/jEdit/tags/jedit-4-2-pre14/doc/users-guide/customizing.xml

<!-- jEdit buffer-local properties: -->
<!-- :tabSize=1:indentSize=1:noTabs=true:wrap=soft:maxLineLen=80: -->
<!-- :xml.root=users-guide.xml: -->

<chapter id="customizing"><title>Customizing jEdit</title>
 <sect1 id="buffer-opts"><title>The Buffer Options Dialog Box</title>
  <para>
   <guimenu>Utilities</guimenu>&gt;<guimenuitem>Buffer Options</guimenuitem>
   displays a dialog box for changing editor settings on a per-buffer basis.
   Changes made in this dialog box are not retained after the buffer is
   closed.
  </para>
  <para>
   The following settings can be changed here:
  </para>
  <itemizedlist>
   <listitem><para>The line separator (see <xref linkend="line-separators" />)
   </para></listitem>
   <listitem><para>The character encoding (see <xref linkend="encodings" />)
   </para></listitem>
   <listitem><para>If the file should be GZipped on disk
   (see <xref linkend="opening" />)
   </para></listitem>
   <listitem><para>The edit mode (see <xref linkend="modes" />)</para></listitem>
   <listitem><para>The fold mode (see <xref linkend="folding" />)</para></listitem>
   <listitem><para>The wrap mode and margin (see <xref linkend="word-wrap" />)
   </para></listitem>
   <listitem><para>The tab width (see <xref linkend="indent" />)</para></listitem>
   <listitem><para>The indent width</para></listitem>
   <listitem><para>If soft tabs should be used
   (see <xref linkend="indent" />)
   </para></listitem>
  </itemizedlist>
 </sect1>
 <sect1 id="buffer-local"><title>Buffer-Local Properties</title>
  <para>
   Buffer-local properties provide an alternate way to change editor settings
   on a per-buffer basis. While changes made in the <guimenuitem>Buffer
   Options</guimenuitem> dialog box
   are lost after the buffer is closed, buffer-local properties take effect
   each time the file is opened, because they are embedded in the file
   itself.
  </para>
  <para>
   When jEdit loads a file, it checks the first and last 10 lines for
   colon-enclosed name/value pairs. For example, placing the following in
   a buffer changes
   the indent width to 4 characters, enables soft tabs, and activates the
   Perl edit mode:
  </para>
  <screen>:indentSize=4:noTabs=true:mode=perl:</screen>
  <para>
   Adding buffer-local properties to a buffer
   takes effect after the next time the buffer is saved.
  </para>
  <para>
   The following table describes each buffer-local property in detail.
  </para>
  <informaltable>
   <tgroup cols="2">
    <colspec colnum="1" colwidth="1.5in" />
    <thead>
     <row>
      <entry>Property name</entry>
      <entry>Description</entry>
     </row>
    </thead>
    <tbody>
     <row>
      <entry><varname>collapseFolds</varname></entry>
      <entry>Folds with a level of this or higher will be collapsed when the
      buffer is opened. If set to zero, all folds will be expanded initially.
      See <xref linkend="folding" />.</entry>
     </row>
     <row>
      <entry><varname>deepIndent</varname></entry>
      <entry>When set to <quote>true</quote>, multiple-line expressions delimited by parentheses are aligned like so:
      <programlisting>retVal.x = (int)(horizontalOffset
    + Chunk.offsetToX(info.chunks,
                      offset));</programlisting>
      With this setting disabled, the text would look like so:
      <programlisting>retVal.x = (int)(horizontalOffset
    + Chunk.offsetToX(info.chunks,
    offset));</programlisting>
      </entry>
     </row>
     <row>
      <entry><varname>folding</varname></entry>
      <entry>The fold mode; one of <quote>none</quote>, <quote>indent</quote>,
      <quote>explicit</quote>, or the name of a plugin folding mode.
      See <xref linkend="folding" />.</entry>
     </row>
     <row>
      <entry><varname>indentSize</varname></entry>
      <entry>The width, in characters, of one indent.
      Must be an integer greater than 0.
      See <xref linkend="indent" />.</entry>
     </row>
     <row>
      <entry><varname>maxLineLen</varname></entry>
      <entry>The maximum line length and wrap column position.
      Inserting text beyond this column will automatically insert a line
      break at the appropriate position.
      See <xref linkend="entering-text" />.</entry>
     </row>
     <row>
      <entry><varname>mode</varname></entry>
      <entry>The default edit mode for the buffer.
      See <xref linkend="modes" />.</entry>
     </row>
     <row>
      <entry><varname>noTabs</varname></entry>
      <entry>If set to <quote>true</quote>, soft tabs (multiple space characters)
      will be used instead of <quote>real</quote> tabs. See
      <xref linkend="indent" />.</entry>
     </row>
     <row>
      <entry><varname>noWordSep</varname></entry>
      <entry>A list of non-alphanumeric characters that are
      <emphasis>not</emphasis> to
      be treated as word separators. Global default is <quote>_</quote>.</entry>
     </row>
     <row>
      <entry><varname>tabSize</varname></entry>
      <entry>The tab width. Must be an integer greater than 0.
      See <xref linkend="indent" />.</entry>
     </row>
     <row>
      <entry><varname>wordBreakChars</varname></entry>
      <entry>Characters, in addition to spaces and tabs, at which lines may be
      split when word wrapping.
      See <xref linkend="entering-text" />.</entry>
     </row>
     <row>
      <entry><varname>wrap</varname></entry>
      <entry>The word wrap mode; one of <quote>none</quote>, <quote>soft</quote>,
      or <quote>hard</quote>. See <xref linkend="word-wrap" />.</entry>
     </row>
    </tbody>
   </tgroup>
  </informaltable>
 </sect1>
 <sect1 id="global-opts"><title>The Global Options Dialog Box</title>
  <para>
   <guimenu>Utilities</guimenu>&gt;<guimenuitem>Global Options</guimenuitem>
   displays the global options dialog box. The dialog box is divided into
   several panes, each pane containing a set of related options. Use the list
   on the left of the dialog box to switch between panes. Only panes
   created by jEdit are described here; some plugins add their own option
   panes, and information about them can be found in the documentation
   for the plugins in question.
  </para>
  <sect2 id="abbrevs-pane"><title>The Abbreviations Pane</title>
  <para>
   The <guibutton>Abbreviations</guibutton> option pane can be used to enable or
   disable automatic abbreviation expansion, and to edit currently defined
   abbreviations.
  </para>
  <para>
   The combo box labeled <quote>Abbrev set</quote> selects the
   abbreviation set to edit. The first entry, <quote>global</quote>, contains
   abbreviations available in all edit modes. The subsequent
   entries correspond to each mode's local set of abbreviations.
  </para>
  <para>
   To change an abbreviation or its expansion, either double-click the appropriate
   table entry, or click a table entry and then click the
   <guibutton>Edit</guibutton> button. This will display a dialog box for
   modifying the abbreviation.
  </para>
  <para>
   The <guibutton>Add</guibutton> button displays a dialog box where you can
   define a new abbreviation. The <guibutton>Remove</guibutton> button removes
   the currently selected abbreviation from the list.
  </para>
  <para>
   See <xref linkend="positional-params" /> for information about positional
   parameters in abbreviations.
  </para>
  </sect2><sect2 id="appearance-pane"><title>The Appearance Pane</title>
  <para>
   The <guibutton>Appearance</guibutton> pane can be used to change the
   appearance of user interface controls such as buttons, labels and menus. The number of items retained in history text fields can also be set here; see <xref linkend="history"/>.
  </para>
  <para>
   Note that changes to certain settings such as the Swing look and feel require a restart of jEdit to take effect.
  </para>
  </sect2><sect2 id="autosave-backups-pane"><title>The Autosave and Backup Pane</title>
  <para>
   The <guibutton>Autosave</guibutton> option pane contains settings for the autosave and backup features. See <xref linkend="autosave" /> and
   <xref linkend="backups"/>.
  </para>
  </sect2><sect2 id="context-pane"><title>The Context Menu Pane</title>
  <para>
   The <guibutton>Context Menu</guibutton> option pane edits the text
   area's right-click context menu. See <xref linkend="views"/>.
  </para>
  </sect2>
  <sect2 id="docking-pane"><title>The Docking Pane</title>
  <para>
   The <guibutton>Docking</guibutton> option pane specifies docking location for various dockable windows. Another way to specify docking locations is to use the popup menus associated with each dockable window; see <xref linkend="docking"/>.
  </para>
  </sect2>
  <sect2 id="editing-pane"><title>The Editing Pane</title>
  <para>
   The <guibutton>Editing</guibutton> option pane contains settings such
   as the tab size, syntax highlighting and soft tabs on a global or
   mode-specific basis.
  </para>
  <para>
   When changing mode-specific settings,
   the <guibutton>File name glob</guibutton> and <guibutton>First line
   glob</guibutton> text fields let you specify a glob pattern that names and
   first lines of buffers will be matched against to determine the edit mode.
   See <xref linkend="globs"/> for information about glob patterns.
  </para>
  <para>
   This option pane does not change XML mode definition files on disk; it
   merely writes values to the user properties file which override those set
   in mode files. To find out how to edit mode files directly, see
   <xref linkend="writing-modes-part" />.
  </para>
  </sect2><sect2 id="general-pane"><title>The General Pane</title>
  <para>
   The <guibutton>General</guibutton> pane contains various
   miscellaneous settings, such as the default line separator and file encoding, the number of recent files to remember,
   if the buffer list should be sorted, and so on.
  </para>
  </sect2><sect2 id="gutter-pane"><title>The Gutter Pane</title>
  <para>
   The <guibutton>Gutter</guibutton> option pane contains settings to
   customize the appearance of the gutter. See <xref linkend="overview"/>.
  </para>
  </sect2><sect2 id="mouse-pane"><title>The Mouse Pane</title>
  <para>
   The <guibutton>Mouse</guibutton> option pane contains settings for toggling drag and drop of text, as well as gutter mouse click behavior.
  </para>
  </sect2><sect2 id="printing-pane"><title>The Printing Pane</title>
  <para>
   The <guibutton>Printing</guibutton> option pane contains settings to
   control the appearance of printed output. Workarounds that might be needed for your Java version to print correctly can also be enabled here. See <xref linkend="printing"/>.
  </para>
  </sect2><sect2 id="pluginmgr-pane"><title>The Plugin Manager Pane</title>
  <para>
   The <guibutton>Plugin Manager</guibutton> pane contains a chooser for the desired download mirror, as well as various settings such as the directory where plugins are to be installed. See <xref linkend="using-plugins"/>.
  </para>
  </sect2><sect2 id="firewall-pane"><title>The Proxy Servers Pane</title>
  <para>
   The <guibutton>Proxy Servers</guibutton> option pane lets you specify HTTP
   and SOCKS proxy servers to use when jEdit makes network connections, for
   example when downloading plugins.
  </para>
  </sect2><sect2 id="shortcuts-pane"><title>The Shortcuts Pane</title>
  <para>
   The <guibutton>Shortcuts</guibutton> option pane associates keyboard shortcuts with commands. Each command can have up to two shortcuts
   associated with it.
  </para>
  <para>
   The combo box at the top of the option pane selects the command set
   to edit. Command sets include the set of all built-in commands, the commands of each plugin, and the set of macros.
  </para>
  <para>
   To change a shortcut, click the appropriate table entry and press the
   keys you want associated with that command in the resulting dialog box.
   The dialog box will warn you if the shortcut is already assigned.
  </para>
  </sect2><sect2 id="status-bar-pane"><title>The Status Bar Pane</title>
  <para>
   The <guibutton>Status Bar</guibutton> option pane contains settings to customize the
   status bar, or disable it completely. See <xref linkend="status-bar"/>.
  </para>
  </sect2><sect2 id="syntax-hilite-pane"><title>The Syntax Highlighting Pane</title>
  <para>
   The <guibutton>Syntax Highlighting</guibutton> pane can be used to
   customize the fonts and colors for syntax highlighting. See <xref linkend="syntax-hilite"/>.
  </para>
  </sect2><sect2 id="text-area-pane"><title>The Text Area Pane</title>
  <para>
   The <guibutton>Text Area</guibutton> pane contains settings to customize
   the appearance of the text area. See <xref linkend="overview"/>.
  </para>
  </sect2><sect2 id="toolbar-pane"><title>The Tool Bar Pane</title>
  <para>
   The <guibutton>Tool Bar</guibutton> option pane lets you edit the tool bar,
   or disable it completely. See <xref linkend="views"/>.
  </para>
  </sect2><sect2 id="view-pane"><title>The View Pane</title>
  <para>
   The <guibutton>View</guibutton> option pane lets you change various settings related to the editor window's appearance, including the arrangement of dockable windows, and if the search bar and buffer switcher should be visible. See <xref linkend="views"/>.
  </para>
  </sect2><sect2 id="vfs-browser-pane"><title>The File System Browser Panes</title>
  <para>
   The <guibutton>File System Browser</guibutton> group
   contains two option panes, <guibutton>General</guibutton> and
   <guibutton>Colors</guibutton>. The former contains various file system
   browser settings. The latter configures glob patterns used for
   coloring the file list. See <xref linkend="vfs-browser" />
   for more information.
  </para></sect2>
 </sect1>
 <sect1 id="settings-directory"><title>The jEdit Settings Directory</title>
  <para>
   jEdit stores settings, macros, and plugins as files
   inside the <firstterm>settings directory</firstterm>. In most cases, editing
   these files by hand is not necessary, since graphical tools and editor
   commands can do the job. However, being familiar with the structure of the
   settings directory still comes in handy
   in certain situations, for example when you want to copy jEdit settings
   between computers.
  </para>
  <para>
   The location of the settings directory is system-specific; it is printed to
   the activity log
   (<guimenu>Utilities</guimenu>&gt;<guisubmenu>Troubleshooting</guisubmenu>&gt;<guimenuitem>Activity
   Log</guimenuitem>). For example:
  </para>
  <screen>[message] jEdit: Settings directory is /home/slava/.jedit</screen>
  <para>
   Specifying the <userinput>-settings</userinput> switch on the command line
   instructs jEdit to store settings in a directory other than the default.
   For example, the following command will instruct jEdit to
   store all settings
   in the <filename>jedit</filename> subdirectory of the <filename>C:</filename>
   drive:
  </para>
  <screen><prompt>C:\jedit&gt;</prompt> <userinput>jedit -settings=C:\jedit</userinput></screen>
  <para>
   The <userinput>-nosettings</userinput> switch will force jEdit to not look for
   or create a settings directory; default settings will be used instead.
  </para>
  <para>
   If you are using <application>jEditLauncher</application>
   to start jEdit on Windows, these parameters cannot be specified on the
   MS-DOS prompt command line when starting jEdit; they must be set as described
   in <xref linkend="launcher-starting" />.
  </para>
  <para>
   jEdit creates the following files and directories
   inside the settings directory; plugins may add more:
  </para>
  <itemizedlist>
   <listitem><para><filename>abbrevs</filename> - a plain text file which
   stores all defined abbreviations. See <xref linkend="abbrevs" />.
   </para></listitem>
   <listitem><para><filename>activity.log</filename> - a plain text file which
   contains the full activity log. See <xref linkend="activity-log" />.
   </para></listitem>
   <listitem><para><filename>history</filename> - a plain text file which
   stores history lists, used by history text fields and the
   <guimenu>Edit</guimenu>&gt;<guimenuitem>Paste Previous</guimenuitem> command.
   See <xref linkend="text-transfer" /> and <xref linkend="history" />.
   </para></listitem>
   <listitem><para><filename>jars</filename> - this directory contains
   plugins. See <xref linkend="using-plugins" />.</para></listitem>
   <listitem><para><filename>jars-cache</filename> - this directory contains
   plugin cache files which decrease the time to start jEdit. They are automatically updated when plugins are installed or updated.</para></listitem>
   <listitem><para><filename>killring.xml</filename> - stores recently deleted text. See <xref linkend="text-transfer" />.</para></listitem>
   <listitem><para><filename>macros</filename> - this directory contains
   macros. See <xref linkend="using-macros" />.</para></listitem>
   <listitem><para><filename>modes</filename> - this directory contains custom
   edit modes. See <xref linkend="writing-modes-part" />.
   </para></listitem>
   <listitem><para><filename>perspective.xml</filename> - an XML file that stores the list of open buffers and views used to maintain editor state between sessions.</para></listitem>
   <listitem><para><filename>PluginManager.download</filename> - this directory
   is usually empty. It only contains files while the plugin manager is
   downloading a plugin. For information about the plugin manager,
   see <xref linkend="using-plugins" />.</para></listitem>
   <listitem><para><filename>printspec</filename> - a binary file that
   stores printing settings when running under Java 2 version 1.4.
   </para></listitem>
   <listitem><para><filename>properties</filename> - a plain text file that
   stores the majority of jEdit's settings.</para></listitem>
   <listitem><para><filename>recent.xml</filename> - an XML file which stores
   the list of recently opened files. jEdit remembers the caret position and
   character encoding of each recent file, and
   automatically restores those values when one of the files is opened.
   </para></listitem>
   <listitem><para><filename>registers.xml</filename> - an XML file that stores
   register contents. See <xref linkend="registers"/> for more information
   about registers.
   </para></listitem>
   <listitem><para><filename>server</filename> - a plain text file that only
   exists while jEdit is running. The edit server's port number and
   authorization key is stored here. See <xref linkend="starting" />.
   </para></listitem>
   <listitem><para><filename>settings-backup</filename> - this directory
   contains numbered backups of all automatically-written settings files.
   </para></listitem>
  </itemizedlist>
 </sect1>
</chapter>