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

 1<?xml version="1.0" encoding="UTF-8"?>
 2<chapter id="installing-modes">
 3    <title>Installing Edit Modes</title>
 4
 5    <!-- jEdit buffer-local properties: -->
 6
 7    <!-- :indentSize=1:noTabs=true: -->
 8
 9    <!-- :xml.root=users-guide.xml: -->
10    <para>jEdit looks for edit modes in two locations; the
11    <filename>modes</filename> subdirectory of the jEdit settings directory, and
12    the <filename>modes</filename> subdirectory of the jEdit install directory.
13    The location of the settings directory is system-specific; see <xref
14    linkend="settings-directory" />.</para>
15
16    <para>Each mode directory contains a <filename>catalog</filename> file. All
17    edit modes contained in that directory must be listed in the catalog,
18    otherwise they will not be available to jEdit.</para>
19
20    <para>Catalogs, like modes themselves, are written in XML. They consist of a
21    single <literal>MODES</literal> tag, with a number of
22    <literal>MODE</literal> tags inside. Each mode tag associates a mode name
23    with an XML file, and specifies the file name and first line pattern for the
24    mode. A sample mode catalog looks as follows:</para>
25
26    <programlisting>&lt;?xml version="1.0"?&gt;
27&lt;!DOCTYPE CATALOG SYSTEM "catalog.dtd"&gt;
28
29&lt;MODES&gt;
30    &lt;MODE NAME="shellscript" FILE="shellscript.xml"
31        FILE_NAME_GLOB="*.sh"
32        FIRST_LINE_GLOB="#!/*sh*" /&gt;
33&lt;/MODES&gt;</programlisting>
34
35    <para>In the above example, a mode named <quote>shellscript</quote> is
36    defined, and is used for files whose names end with
37    <filename>.sh</filename>, or whose first line starts with <quote>#!/</quote>
38    and contains <quote>sh</quote>.</para>
39
40    <para>The <literal>MODE</literal> tag supports the following
41    attributes:</para>
42
43    <itemizedlist>
44        <listitem>
45            <para><literal>NAME</literal> - the name of the edit mode, as it
46            will appear in the <guimenuitem>Buffer Options</guimenuitem> dialog
47            box, the status bar, and so on.</para>
48        </listitem>
49
50        <listitem>
51            <para><literal>FILE</literal> - the name of the XML file containing
52            the mode definition.</para>
53        </listitem>
54
55        <listitem>
56            <para><literal>FILE_NAME_GLOB</literal> - files whose names match
57            this glob pattern will be opened in this edit mode.
58            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. 
59            </para>
60        </listitem>
61
62        <listitem>
63            <para><literal>FIRST_LINE_GLOB</literal> - files whose first line
64            matches this glob pattern will be opened in this edit mode.</para>
65        </listitem>
66    </itemizedlist>
67
68    <para>Glob pattern syntax is described in <xref linkend="globs" />.</para>
69
70    <tip>
71        <para>If an edit mode in the user-specific catalog has the same name as
72        an edit mode in the system catalog, the version in the user-specific
73        catalog will override the system default.</para>
74    </tip>
75</chapter>