/jEdit/tags/jedit-4-2-pre4/doc/users-guide/starting.xml
XML | 406 lines | 397 code | 6 blank | 3 comment | 0 complexity | 13dc8f5498070ce06fa5a69e93467131 MD5 | raw file
Possible License(s): BSD-3-Clause, AGPL-1.0, Apache-2.0, LGPL-2.0, LGPL-3.0, GPL-2.0, CC-BY-SA-3.0, LGPL-2.1, GPL-3.0, MPL-2.0-no-copyleft-exception, IPL-1.0
- <!-- jEdit buffer-local properties: -->
- <!-- :tabSize=1:indentSize=1:noTabs=true: -->
- <!-- :xml.root=users-guide.xml: -->
- <chapter id="starting"><title>Starting jEdit</title>
- <sect1 id="conventions"><title>Conventions</title>
- <para>
- Several conventions are used throughout jEdit's user interface and
- this manual. They will be described here. Macintosh users should note how their modifier keys map to the terms used in the manual.
- </para>
- <informaltable>
- <tgroup cols="2">
- <tbody>
- <row>
- <entry>
- <guimenu>View</guimenu>><guisubmenu>Scrolling</guisubmenu>><guimenuitem>Scroll
- to Current Line</guimenuitem>
- </entry>
- <entry>
- The <guimenuitem>Scroll to Current
- Line</guimenuitem> command contained in the
- <guisubmenu>Scrolling</guisubmenu> submenu of the <guimenu>View</guimenu> menu.
- </entry>
- </row>
- <row>
- <entry>
- <guimenu>Edit</guimenu>><guimenuitem>Go to Line...</guimenuitem>
- </entry>
- <entry>
- Menu items that end with
- ellipsis (...) display dialog boxes.
- </entry>
- </row>
- <row>
- <entry><keycap>Control</keycap> or <keycap>C</keycap></entry>
- <entry>
- The primary modifier key in jEdit. On MacOS X, this is actually the
- key known as <quote>Command</quote>. On most other keyboards, this key is
- labelled <quote>Control</quote>.
- </entry>
- </row>
- <row>
- <entry><keycap>Alt</keycap> or <keycap>A</keycap></entry>
- <entry>
- The secondary modifier key in jEdit. On MacOS X, this is actually the
- key labelled <quote>Control</quote>. On most other keyboards, this key is
- labelled <quote>Alt</quote>.
- </entry>
- </row>
- <row>
- <entry><keycap>Shift</keycap> or <keycap>S</keycap></entry>
- <entry>The standard <quote>Shift</quote> key.
- </entry>
- </row>
- <row>
- <entry>
- <keycombo><keycap>Control</keycap><keycap>O</keycap></keycombo>
- </entry>
- <entry>
- 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.
- </entry>
- </row>
- <row>
- <entry>
- <keycombo><keycap>Control</keycap><keycap>E</keycap></keycombo>
- <keycombo><keycap>Control</keycap><keycap>J</keycap></keycombo>
- </entry>
- <entry>
- Command shortcuts can consist of more than one keypress. To invoke the command with the example shortcut above,
- press <keycombo><keycap>Control</keycap><keycap>E</keycap></keycombo>, and follow it with
- <keycombo><keycap>Control</keycap><keycap>J</keycap></keycombo>.
- </entry>
- </row>
- <row>
- <entry>
- Default buttons
- </entry>
- <entry>
- In many dialog boxes, the default button (it has a heavy outline, or a
- special border, depending on the current Swing look and feel) can be activated by
- pressing <keycap>Enter</keycap>. Similarly, pressing
- <keycap>Escape</keycap> will usually close a dialog box.
- </entry>
- </row>
- <row>
- <entry>
- <keycap>Alt</keycap>-key mnemonics
- </entry>
- <entry>
- Some user interface elements (menus, menu items, buttons) have a
- certain letter in their label underlined. Pressing this letter in combination
- with the <keycap>Alt</keycap> key activates the associated user interface
- 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.
- </entry>
- </row>
- <row>
- <entry>
- Right mouse button
- </entry>
- <entry>
- 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.
- </entry>
- </row>
- <row>
- <entry>
- Middle mouse button
- </entry>
- <entry>
- 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.
- </entry>
- </row>
- </tbody>
- </tgroup>
- </informaltable>
- </sect1>
- <sect1 id="starting-any-os"><title>Platform-Independent Instructions</title>
- <para>
- Exactly how jEdit is started depends on the operating system. For example, on Unix you can run <quote>jedit</quote> at the command line,
- or select jEdit from a menu; on Windows, you can
- use the jEditLauncher package, which is documented in
- <xref linkend="starting-windows" />.
- </para>
- <para>
- If jEdit is started while another copy is already running, control is
- transferred to the running copy, and a second instance is not loaded.
- This saves time and memory if jEdit is started multiple times.
- Communication between instances of jEdit is implemented using
- TCP/IP sockets; the initial instance is known as the
- <firstterm>server</firstterm>, and subsequent invocations are
- <firstterm>clients</firstterm>.
- </para>
- <para>
- If the <userinput>-background</userinput> command line switch is specified,
- jEdit will continue running and waiting for client requests even
- after all editor windows are closed. When run in background mode,
- you can open and close jEdit any number of times, only having
- to wait for it to start the first time. The downside of this
- is that jEdit will continue to consume memory when no windows
- are open.
- </para>
- <para>
- 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.
- </para>
- <para>
- For more information about command line switches that control the
- server feature, see <xref linkend="cli-usage" />.
- Note that if you are using <application>jEditLauncher</application>
- to start jEdit on Windows, this switch cannot be specified on the
- MS-DOS prompt command line when starting jEdit; it must be set as described
- in <xref linkend="launcher-starting" />.
- </para>
- <para>
- 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
- disabled in the <guibutton>General</guibutton> pane of the
- <guimenu>Utilities</guimenu>><guimenuitem>Global Options</guimenuitem>
- dialog box see <xref linkend="general-pane" />.
- </para>
- <sidebar><title>The edit server and security</title>
- <para>
- Not only does the server pick a random TCP port number on startup,
- it also requires that clients provide an <firstterm>authorization
- key</firstterm>; a randomly-generated number only accessible to
- processes running on the local machine.
- So not only will <quote>bad guys</quote> have to guess a 64-bit integer,
- they will need to get it right on the first try; the edit server
- shuts itself off upon receiving an invalid packet.
- </para>
- <para>
- In environments that demand absolute security, the edit server can be
- disabled by specifying the <userinput>-noserver</userinput> command line switch.
- </para>
- </sidebar>
- </sect1>
- <sect1 id="starting-windows"><title>Starting jEdit on Windows</title>
- <para>
- On Windows, jEdit comes with <emphasis>jEditLauncher</emphasis> - an optional
- package of components that make it easy to start jEdit, manage its command
- line settings, and launch files and macro scripts.
- </para>
- <para>
- The jEditLauncher package provides three shortcuts for running jEdit: one in
- the desktop's <guilabel>Start</guilabel> menu, a entry in the Programs menu, and
- a third shortcut on your desktop. Any of these may be deleted or moved without
- affecting jEdit's operation. To launch jEdit, simply select one of these shortcuts
- as you would for any Windows application.
- </para>
- <para>
- The jEditLauncher package includes a utility for changing the command line
- parameters that are stored with jEditLauncher and used every time it runs jEdit.
- You can change the Java interpreter used to launch jEdit, the amount of heap memory,
- the working directory and other command line parameters. To make these changes,
- select <guilabel>Set jEdit Parameters</guilabel> from the jEdit group in
- the Programs menu, or run <userinput>jedit /p</userinput> from a command
- line that has jEdit's installation directory in its search path. A dialog
- will appear that allows you to change and save a new set of command line
- parameters.
- </para>
- <para>
- The package also adds menu items to the context or <quote>right-click</quote>
- menu displayed by the Windows shell when you click on a file item in the
- desktop window, a Windows Explorer window or a standard file selection dialog.
- The menu entries allow you to open selected files in jEdit, starting the
- application if necessary. It will also allow you to open all files in a
- directory with a given extension with a single menu selection. If a BeanShell
- macro script with a <filename>.bsh</filename> extension is selected, the menu
- includes the option of running that script within jEdit. If you have the
- <application>JDiff</application> plugin installed with jEdit, you can also
- select two files and have jEdit compare them in a side-by-side graphical display.
- </para>
- <para>
- For a more detailed description of all features found in
- the jEditLauncher package, see <xref linkend="launcher-guide"/>.
- </para>
- </sect1>
- <sect1 id="cli-usage"><title>Command Line Usage</title>
- <para>
- On operating systems that support a command line, jEdit can be passed
- various arguments to control its behavior.
- </para>
- <para>
- If you are using <application>jEditLauncher</application>
- to start jEdit on Windows, only file names can be specified
- on the command line; the parameters documented below must be set as described
- in <xref linkend="launcher-starting" />.
- </para>
- <para>
- When opening files from the command line, a line number or marker to
- position the caret on can be specified like so:
- </para>
- <screen><prompt>$ </prompt><userinput>jedit MyApplet.java +line:10</userinput>
- <prompt>$ </prompt><userinput>jedit thesis.tex +marker:c</userinput></screen>
- <para>
- Command-line switches begin with a "-". Some take a parameter. A file whose name
- begins with "-" can be opened like so:
- </para>
- <screen><prompt>$ </prompt><userinput>jedit -- -myfile</userinput></screen>
- <sect2><title>Miscellaneous Options</title>
- <informaltable>
- <tgroup cols="2">
- <colspec colnum="1" colwidth="1.5in" />
- <thead>
- <row><entry>Option</entry><entry>Effect</entry></row>
- </thead>
- <tbody>
- <row>
- <entry><userinput>-log=<replaceable>level</replaceable></userinput></entry>
- <entry>Set the minimum log level to an integer between 1 and 9. Default is 7.
- Has no effect when connecting to
- another instance via the edit server.</entry>
- </row>
- <row>
- <entry><userinput>-usage</userinput></entry>
- <entry>Show a brief command line usage message without starting
- jEdit.
- This message is also shown if an invalid switch was specified.</entry>
- </row>
- <row>
- <entry><userinput>-version</userinput></entry>
- <entry>Show the version number without starting jEdit.</entry>
- </row>
- <row>
- <entry><userinput>- -</userinput></entry>
- <entry>Specifies the end of command-line processing. Further parameters are treated
- as file names, even if they begin with a dash.
- </entry>
- </row>
- </tbody>
- </tgroup>
- </informaltable>
- </sect2>
- <sect2><title>Configuration Options</title>
- <informaltable>
- <tgroup cols="2">
- <colspec colnum="1" colwidth="1.5in" />
- <thead>
- <row><entry>Option</entry><entry>Effect</entry></row>
- </thead>
- <tbody>
- <row>
- <entry><userinput>-plugins</userinput></entry>
- <entry>Enable loading of plugins. Has no effect
- when connecting to another instance via the edit server.
- See <xref linkend="using-plugins" />.</entry>
- </row>
- <row>
- <entry><userinput>-noplugins</userinput></entry>
- <entry>Disable loading of plugins. Has no effect
- when connecting to another instance via the edit server.</entry>
- </row>
- <row>
- <entry><userinput>-restore</userinput></entry>
- <entry>Restore previously open files on startup. This is the default.
- This feature can also be set permanently in the
- <guibutton>General</guibutton> pane of the
- <guimenu>Utilities</guimenu>><guimenuitem>Global Options</guimenuitem>
- dialog box; see <xref linkend="general-pane" />.
- </entry>
- </row>
- <row>
- <entry><userinput>-norestore</userinput></entry>
- <entry>Do not restore previously open files on startup.
- </entry>
- </row>
- <row>
- <entry><userinput>-run=<replaceable>script</replaceable></userinput></entry>
- <entry>Run the specified BeanShell script. There can only be one
- of these parameters on the command line. See
- <xref linkend="scripts-command-line" />.</entry>
- </row>
- <row>
- <entry><userinput>-settings=<replaceable>dir</replaceable></userinput></entry>
- <entry>Store user-specific settings in
- the directory named <replaceable>dir</replaceable>, instead of the
- default <filename><replaceable>user.home</replaceable>/.jedit</filename>.
- The directory will be created automatically if it does not exist. Has no
- effect when connecting to another instance via the edit server.
- See <xref linkend="settings-directory"/>.</entry>
- </row>
- <row>
- <entry><userinput>-nosettings</userinput></entry>
- <entry>Start jEdit without loading user-specific settings.</entry>
- </row>
- <row>
- <entry><userinput>-startupscripts</userinput></entry>
- <entry>Run startup scripts. This is the default.
- Has no effect
- when connecting to another instance via the edit server.
- See <xref linkend="startup-scripts" />.</entry>
- </row>
- <row>
- <entry><userinput>-nostartupscripts</userinput></entry>
- <entry>Disable startup scripts.
- Has no effect
- when connecting to another instance via the edit server.</entry>
- </row>
- </tbody>
- </tgroup>
- </informaltable>
- </sect2>
- <sect2><title>Edit Server Options</title>
- See <xref linkend="starting-any-os" /> for a brief description of the edit server.
- <informaltable>
- <tgroup cols="2">
- <colspec colnum="1" colwidth="1.5in" />
- <thead>
- <row><entry>Option</entry><entry>Effect</entry></row>
- </thead>
- <tbody>
- <row>
- <entry><userinput>-background</userinput></entry>
- <entry>Run jEdit in background mode. In background mode,
- the edit server will continue listening for
- client connections even after all views are closed. Has no effect
- when connecting to another instance via the edit server.</entry>
- </row>
- <row>
- <entry><userinput>-nobackground</userinput></entry>
- <entry>Disable background mode. This is the default.
- Has no effect when connecting to
- another instance via the edit server.</entry>
- </row>
- <row>
- <entry><userinput>-gui</userinput></entry>
- <entry>Open an initial view. This is the
- default. Has no effect when connecting to
- another instance via the edit server.
- </entry>
- </row>
- <row>
- <entry><userinput>-nogui</userinput></entry>
- <entry>Do not open an initial view, and instead only open one
- when the first client connects. Can only be used in combination with
- the <userinput>-background</userinput> switch. You can use this switch to
- <quote>pre-load</quote> jEdit when you log in to your computer, for
- example. Has no effect when connecting to
- another instance via the edit server.
- </entry>
- </row>
- <row>
- <entry><userinput>-server</userinput></entry>
- <entry>Store the server port info in the file named <filename>server</filename>
- inside the settings directory.</entry>
- </row>
- <row>
- <entry><userinput>-server=<replaceable>name</replaceable></userinput></entry>
- <entry>Store the server port info in the file named
- <replaceable>name</replaceable>. File names for this
- parameter are relative to the settings directory.</entry>
- </row>
- <row>
- <entry><userinput>-noserver</userinput></entry>
- <entry>Do not attempt to
- connect to a running edit server, and do not start one either.
- </entry>
- </row>
- </tbody>
- </tgroup>
- </informaltable>
- </sect2>
- </sect1>
- </chapter>