/jEdit/tags/jedit-4-5-pre1/doc/users-guide/installing-modes.xml

<?xml version="1.0" encoding="UTF-8"?>
<chapter id="installing-modes">
    <title>Installing Edit Modes</title>

    <!-- jEdit buffer-local properties: -->

    <!-- :indentSize=1:noTabs=true: -->

    <!-- :xml.root=users-guide.xml: -->
    <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>
</chapter>