PageRenderTime 19ms CodeModel.GetById 11ms app.highlight 3ms RepoModel.GetById 2ms app.codeStats 0ms


XML | 406 lines | 397 code | 6 blank | 3 comment | 0 complexity | 13dc8f5498070ce06fa5a69e93467131 MD5 | raw file
  1<!-- jEdit buffer-local properties: -->
  2<!-- :tabSize=1:indentSize=1:noTabs=true: -->
  3<!-- :xml.root=users-guide.xml: -->
  5<chapter id="starting"><title>Starting jEdit</title>
  6 <sect1 id="conventions"><title>Conventions</title>
  7  <para>
  8   Several conventions are used throughout jEdit's user interface and
  9   this manual. They will be described here. Macintosh users should note how their modifier keys map to the terms used in the manual.
 10  </para>
 11  <informaltable>
 12   <tgroup cols="2">
 13   <tbody>
 14   <row>
 15   <entry>
 16   <guimenu>View</guimenu>&gt;<guisubmenu>Scrolling</guisubmenu>&gt;<guimenuitem>Scroll
 17   to Current Line</guimenuitem>
 18   </entry>
 19   <entry>
 20   The <guimenuitem>Scroll to Current
 21   Line</guimenuitem> command contained in the
 22   <guisubmenu>Scrolling</guisubmenu> submenu of the <guimenu>View</guimenu> menu.
 23   </entry>
 24   </row>
 25   <row>
 26   <entry>
 27   <guimenu>Edit</guimenu>&gt;<guimenuitem>Go to Line...</guimenuitem>
 28   </entry>
 29   <entry>
 30   Menu items that end with
 31   ellipsis (...) display dialog boxes.
 32   </entry>
 33   </row>
 34   <row>
 35   <entry><keycap>Control</keycap> or <keycap>C</keycap></entry>
 36   <entry>
 37    The primary modifier key in jEdit. On MacOS X, this is actually the
 38    key known as <quote>Command</quote>. On most other keyboards, this key is
 39    labelled <quote>Control</quote>.
 40   </entry>
 41   </row>
 42   <row>
 43   <entry><keycap>Alt</keycap> or <keycap>A</keycap></entry>
 44   <entry>
 45    The secondary modifier key in jEdit. On MacOS X, this is actually the
 46    key labelled <quote>Control</quote>. On most other keyboards, this key is
 47    labelled <quote>Alt</quote>.
 48   </entry>
 49   </row>
 50   <row>
 51   <entry><keycap>Shift</keycap> or <keycap>S</keycap></entry>
 52   <entry>The standard <quote>Shift</quote> key.
 53   </entry>
 54   </row>
 55   <row>
 56   <entry>
 57   <keycombo><keycap>Control</keycap><keycap>O</keycap></keycombo>
 58   </entry>
 59   <entry>
 60   Refers to pressing and holding the <keycap>Control</keycap> key, pressing and releasing <keycap>O</keycap>, and finally releasing the <keycap>Control</keycap> key again.
 61   </entry>
 62   </row>
 63   <row>
 64   <entry>
 65   <keycombo><keycap>Control</keycap><keycap>E</keycap></keycombo>
 66   <keycombo><keycap>Control</keycap><keycap>J</keycap></keycombo>
 67   </entry>
 68   <entry>
 69   Command shortcuts can consist of more than one keypress. To invoke the command with the example shortcut above,
 70   press <keycombo><keycap>Control</keycap><keycap>E</keycap></keycombo>, and follow it with
 71   <keycombo><keycap>Control</keycap><keycap>J</keycap></keycombo>.
 72   </entry>
 73   </row>
 74   <row>
 75   <entry>
 76   Default buttons
 77   </entry>
 78   <entry>
 79   In many dialog boxes, the default button (it has a heavy outline, or a
 80   special border, depending on the current Swing look and feel) can be activated by
 81   pressing <keycap>Enter</keycap>. Similarly, pressing
 82   <keycap>Escape</keycap> will usually close a dialog box.
 83   </entry>
 84   </row>
 85   <row>
 86   <entry>
 87   <keycap>Alt</keycap>-key mnemonics
 88   </entry>
 89   <entry>
 90   Some user interface elements (menus, menu items, buttons) have a
 91   certain letter in their label underlined. Pressing this letter in combination
 92   with the <keycap>Alt</keycap> key activates the associated user interface
 93   widget. Note that this functionality is not available on MacOS X with the <quote>MacOS Adaptive</quote> look and feel. See <xref linkend="appearance-pane" /> for information on chang,ing the look and feel.
 94   </entry>
 95   </row>
 96   <row>
 97   <entry>
 98   Right mouse button
 99   </entry>
100   <entry>
101   Used in jEdit to show context-sensitive menus. If you have a one button Macintosh mouse, a <keycap>Control</keycap>-click has the same effect.
102   </entry>
103   </row>
104   <row>
105   <entry>
106   Middle mouse button
107   </entry>
108   <entry>
109   Used by the quick copy feature (see <xref linkend="quick-copy"/>). On a Macintosh with a one or two button mouse, <keycap>Option</keycap>-click. On other platforms with a one or two button mouse, <keycap>Alt</keycap>-click.
110   </entry>
111   </row>
112   </tbody>
113   </tgroup>
114  </informaltable>
115 </sect1>
116 <sect1 id="starting-any-os"><title>Platform-Independent Instructions</title>
117  <para>
118   Exactly how jEdit is started depends on the operating system. For example, on Unix you can run <quote>jedit</quote> at the command line,
119   or select jEdit from a menu; on Windows, you can
120   use the jEditLauncher package, which is documented in
121   <xref linkend="starting-windows" />.
122  </para>
123  <para>
124   If jEdit is started while another copy is already running, control is
125   transferred to the running copy, and a second instance is not loaded.
126   This saves time and memory if jEdit is started multiple times.
127   Communication between instances of jEdit is implemented using
128   TCP/IP sockets; the initial instance is known as the
129   <firstterm>server</firstterm>, and subsequent invocations are
130   <firstterm>clients</firstterm>.
131  </para>
132  <para>
133   If the <userinput>-background</userinput> command line switch is specified,
134   jEdit will continue running and waiting for client requests even
135   after all editor windows are closed. When run in background mode,
136   you can open and close jEdit any number of times, only having
137   to wait for it to start the first time. The downside of this
138   is that jEdit will continue to consume memory when no windows
139   are open.
140  </para>
141  <para>
142   When running on MacOS X, the <userinput>-background</userinput> command-line switch is active by default, so that jEdit conforms to the platform convention that programs should stay open until the <guimenuitem>Quit</guimenuitem> command is explicitly invoked by the user, even if all windows are closed. To disable background mode on MacOS X, use the <userinput>-nobackground</userinput> switch.
143  </para>
144  <para>
145   For more information about command line switches that control the
146   server feature, see <xref linkend="cli-usage" />.
147   Note that if you are using <application>jEditLauncher</application>
148   to start jEdit on Windows, this switch cannot be specified on the
149   MS-DOS prompt command line when starting jEdit; it must be set as described
150   in <xref linkend="launcher-starting" />.
151  </para>
152  <para>
153   jEdit remembers open buffers, views and split window configurations between editing sessions, so you can get back to work immediately after starting jEdit. This feature can be
154   disabled in the <guibutton>General</guibutton> pane of the
155   <guimenu>Utilities</guimenu>&gt;<guimenuitem>Global Options</guimenuitem>
156   dialog box see <xref linkend="general-pane" />.
157  </para>
158  <sidebar><title>The edit server and security</title>
159   <para>
160    Not only does the server pick a random TCP port number on startup,
161    it also requires that clients provide an <firstterm>authorization
162    key</firstterm>; a randomly-generated number only accessible to
163    processes running on the local machine.
164    So not only will <quote>bad guys</quote> have to guess a 64-bit integer,
165    they will need to get it right on the first try; the edit server
166    shuts itself off upon receiving an invalid packet.
167   </para>
168   <para>
169    In environments that demand absolute security, the edit server can be
170    disabled by specifying the <userinput>-noserver</userinput> command line switch.
171   </para>
172  </sidebar>
173 </sect1>
174 <sect1 id="starting-windows"><title>Starting jEdit on Windows</title>
175  <para>
176   On Windows, jEdit comes with <emphasis>jEditLauncher</emphasis> - an optional
177   package of components that make it easy to start jEdit, manage its command
178   line settings, and launch files and macro scripts.
179  </para>
181  <para>
182   The jEditLauncher package provides three shortcuts for running jEdit:  one in
183   the desktop's <guilabel>Start</guilabel> menu, a entry in the Programs menu, and
184   a third shortcut on your desktop.  Any of these may be deleted or moved without
185   affecting jEdit's operation.  To launch jEdit, simply select one of these shortcuts
186   as you would for any Windows application.
187  </para>
189  <para>
190   The jEditLauncher package includes a utility for changing the command line
191   parameters that are stored with jEditLauncher and used every time it runs jEdit.
192   You can change the Java interpreter used to launch jEdit, the amount of heap memory,
193   the working directory and other command line parameters.  To make these changes,
194   select <guilabel>Set jEdit Parameters</guilabel> from the jEdit group in
195   the Programs menu, or run <userinput>jedit /p</userinput> from a command
196   line that has jEdit's installation directory in its search path.  A dialog
197   will appear that allows you to change and save a new set of command line
198   parameters.
199  </para>
201  <para>
202   The package also adds menu items to the context or <quote>right-click</quote>
203   menu displayed by the Windows shell when you click on a file item in the
204   desktop window, a Windows Explorer window or a standard file selection dialog.
205   The menu entries allow  you to open selected files in jEdit, starting the
206   application if necessary. It will also allow you to open all files in a
207   directory with a given extension with a single menu selection. If a BeanShell
208   macro script with a <filename>.bsh</filename> extension is selected, the menu
209   includes the option of running that script within jEdit. If you have the
210   <application>JDiff</application> plugin installed with jEdit, you can also
211   select two files and have jEdit compare them in a side-by-side graphical display.
212  </para>
214  <para>
215   For a more detailed description of all features found in
216   the jEditLauncher package, see <xref linkend="launcher-guide"/>.
217  </para>
218 </sect1>
220 <sect1 id="cli-usage"><title>Command Line Usage</title>
221  <para>
222   On operating systems that support a command line, jEdit can be passed
223   various arguments to control its behavior.
224  </para>
225  <para>
226   If you are using <application>jEditLauncher</application>
227   to start jEdit on Windows, only file names can be specified
228   on the command line; the parameters documented below must be set as described
229   in <xref linkend="launcher-starting" />.
230  </para>
231  <para>
232   When opening files from the command line, a line number or marker to
233   position the caret on can be specified like so:
234  </para>
235  <screen><prompt>$ </prompt><userinput>jedit +line:10</userinput>
236<prompt>$ </prompt><userinput>jedit thesis.tex +marker:c</userinput></screen>
237  <para>
238   Command-line switches begin with a "-". Some take a parameter. A file whose name
239   begins with "-" can be opened like so:
240  </para>
241  <screen><prompt>$ </prompt><userinput>jedit -- -myfile</userinput></screen>
242  <sect2><title>Miscellaneous Options</title>
243  <informaltable>
244   <tgroup cols="2">
245    <colspec colnum="1" colwidth="1.5in" />
246    <thead>
247     <row><entry>Option</entry><entry>Effect</entry></row>
248    </thead>
249    <tbody>
250     <row>
251      <entry><userinput>-log=<replaceable>level</replaceable></userinput></entry>
252      <entry>Set the minimum log level to an integer between 1 and 9. Default is 7.
253      Has no effect when connecting to 
254      another instance via the edit server.</entry>
255     </row>
256     <row>
257      <entry><userinput>-usage</userinput></entry>
258      <entry>Show a brief command line usage message without starting
259      jEdit.
260      This message is also shown if an invalid switch was specified.</entry>
261     </row>
262     <row>
263      <entry><userinput>-version</userinput></entry>
264      <entry>Show the version number without starting jEdit.</entry>
265     </row>
266     <row>
267      <entry><userinput>- -</userinput></entry>
268      <entry>Specifies the end of command-line processing. Further parameters are treated
269      as file names, even if they begin with a dash.
270      </entry>
271     </row>
272    </tbody>
273   </tgroup>
274  </informaltable>
275  </sect2>
276  <sect2><title>Configuration Options</title>
277   <informaltable>
278   <tgroup cols="2">
279    <colspec colnum="1" colwidth="1.5in" />
280    <thead>
281     <row><entry>Option</entry><entry>Effect</entry></row>
282    </thead>
283    <tbody>
284     <row>
285      <entry><userinput>-plugins</userinput></entry>
286      <entry>Enable loading of plugins. Has no effect
287      when connecting to another instance via the edit server.
288      See <xref linkend="using-plugins" />.</entry>
289     </row>
290     <row>
291      <entry><userinput>-noplugins</userinput></entry>
292      <entry>Disable loading of plugins. Has no effect
293      when connecting to another instance via the edit server.</entry>
294     </row>
295    <row>
296      <entry><userinput>-restore</userinput></entry>
297      <entry>Restore previously open files on startup. This is the default.
298      This feature can also be set permanently in the
299      <guibutton>General</guibutton> pane of the
300      <guimenu>Utilities</guimenu>&gt;<guimenuitem>Global Options</guimenuitem>
301      dialog box; see <xref linkend="general-pane" />.
302      </entry>
303     </row>
304    <row>
305      <entry><userinput>-norestore</userinput></entry>
306      <entry>Do not restore previously open files on startup.
307      </entry>
308     </row>
309     <row>
310      <entry><userinput>-run=<replaceable>script</replaceable></userinput></entry>
311      <entry>Run the specified BeanShell script. There can only be one
312      of these parameters on the command line. See
313      <xref linkend="scripts-command-line" />.</entry>
314     </row>
315     <row>
316      <entry><userinput>-settings=<replaceable>dir</replaceable></userinput></entry>
317      <entry>Store user-specific settings in
318      the directory named <replaceable>dir</replaceable>, instead of the
319      default <filename><replaceable>user.home</replaceable>/.jedit</filename>.
320      The directory will be created automatically if it does not exist. Has no
321      effect when connecting to another instance via the edit server.
322      See <xref linkend="settings-directory"/>.</entry>
323     </row>
324     <row>
325      <entry><userinput>-nosettings</userinput></entry>
326      <entry>Start jEdit without loading user-specific settings.</entry>
327     </row>
328     <row>
329      <entry><userinput>-startupscripts</userinput></entry>
330      <entry>Run startup scripts. This is the default.
331      Has no effect
332      when connecting to another instance via the edit server.
333      See <xref linkend="startup-scripts" />.</entry>
334     </row>
335     <row>
336      <entry><userinput>-nostartupscripts</userinput></entry>
337      <entry>Disable startup scripts.
338      Has no effect
339      when connecting to another instance via the edit server.</entry>
340     </row>
341    </tbody>
342   </tgroup>
343   </informaltable>
344  </sect2>
345  <sect2><title>Edit Server Options</title>
346   See <xref linkend="starting-any-os" /> for a brief description of the edit server.
347   <informaltable>
348   <tgroup cols="2">
349    <colspec colnum="1" colwidth="1.5in" />
350    <thead>
351     <row><entry>Option</entry><entry>Effect</entry></row>
352    </thead>
353    <tbody>
354    <row>
355      <entry><userinput>-background</userinput></entry>
356      <entry>Run jEdit in background mode. In background mode,
357      the edit server will continue listening for
358      client connections even after all views are closed. Has no effect
359      when connecting to another instance via the edit server.</entry>
360     </row>
361    <row>
362      <entry><userinput>-nobackground</userinput></entry>
363      <entry>Disable background mode. This is the default.
364      Has no effect when connecting to 
365      another instance via the edit server.</entry>
366     </row>
367     <row>
368      <entry><userinput>-gui</userinput></entry>
369      <entry>Open an initial view. This is the
370      default. Has no effect when connecting to 
371      another instance via the edit server.
372      </entry>
373     </row>
374     <row>
375      <entry><userinput>-nogui</userinput></entry>
376      <entry>Do not open an initial view, and instead only open one
377      when the first client connects. Can only be used in combination with
378      the <userinput>-background</userinput> switch. You can use this switch to
379      <quote>pre-load</quote> jEdit when you log in to your computer, for
380      example. Has no effect when connecting to 
381      another instance via the edit server.
382      </entry>
383     </row>
384     <row>
385      <entry><userinput>-server</userinput></entry>
386      <entry>Store the server port info in the file named <filename>server</filename>
387      inside the settings directory.</entry>
388     </row>
389     <row>
390      <entry><userinput>-server=<replaceable>name</replaceable></userinput></entry>
391      <entry>Store the server port info in the file named
392      <replaceable>name</replaceable>. File names for this
393      parameter are relative to the settings directory.</entry>
394     </row>
395     <row>
396      <entry><userinput>-noserver</userinput></entry>
397      <entry>Do not attempt to
398      connect to a running edit server, and do not start one either.
399      </entry>
400     </row>
401    </tbody>
402   </tgroup>
403   </informaltable>
404  </sect2>
405 </sect1>