<?xml version="1.0" encoding="UTF-8"?>
<chapter id="installing-modes">
    <title>Installing Edit Modes</title>
    <!-- jEdit buffer-local properties: -->
    <!-- :indentSize=2:noTabs=true: -->
    <!-- :xml.root=users-guide.xml: -->
    <para>The easiest way to install a new mode locally is to use the Editing 
    dialog found under Utilities - Global Options. At the bottom of this dialog
    is an "Add Mode" button. Clicking this button shows a dialog to add a mode
    to jEdit. Simply fill in the blanks and the mode file will be put in the
    proper place and the catalog file will be updated appropriately. Modes added
    this way can be removed by selecting the mode in the Editing dialog, then
    clicking the "Delete Mode" button. This button will only appear for modes
    that exist in the user settings directory. Core modes, that is, those modes
    distributed with jEdit cannot be deleted this way. The details of adding a
    mode by hand are below.
    </para>
    <para>jEdit looks for edit modes in two locations; the
    <filename>modes</filename> subdirectory of the jEdit settings directory, and
    the <filename>modes</filename> subdirectory of the jEdit install directory.
    The location of the settings directory is system-specific; see <xref
    linkend="settings-directory" />.</para>

    <para>Each mode directory contains a <filename>catalog</filename> file. All
    edit modes contained in that directory must be listed in the catalog,
    otherwise they will not be available to jEdit.</para>

    <para>Catalogs, like modes themselves, are written in XML. They consist of a
    single <literal>MODES</literal> tag, with a number of
    <literal>MODE</literal> tags inside. Each mode tag associates a mode name
    with an XML file, and specifies the file name and first line pattern for the
    mode. A sample mode catalog looks as follows:</para>

    <programlisting>&lt;?xml version="1.0"?&gt;
&lt;!DOCTYPE CATALOG SYSTEM "catalog.dtd"&gt;

&lt;MODES&gt;
    &lt;MODE NAME="shellscript" FILE="shellscript.xml"
        FILE_NAME_GLOB="*.sh"
        FIRST_LINE_GLOB="#!/*sh*" /&gt;
&lt;/MODES&gt;</programlisting>

    <para>In the above example, a mode named <quote>shellscript</quote> is
    defined, and is used for files whose names end with
    <filename>.sh</filename>, or whose first line starts with <quote>#!/</quote>
    and contains <quote>sh</quote>.</para>

    <para>The <literal>MODE</literal> tag supports the following
    attributes:</para>

    <itemizedlist>
        <listitem>
            <para><literal>NAME</literal> - the name of the edit mode, as it
            will appear in the <guimenuitem>Buffer Options</guimenuitem> dialog
            box, the status bar, and so on.</para>
        </listitem>

        <listitem>
            <para><literal>FILE</literal> - the name of the XML file containing
            the mode definition.</para>
        </listitem>

        <listitem>
            <para><literal>FILE_NAME_GLOB</literal> - files whose names match
            this glob pattern will be opened in this edit mode.
            This can also specify full paths, if the glob pattern contains a 
            path separator character. <literal>FILE_NAME_GLOB</literal> can be 
            specified in the <literal>modes/catalog</literal> file, or the mode 
            file itself. See the <literal>FILE_NAME_GLOB</literal> for 
            <literal>apacheconf.xml</literal> in <literal>modes/catalog</literal> 
            for an example of full path filename globbing.
            </para>
        </listitem>

        <listitem>
            <para><literal>FIRST_LINE_GLOB</literal> - files whose first line
            matches this glob pattern will be opened in this edit mode.</para>
        </listitem>
    </itemizedlist>

    <para>Glob pattern syntax is described in <xref linkend="globs" />.</para>

    <tip>
        <para>If an edit mode in the user-specific catalog has the same name as
        an edit mode in the system catalog, the version in the user-specific
        catalog will override the system default.</para>
    </tip>

    <para> When a buffer is opened, jEdit must choose an edit mode for that buffer.
    It checks conditions in this order to decide which edit mode to use: </para>

    <orderedlist>
    <listitem><para> the filename is an exact match for the <literal>FILE_NAME_GLOB</literal>. </para></listitem>
    <listitem><para> the filename matches the <literal>FILE_NAME_GLOB</literal> and the first line of the file matches the <literal>FIRST_LINE_GLOB</literal></para></listitem>
    <listitem><para> the filename matches the <literal>FILE_NAME_GLOB</literal> </para></listitem>
    <listitem><para> the first line of the file matches the <literal>FIRST_LINE_GLOB</literal></para></listitem>
    </orderedlist>
</chapter>