PageRenderTime 79ms CodeModel.GetById 68ms app.highlight 6ms RepoModel.GetById 1ms app.codeStats 0ms


XML | 300 lines | 292 code | 6 blank | 2 comment | 0 complexity | 75b947f924a6714fd292c089d204f732 MD5 | raw file
  1<!-- jEdit buffer-local properties: -->
  2<!-- :tabSize=1:indentSize=1:noTabs=true: -->
  4<chapter id="starting"><title>Starting jEdit</title>
  5 <sect1 id="conventions"><title>Conventions</title>
  6  <para>
  7   Several conventions are used throughout jEdit's user interface and
  8   this manual. They will be described here.
  9  </para>
 10  <para>
 11   When a menu item selection is being described, the
 12   top level menu is listed first, followed by successive levels of submenus,
 13   finally followed by the menu item itself. All menu components are separated
 14   by greater-than symbols (<quote>&gt;</quote>). For example,
 15   <guimenu>View</guimenu>&gt;<guisubmenu>Scrolling</guisubmenu>&gt;<guimenuitem>Scroll
 16   to Current Line</guimenuitem> refers to the <guimenuitem>Scroll to Current
 17   Line</guimenuitem> command contained in the
 18   <guisubmenu>Scrolling</guisubmenu> submenu of the <guimenu>View</guimenu> menu.
 19  </para>
 20  <para>
 21   As with many other applications, menu items that end with
 22   ellipsis (...) display dialog boxes or windows when invoked.
 23  </para>
 24  <para>
 25   Many jEdit commands can be also be invoked using keystrokes. This speeds
 26   up editing by letting you keep your hands on the keyboard. Not all
 27   commands with keyboard shortcuts
 28   are accessible with one key stroke; for example, the
 29   keyboard shortcut for <guimenuitem>Scroll to Current Line</guimenuitem> is
 30   <keycombo><keycap>Control</keycap><keycap>E</keycap></keycombo>
 31   <keycombo><keycap>Control</keycap><keycap>J</keycap></keycombo>. That is, you
 32   must first
 33   press <keycombo><keycap>Control</keycap><keycap>E</keycap></keycombo>, followed by
 34   <keycombo><keycap>Control</keycap><keycap>J</keycap></keycombo>.
 35  </para>
 36  <para>
 37   In many dialog boxes, the default button (it has a heavy outline, or a
 38   special border, depending on the current Swing look and feel) can be activated by
 39   pressing <keycap>Enter</keycap>. Similarly, pressing
 40   <keycap>Escape</keycap> will usually close a dialog box.
 41  </para>
 42  <para>
 43   Finally, some user interface elements (menus, menu items, buttons) have a
 44   certain letter in their label underlined. Pressing this letter in combination
 45   with the <keycap>Alt</keycap> key activates the associated user interface
 46   widget.
 47  </para>
 48  <sidebar><title>MacOS</title>
 49   <para>
 50    jEdit tries to adapt itself to established conventions when running on
 51    MacOS.
 52   </para>
 53   <para>
 54    If you are using MacOS, mentally substitute the modifier keys you see in
 55    this manual as follows:
 56   </para>
 57   <itemizedlist>
 58    <listitem><para>Read <keycap>Control</keycap> as <keycap>Command</keycap>
 59    </para></listitem>
 60    <listitem><para>Read <keycap>Alt</keycap> as <keycap>Option</keycap>
 61    </para></listitem>
 62   </itemizedlist>
 63   <para>
 64    If you only have a one-button mouse, a right button click (to show a
 65    context menu, and so on) can be simulated by holding down
 66    <keycap>Control</keycap> while clicking. A middle button click (to insert
 67    the most recent selection in the text area) can be simulated by
 68    holding down <keycap>Option</keycap> while clicking.
 69   </para>
 70  </sidebar>
 71 </sect1>
 72 <sect1 id="starting-any-os"><title>Platform-Independent Instructions</title>
 73  <para>
 74   Exactly how jEdit is started depends on the operating system;
 75   on Unix systems, usually you would
 76   run the <quote>jedit</quote> command at the command line,
 77   or select jEdit from a menu; on Windows, you might
 78   use the jEditLauncher package, which is documented in
 79   <xref linkend="starting-windows" />.
 80  </para>
 81  <para>
 82   If jEdit is started while another copy is already running, control is
 83   transferred to the running copy, and a second instance is not loaded.
 84   This saves time and memory if jEdit is started multiple times.
 85   Communication between instances of jEdit is implemented using
 86   TCP/IP sockets; the initial instance is known as the
 87   <firstterm>server</firstterm>, and subsequent invocations are
 88   <firstterm>clients</firstterm>.
 89  </para>
 90  <para>
 91   If the <command>-background</command> command line switch is specified,
 92   jEdit will continue running and waiting for client requests even
 93   after all editor windows are closed. When run in background mode,
 94   you can open and close jEdit any number of times, only having
 95   to wait for it to start the first time. The downside of this
 96   is that jEdit will continue to consume memory when no windows
 97   are open.
 98  </para>
 99  <para>
100   For more information about command line switches that control the
101   server feature, see <xref linkend="cli-usage" />.
102   Note that if you are using <application>jEditLauncher</application>
103   to start jEdit on Windows, this switch cannot be specified on the
104   MS-DOS prompt command line when starting jEdit; it must be set as described
105   in <xref linkend="launcher-starting" />.
106  </para>
107  <para>
108   Unlike other applications, jEdit automatically loads any files that were
109   open last time in was used, so you can get back to work immediately, without
110   having to find the files you are working on first. This feature can be
111   disabled in the <guibutton>Loading and Saving</guibutton> pane of the
112   <guimenu>Utilities</guimenu>&gt;<guimenuitem>Global Options</guimenuitem>
113   dialog box; see <xref linkend="global-opts" />.
114  </para>
115  <sidebar><title>The edit server and security</title>
116   <para>
117    Not only does the server pick a random TCP port number on startup,
118    it also requires that clients provide an <firstterm>authorization
119    key</firstterm>; a randomly-generated number only accessible to
120    processes running on the local machine.
121    So not only will <quote>bad guys</quote> have to guess a 64-bit integer,
122    they will need to get it right on the first try; the edit server
123    shuts itself off upon receiving an invalid packet.
124   </para>
125   <para>
126    In environments that demand absolute security, the edit server can be
127    disabled by specifying the <command>-noserver</command> command line switch.
128   </para>
129  </sidebar>
130 </sect1>
131 <sect1 id="starting-windows"><title>Starting jEdit on Windows</title>
132  <para>
133   On Windows, jEdit comes with <emphasis>jEditLauncher</emphasis> - an optional
134   package of components that make it easy to start jEdit, manage its command
135   line settings, and launch files and macro scripts.
136  </para>
138  <para>
139   The jEditLauncher package provides three shortcuts for running jEdit:  one in
140   the desktop's <guilabel>Start</guilabel> menu, a entry in the Programs menu, and
141   a third shortcut on your desktop.  Any of these may be deleted or moved without
142   affecting jEdit's operation.  To launch jEdit, simply select one of these shortcuts
143   as you would for any Windows application.
144  </para>
146  <para>
147   The jEditLauncher package includes a utility for changing the command line
148   parameters that are stored with jEditLauncher and used every time it runs jEdit.
149   You can change the Java interpreter used to launch jEdit, the amount of heap memory,
150   the working directory and other command line parameters.  To make these changes,
151   select <guilabel>Set jEdit Parameters</guilabel> from the jEdit group in
152   the Programs menu, or run <userinput>jedit /p</userinput> from a command
153   line that has jEdit's installation directory in its search path.  A dialog
154   will appear that allows you to change and save a new set of command line
155   parameters.
156  </para>
158  <para>
159   The package also adds menu items to the context or <quote>right-click</quote>
160   menu displayed by the Windows shell when you click on a file item in the
161   desktop window, a Windows Explorer window or a standard file selection dialog.
162   The menu entries allow  you to open selected files in jEdit, starting the
163   application if necessary. It will also allow you to open all files in a
164   directory with a given extension with a single menu selection. If a BeanShell
165   macro script with a <filename>.bsh</filename> extension is selected, the menu
166   includes the option of running that script within jEdit. If you have the
167   <application>JDiff</application> plugin installed with jEdit, you can also
168   select two files and have jEdit compare them in a side-by-side graphical display.
169  </para>
171  <para>
172   For a more detailed description of all features found in
173   the jEditLauncher package, see <xref linkend="launcher-guide"/>.
174  </para>
175 </sect1>
177 <sect1 id="cli-usage"><title>Command Line Usage</title>
178  <para>
179   On operating systems that support a command line, jEdit can be passed
180   various arguments to control its behavior.
181  </para>
182  <para>
183   If you are using <application>jEditLauncher</application>
184   to start jEdit on Windows, only file names can be specified
185   on the command line; the parameters documented below must be set as described
186   in <xref linkend="launcher-starting" />.
187  </para>
188  <para>
189   When opening files from the command line, a line number or marker to
190   position the caret on can be specified like so:
191  </para>
192  <screen><prompt>$ </prompt><userinput>jedit +line:10</userinput>
193<prompt>$ </prompt><userinput>jedit thesis.tex +marker:c</userinput></screen>
194  <para>
195   A number of options can also be specified to control several obscure features.
196   They are listed in the following table.
197  </para>
198  <informaltable>
199   <tgroup cols="2">
200    <colspec colnum="1" colwidth="1.5in" />
201    <thead>
202     <row><entry>Option</entry><entry>Description</entry></row>
203    </thead>
204    <tbody>
205     <row>
206      <entry><command>-background</command></entry>
207      <entry>Runs jEdit in background mode. In background mode,
208      the edit server will continue listening for
209      client connections even after all views are closed.
210      See <xref linkend="starting" />.</entry>
211     </row>
212     <row>
213      <entry><command>-nogui</command></entry>
214      <entry>Makes jEdit not open an initial view, and instead only open one
215      when the first client connects. Can only be used in combination with
216      the <command>-background</command> switch. You can use this switch to
217      <quote>pre-load</quote> jEdit when you log in to your computer, for
218      example.
219      </entry>
220     </row>
221     <row>
222      <entry><command>-norestore</command></entry>
223      <entry>Disables automatic restore of previously open files on
224      startup. This feature can also be set permanently in the
225      <guibutton>Loading and Saving</guibutton> pane of the
226      <guimenu>Utilities</guimenu>&gt;<guimenuitem>Global Options</guimenuitem>
227      dialog box; see <xref linkend="global-opts" />.
228      </entry>
229     </row>
230     <row>
231      <entry><command>-run=<replaceable>script</replaceable></command></entry>
232      <entry>Runs the specified BeanShell script. There can only be one
233      of these parameters on the command line. See
234      <xref linkend="scripts-command-line" /> for details.</entry>
235     </row>
236     <row>
237      <entry><command>-server</command></entry>
238      <entry>Stores the server port info in the file named <filename>server</filename>
239      inside the settings directory.</entry>
240     </row>
241     <row>
242      <entry><command>-server=<replaceable>name</replaceable></command></entry>
243      <entry>Stores the server port info in the file named
244      <replaceable>name</replaceable>. File names for this
245      parameter are relative to the settings directory.</entry>
246     </row>
247     <row>
248      <entry><command>-noserver</command></entry>
249      <entry>Does not attempt to
250      connect to a running edit server, and does not start one either. For
251      information about the edit server, see <xref linkend="starting" />.</entry>
252     </row>
253     <row>
254      <entry><command>-settings=<replaceable>dir</replaceable></command></entry>
255      <entry>Loads and saves the user-specific settings in
256      the directory named <replaceable>dir</replaceable>, instead of the
257      default <filename><replaceable>user.home</replaceable>/.jedit</filename>.
258      The directory will be created automatically if it does not exist. Has no
259      effect when connecting to another instance via the edit server.</entry>
260     </row>
261     <row>
262      <entry><command>-nosettings</command></entry>
263      <entry>Starts jEdit without loading user-specific settings.
264      See <xref linkend="settings-directory" />.</entry>
265     </row>
266     <row>
267      <entry><command>-noplugins</command></entry>
268      <entry>Causes jEdit to not load any plugins.
269      See <xref linkend="using-plugins" />. Has no effect
270      when connecting to another instance via the edit server.</entry>
271     </row>
272     <row>
273      <entry><command>-nostartupscripts</command></entry>
274      <entry>Causes jEdit to not run any startup scripts.
275      See <xref linkend="startup-scripts" />.
276      Has no effect
277      when connecting to another instance via the edit server.</entry>
278     </row>
279     <row>
280      <entry><command>-usage</command></entry>
281      <entry>Shows a brief command line usage message without starting
282      jEdit.
283      This message is also shown if an invalid switch was specified.</entry>
284     </row>
285     <row>
286      <entry><command>-version</command></entry>
287      <entry>Shows the version number without starting jEdit.</entry>
288     </row>
289     <row>
290      <entry><command>- -</command></entry>
291      <entry>Specifies the end of the command line switches. Further
292      parameters are treated as file names, even if they begin with
293      a dash. Can be used to open files whose names start with a
294      dash, and so on.</entry>
295     </row>
296    </tbody>
297   </tgroup>
298  </informaltable>
299 </sect1>