1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/toolkit/devtools/gcli/source/docs/index.md Wed Dec 31 06:09:35 2014 +0100
1.3 @@ -0,0 +1,150 @@
1.4 +
1.5 +# About GCLI
1.6 +
1.7 +## GCLI is a Graphical Command Line Interpreter.
1.8 +
1.9 +GCLI is a command line for modern computers. When command lines were invented,
1.10 +computers were resource-limited, disconnected systems with slow multi-tasking
1.11 +and poor displays. The design of the Unix CLI made sense in 1970, but over 40
1.12 +years on, considering the pace of change, there are many improvements we can
1.13 +make.
1.14 +
1.15 +CLIs generally suffer from poor discoverability; It's hard when faced with a
1.16 +blank command line to work out what to do. As a result the majority of programs
1.17 +today use purely graphical user interfaces, however in doing so, they lose some
1.18 +of the benefits of CLIs. CLIs are still used because generally, in the hands of
1.19 +a skilled user they are faster, and have a wider range of available options.
1.20 +
1.21 +GCLI attempts to get the best of the GUI world and the CLI world to produce
1.22 +something that is both easy to use and learn as well as fast and powerful.
1.23 +
1.24 +GCLI has a type system to help ensure that users are inputting valid commands
1.25 +and to enable us to provide sensible context sensitive help. GCLI provides
1.26 +integration with JavaScript rather than being an alternative (like CoffeeScript).
1.27 +
1.28 +
1.29 +## History
1.30 +
1.31 +GCLI was born as part of the
1.32 +[Bespin](http://ajaxian.com/archives/canvas-for-a-text-editor) project and was
1.33 +[discussed at the time](http://j.mp/bespin-cli). The command line component
1.34 +survived the rename of Bepsin to Skywriter and the merger with Ace, got a name
1.35 +of it's own (Cockpit) which didn't last long before the project was named GCLI.
1.36 +It is now being used in the Firefox's web console where it doesn't have a
1.37 +separate identity but it's still called GCLI outside of Firefox. It is also
1.38 +used in [Eclipse Orion](http://www.eclipse.org/orion/).
1.39 +
1.40 +
1.41 +## Environments
1.42 +
1.43 +GCLI is designed to work in a number of environments:
1.44 +
1.45 +1. As a component of Firefox developer tools.
1.46 +2. As an adjunct to Orion/Ace and other online editors.
1.47 +3. As a plugin to any web-page wishing to provide its own set of commands.
1.48 +4. As part of a standalone web browser extension with it's own set of commands.
1.49 +
1.50 +
1.51 +## Related Pages
1.52 +
1.53 +Other sources of GCLI documentation:
1.54 +
1.55 +- [Writing Commands](writing-commands.md)
1.56 +- [Writing Types](writing-types.md)
1.57 +- [Developing GCLI](developing-gcli.md)
1.58 +- [Writing Tests](writing-tests.md) / [Running Tests](running-tests.md)
1.59 +- [The Design of GCLI](design.md)
1.60 +- Source
1.61 + - The most up-to-date source is in [this Github repository](https://github.com/joewalker/gcli/).
1.62 + - When a feature is 'done' it's merged into the [Mozilla clone](https://github.com/mozilla/gcli/).
1.63 + - From which it flows into [Mozilla Central](https://hg.mozilla.org/mozilla-central/file/tip/browser/devtools/commandline).
1.64 +- [Demo of GCLI](http://mozilla.github.com/gcli/) with an arbitrary set of demo
1.65 + commands
1.66 +- Other Documentation
1.67 + - [Embedding docs](https://github.com/mozilla/gcli/blob/master/docs/index.md)
1.68 + - [Status page](http://mozilla.github.com/devtools/2011/status.html#gcli)
1.69 +
1.70 +
1.71 +## Accessibility
1.72 +
1.73 +GCLI uses ARIA roles to guide a screen-reader as to the important sections to
1.74 +voice. We welcome [feedback on how these roles are implemented](https://bugzilla.mozilla.org/enter_bug.cgi?product=Firefox&component=Developer+Tools:+Graphic+Commandline+and+Toolbar&rep_platform=All&op_sys=All&short_desc=GCLI).
1.75 +
1.76 +The command line uses TAB as a method of completing current input, this
1.77 +prevents use of TAB for keyboard navigation. Instead of using TAB to move to
1.78 +the next field you can use F6. In addition to F6, ALT+TAB, CTRL+TAB, META+TAB
1.79 +make an attempt to move the focus on. How well this works depends on your
1.80 +OS/browser combination.
1.81 +
1.82 +
1.83 +## Embedding GCLI
1.84 +
1.85 +There are 3 basic steps in using GCLI in your system.
1.86 +
1.87 +1. Import a GCLI JavaScript file.
1.88 + For serious use of GCLI you are likely to be creating a custom build (see
1.89 + below) however if you just want to have a quick play, you can use
1.90 + ``gcli-uncompressed.js`` from [the gh-pages branch of GCLI]
1.91 + (https://github.com/mozilla/gcli/tree/gh-pages)
1.92 + Just place the following wherever you place your script files.
1.93 +
1.94 + <script src="path/to/gcli-uncompressed.js" type="text/javascript"></script>
1.95 +
1.96 +2. Having imported GCLI, we need to tell it where to display. The simplest
1.97 + method is to include an elements with the id of ``gcli-input`` and
1.98 + ``gcli-display``.
1.99 +
1.100 + <input id="gcli-input" type="text"/>
1.101 + <div id="gcli-display"></div>
1.102 +
1.103 +3. Tell GCLI what commands to make available. See the sections on Writing
1.104 + Commands, Writing Types and Writing Fields for more information.
1.105 +
1.106 + GCLI uses the CommonJS AMD format for it's files, so a 'require' statement
1.107 + is needed to get started.
1.108 +
1.109 + require([ 'gcli/index' ], function(gcli) {
1.110 + gcli.addCommand(...); // Register custom commands
1.111 + gcli.createTerminal(); // Create a user interface
1.112 + });
1.113 +
1.114 + The createTerminal() function takes an ``options`` objects which allows
1.115 + customization. At the current time the documentation of these object is left
1.116 + to the source.
1.117 +
1.118 +
1.119 +## Backwards Compatibility
1.120 +
1.121 +The goals of the GCLI project are:
1.122 +
1.123 +- Aim for very good backwards compatibility with code required from an
1.124 + 'index' module. This means we will not break code without a cycle of
1.125 + deprecation warnings.
1.126 +
1.127 + There are currently 3 'index' modules:
1.128 + - gcli/index (all you need to get started with GCLI)
1.129 + - demo/index (a number of demo commands)
1.130 + - gclitest/index (GCLI test suite)
1.131 +
1.132 + Code from these modules uses the module pattern to prevent access to internal
1.133 + functions, so in essence, if you can get to it from an index module, you
1.134 + should be ok.
1.135 +
1.136 +- We try to avoid needless change to other modules, however we don't make any
1.137 + promises, and don't provide a deprecation cycle.
1.138 +
1.139 + Code from other modules uses classes rather than modules, so member variables
1.140 + are exposed. Many classes mark private members using the `_underscorePrefix`
1.141 + pattern. Particular care should be taken if access is needed to a private
1.142 + member.
1.143 +
1.144 +
1.145 +## Creating Custom Builds
1.146 +
1.147 +GCLI uses [DryIce](https://github.com/mozilla/dryice) to create custom builds.
1.148 +If dryice is installed (``npm install .``) then you can create a built
1.149 +version of GCLI simply using ``node gcli.js standard``. DryIce supplies a custom
1.150 +module loader to replace RequireJS for built applications.
1.151 +
1.152 +The build will be output to the ``built`` directory. The directory will be
1.153 +created if it doesn't exist.
