<?xml version="1.0" encoding="UTF-8"?>
<chapter id="customizing">
    <title>Customizing jEdit</title>
    <!-- jEdit buffer-local properties: -->
    <!-- :tabSize=1:indentSize=1:noTabs=true:wrap=soft:maxLineLen=0: -->
    <!-- :xml.root=users-guide.xml: -->

    <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="general-pane">
            <title>The General Pane</title>

            <para>The <guibutton>General</guibutton> pane contains various
            settings, such as the default line separator, the number of recent
            files to remember, if the buffer list should be sorted, and so
            on.</para>

        </sect2>

        <sect2 id="abbrevs-pane">
            <title>The Abbreviations Pane</title>

            <indexterm>
                <primary>Abbreviations</primary>

                <secondary>creating and editing</secondary>
            </indexterm>

            <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 labelled <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>Changing options from this optionpane 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" />. Some of these options can be further overridden on an individual file basis through the use of buffer-local properties. </para>
            
            <para>The <literal>File name
            glob</literal> and <literal>First line glob</literal> 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> The <literal>Extra Word Characters</literal> allows you to set the <literal>noLineSep</literal> buffer property on a mode-wide basis, allowing you to define what is considered part of a word when double-clicking on it in the text area.
            </para>
            
            <para> The <literal>Deep Indent</literal> option instructs jEdit to indent subsequent lines so that they line up with the open bracket on the previous line. </para>
            
            
        </sect2>

        <sect2 id="encodings-pane">
            <title>The Encodings Pane</title>

            <para>This option pane is new to jEdit 4.3, and offers international
            users of jEdit many flexible options for defining how Encodings are
            handled in jEdit. See <xref linkend="encodings" /> for the
            basics.</para>
            
            <para> In previous versions of jEdit, there was very little encoding autodetection, so <guilabel>use autodetection when possible</guilabel> is an option you can switch on or off.
            </para>

            <para>The <literal>List of Encoding Autodetector Names</literal> is
            an experimental feature that allows for jEdit and plugins to offer
            additional encoding autodetector routines. At the moment, there are
            two techniques known by jEdit: the <literal>BOM</literal> (Byte
            Order Mark), and the <literal>XML-PI</literal> (XML processing
            instruction) techniques. Others can be defined as services and added
            to this space-separated list. See <ulink
            url="../api/org/gjt/sp/jedit/io/EncodingDetector.html">EncodingDetector</ulink>
            for details on how to offer this service. The order they appear in this
            list determines the order of detectors that are tried on each file. </para>

            <para>The <literal>List of Fallback Encodings</literal> is used when
            a file fails to open in the default encoding, and the Encoding
            Autodetectors also fail. The list order here determines the order of
            encodings that are tried. Each is separated by a space. This is
            especially handy when doing directory searches through files of
            different encodings. We suggest using <literal>UTF-8</literal> as
            either your default or one of the fallback encodings.</para>

            <para>While jEdit allows you to edit files in a variety of different
            encodings, the average user switches between only 2 or 3. In other
            parts of jEdit, where the list of encodings is displayed in a
            combobox (such as the buffer options) or a menu (such as
            <guimenuitem>File - Reload with Encoding</guimenuitem> submenu) it
            may be desirable to display only a subset of available encodings,
            those that are in common local use. The Encodings checkbox list
            allows the user to select the subset of supported encodings to
            display in other GUI components that list all of the
            encodings.</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>
            
            <para> The only option that may not be self-explanatory is the  <emphasis role="bold">Double-Click drag joins non-alphanumeric characters</emphasis>. This option means that double-click will select a region that includes the non-alphabetical characters, as defined for the current mode. The actual set of characters can be defined for an indiviual file via buffer-local properties (<literal>noWordSep</literal>) or on a mode-wide basis from the Editing option pane (<literal>Extra Word Characters</literal>).
            </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. In addition, you can set the time in minutes that the pluginlist can be cached from jedit.org, helping to reduce the server load. 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>
            
            <bridgehead> 2-key shortcut prefixes </bridgehead>
            
            <para> Some shortcuts, such as C+e, C+m, and C+r, are prefixes for two-keystroke shortcuts. Another  keystroke may be used as a prefix in a 2-key shortcut, so for example, C+x can be redefined as a prefix to make it more emacs-like, by mapping any other action to a C+x prefixed shortcut.</para>
            
            <para> Conversely, emacs users will notice at first that C+e can not be mapped as a single key shortcut to go to the end of the line, unless all of the other actions that contain C+e prefixed shortcuts are remapped to other shortcuts first. After that, C+e can be bound to end-of-line. </para>
            
            <para> The default shortcuts can be found in  <literal>jedit_keys.props</literal>. </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>pluginMgr-Cached.xml.gz</filename> - 
                this contains a cached copy of the last XML plugin list downloaded from plugin central. If you delete this file, a new one will be created next time you try to install a plugin via Plugin Manager. </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 and its plugins settings. For
                more information see <xref linkend="propertiesfile" />.</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>

        <sect2 id="propertiesfile">
            <title>The jEdit properties file</title>

            <para>The jEdit <literal>properties</literal> file uses the Java
            properties syntax to store key/value pairs. All of the values are
            stored as strings, but are interpreted as other types (such as
            integer or boolean) by plugins at runtime.</para>

            <para>Editing and saving this file while jEdit is running means that
            until you restart jEdit again, all other changed settings will be
            lost.</para>
        </sect2>
    </sect1>
</chapter>