The Tor Browser / file comparison

comparison: toolkit/devtools/gcli/source/docs/index.md

toolkit/devtools/gcli/source/docs/index.md

changeset 0
6474c204b198
equal deleted inserted replaced
-1:000000000000 0:4bc21bdf7d05
1
2 # About GCLI
3
4 ## GCLI is a Graphical Command Line Interpreter.
5
6 GCLI is a command line for modern computers. When command lines were invented,
7 computers were resource-limited, disconnected systems with slow multi-tasking
8 and poor displays. The design of the Unix CLI made sense in 1970, but over 40
9 years on, considering the pace of change, there are many improvements we can
10 make.
11
12 CLIs generally suffer from poor discoverability; It's hard when faced with a
13 blank command line to work out what to do. As a result the majority of programs
14 today use purely graphical user interfaces, however in doing so, they lose some
15 of the benefits of CLIs. CLIs are still used because generally, in the hands of
16 a skilled user they are faster, and have a wider range of available options.
17
18 GCLI attempts to get the best of the GUI world and the CLI world to produce
19 something that is both easy to use and learn as well as fast and powerful.
20
21 GCLI has a type system to help ensure that users are inputting valid commands
22 and to enable us to provide sensible context sensitive help. GCLI provides
23 integration with JavaScript rather than being an alternative (like CoffeeScript).
24
25
26 ## History
27
28 GCLI was born as part of the
29 [Bespin](http://ajaxian.com/archives/canvas-for-a-text-editor) project and was
30 [discussed at the time](http://j.mp/bespin-cli). The command line component
31 survived the rename of Bepsin to Skywriter and the merger with Ace, got a name
32 of it's own (Cockpit) which didn't last long before the project was named GCLI.
33 It is now being used in the Firefox's web console where it doesn't have a
34 separate identity but it's still called GCLI outside of Firefox. It is also
35 used in [Eclipse Orion](http://www.eclipse.org/orion/).
36
37
38 ## Environments
39
40 GCLI is designed to work in a number of environments:
41
42 1. As a component of Firefox developer tools.
43 2. As an adjunct to Orion/Ace and other online editors.
44 3. As a plugin to any web-page wishing to provide its own set of commands.
45 4. As part of a standalone web browser extension with it's own set of commands.
46
47
48 ## Related Pages
49
50 Other sources of GCLI documentation:
51
52 - [Writing Commands](writing-commands.md)
53 - [Writing Types](writing-types.md)
54 - [Developing GCLI](developing-gcli.md)
55 - [Writing Tests](writing-tests.md) / [Running Tests](running-tests.md)
56 - [The Design of GCLI](design.md)
57 - Source
58 - The most up-to-date source is in [this Github repository](https://github.com/joewalker/gcli/).
59 - When a feature is 'done' it's merged into the [Mozilla clone](https://github.com/mozilla/gcli/).
60 - From which it flows into [Mozilla Central](https://hg.mozilla.org/mozilla-central/file/tip/browser/devtools/commandline).
61 - [Demo of GCLI](http://mozilla.github.com/gcli/) with an arbitrary set of demo
62 commands
63 - Other Documentation
64 - [Embedding docs](https://github.com/mozilla/gcli/blob/master/docs/index.md)
65 - [Status page](http://mozilla.github.com/devtools/2011/status.html#gcli)
66
67
68 ## Accessibility
69
70 GCLI uses ARIA roles to guide a screen-reader as to the important sections to
71 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).
72
73 The command line uses TAB as a method of completing current input, this
74 prevents use of TAB for keyboard navigation. Instead of using TAB to move to
75 the next field you can use F6. In addition to F6, ALT+TAB, CTRL+TAB, META+TAB
76 make an attempt to move the focus on. How well this works depends on your
77 OS/browser combination.
78
79
80 ## Embedding GCLI
81
82 There are 3 basic steps in using GCLI in your system.
83
84 1. Import a GCLI JavaScript file.
85 For serious use of GCLI you are likely to be creating a custom build (see
86 below) however if you just want to have a quick play, you can use
87 ``gcli-uncompressed.js`` from [the gh-pages branch of GCLI]
88 (https://github.com/mozilla/gcli/tree/gh-pages)
89 Just place the following wherever you place your script files.
90
91 <script src="path/to/gcli-uncompressed.js" type="text/javascript"></script>
92
93 2. Having imported GCLI, we need to tell it where to display. The simplest
94 method is to include an elements with the id of ``gcli-input`` and
95 ``gcli-display``.
96
97 <input id="gcli-input" type="text"/>
98 <div id="gcli-display"></div>
99
100 3. Tell GCLI what commands to make available. See the sections on Writing
101 Commands, Writing Types and Writing Fields for more information.
102
103 GCLI uses the CommonJS AMD format for it's files, so a 'require' statement
104 is needed to get started.
105
106 require([ 'gcli/index' ], function(gcli) {
107 gcli.addCommand(...); // Register custom commands
108 gcli.createTerminal(); // Create a user interface
109 });
110
111 The createTerminal() function takes an ``options`` objects which allows
112 customization. At the current time the documentation of these object is left
113 to the source.
114
115
116 ## Backwards Compatibility
117
118 The goals of the GCLI project are:
119
120 - Aim for very good backwards compatibility with code required from an
121 'index' module. This means we will not break code without a cycle of
122 deprecation warnings.
123
124 There are currently 3 'index' modules:
125 - gcli/index (all you need to get started with GCLI)
126 - demo/index (a number of demo commands)
127 - gclitest/index (GCLI test suite)
128
129 Code from these modules uses the module pattern to prevent access to internal
130 functions, so in essence, if you can get to it from an index module, you
131 should be ok.
132
133 - We try to avoid needless change to other modules, however we don't make any
134 promises, and don't provide a deprecation cycle.
135
136 Code from other modules uses classes rather than modules, so member variables
137 are exposed. Many classes mark private members using the `_underscorePrefix`
138 pattern. Particular care should be taken if access is needed to a private
139 member.
140
141
142 ## Creating Custom Builds
143
144 GCLI uses [DryIce](https://github.com/mozilla/dryice) to create custom builds.
145 If dryice is installed (``npm install .``) then you can create a built
146 version of GCLI simply using ``node gcli.js standard``. DryIce supplies a custom
147 module loader to replace RequireJS for built applications.
148
149 The build will be output to the ``built`` directory. The directory will be
150 created if it doesn't exist.

Mercurial Repository: The Tor Browser

Europalab SCM Repository Server

mercurial