/jEdit/tags/jedit-4-0-pre3/doc/users-guide/writing-modes.xml

# · XML · 515 lines · 507 code · 6 blank · 2 comment · 0 complexity · 1386484f546c7d11e0ad5d68fdd0325a MD5 · raw file 

    

  1. <!-- jEdit buffer-local properties: -->
    2. 

  2. <!-- :indentSize=1:noTabs=true:folding=indent:collapseFolds=1: -->
    3. 

  3. 

  4. <chapter id="writing-modes"><title>Writing Edit Modes</title>
    5. 

  5.  <para>
    6. 

  6.   Edit modes are defined using XML, the <firstterm>extensible markup
    7. 

  7.   language</firstterm>; mode files have the extension
    8. 

  8.   <filename>.xml</filename>. XML is a very simple language, and as a result
    9. 

  9.   edit modes are easy to create and modify. This section will
    10. 

  10.   start with a short XML primer, followed by detailed information about
    11. 

  11.   each supported tag and highlighting rule.
    12. 

  12.  </para>
    13. 

  13.  <sidebar><title>Changes to modes take effect immediately</title>
    14. 

  14.   <para>
    15. 

  15.    Editing a mode file, or a mode catalog file within jEdit will cause the
    16. 

  16.    edit modes to be reloaded automatically as soon as the file is saved.
    17. 

  17.   </para>
    18. 

  18.   <para>
    19. 

  19.    <guimenu>Utilities</guimenu>&gt;<guimenuitem>Reload Edit Modes</guimenuitem>
    20. 

  20.    can be used to reload edit modes after changes to mode files are made
    21. 

  21.    outside jEdit.
    22. 

  22.   </para>
    23. 

  23.  </sidebar>
    24. 

  24.  <sect1 id="xml-primer"><title>An XML Primer</title>
    25. 

  25.   <para>
    26. 

  26.    A very simple edit mode looks like so:
    27. 

  27.   </para>
    28. 

  28.   <programlisting><![CDATA[<?xml version="1.0"?>
    29. 

  29. 

  30. <!DOCTYPE MODE SYSTEM "xmode.dtd">
    31. 

  31. 

  32. <MODE>
    33. 

  33.     <PROPS>
    34. 

  34.         <PROPERTY NAME="commentStart" VALUE="/*" />
    35. 

  35.         <PROPERTY NAME="commentEnd" VALUE="*/" />
    36. 

  36.     </PROPS>
    37. 

  37. 

  38.     <RULES>
    39. 

  39.         <SPAN TYPE="COMMENT1">
    40. 

  40.             <BEGIN>/*</BEGIN>
    41. 

  41.             <END>*/</END>
    42. 

  42.         </SPAN>
    43. 

  43.     </RULES>
    44. 

  44. </MODE>]]></programlisting>
    45. 

  45.   <para>
    46. 

  46.    Note that each opening tag must have a corresponding closing tag.
    47. 

  47.    If there is nothing between the opening and closing tags, for example
    48. 

  48.    <literal>&lt;TAG&gt;&lt;/TAG&gt;</literal>, the shorthand notation
    49. 

  49.    <literal>&lt;TAG /&gt;</literal> may be used. An example of this shorthand
    50. 

  50.    can be seen
    51. 

  51.    in the <literal>&lt;PROPERTY&gt;</literal> tags above.
    52. 

  52.   </para>
    53. 

  53.   <para>
    54. 

  54.    XML is case sensitive. <literal>Span</literal> or <literal>span</literal>
    55. 

  55.    is not the same as <literal>SPAN</literal>.
    56. 

  56.   </para>
    57. 

  57.   <para>
    58. 

  58.    To insert a special character such as &lt; or &gt; literally in XML
    59. 

  59.    (for example, inside an attribute value), you must write it as
    60. 

  60.    an <firstterm>entity</firstterm>. An
    61. 

  61.    entity consists of the character's symbolic name enclosed with
    62. 

  62.    <quote>&amp;</quote> and <quote>;</quote>. A full list of entities is out of
    63. 

  63.    the scope of this section, but the most important are:
    64. 

  64.   </para>
    65. 

  65.   <itemizedlist>
    66. 

  66.    <listitem><para><literal>&amp;lt;</literal> - The less-than (&lt;)
    67. 

  67.    character</para></listitem>
    68. 

  68.    <listitem><para><literal>&amp;gt;</literal> - The greater-than (&gt;)
    69. 

  69.    character</para></listitem>
    70. 

  70.    <listitem><para><literal>&amp;amp;</literal> - The ampersand (&amp;)
    71. 

  71.    character</para></listitem>
    72. 

  72.   </itemizedlist>
    73. 

  73.   <para>
    74. 

  74.    For example, the following will cause a syntax error:
    75. 

  75.   </para>
    76. 

  76.   <programlisting>&lt;SEQ TYPE="OPERATOR"&gt;&amp;&lt;/SEQ&gt;</programlisting>
    77. 

  77.   <para>
    78. 

  78.    Instead, you must write:
    79. 

  79.   </para>
    80. 

  80.   <programlisting>&lt;SEQ TYPE="OPERATOR"&gt;&amp;amp;&lt;/SEQ&gt;</programlisting>
    81. 

  81.   <para>
    82. 

  82.    Now that the basics of XML have been covered, the rest of this
    83. 

  83.    section will cover each construct in detail.
    84. 

  84.   </para>
    85. 

  85.  </sect1>
    86. 

  86.  <sect1 id="mode-preamble"><title>The Preamble and MODE tag</title>
    87. 

  87.    <para>
    88. 

  88.     Each mode definition must begin with the following:
    89. 

  89.    </para>
    90. 

  90.    <programlisting>&lt;?xml version="1.0"?&gt;
    91. 

  91. &lt;!DOCTYPE MODE SYSTEM "xmode.dtd"&gt;</programlisting>
    92. 

  92.   <para>
    93. 

  93.    Each mode definition must also contain exactly one <literal>MODE</literal>
    94. 

  94.    tag. All other tags (<literal>PROPS</literal>, <literal>RULES</literal>)
    95. 

  95.    must be placed inside the <literal>MODE</literal> tag.
    96. 

  96.   </para>
    97. 

  97.  </sect1>
    98. 

  98.  <sect1 id="mode-tag-props"><title>The PROPS Tag</title>
    99. 

  99.   <para>
    100. 

  100.    The <literal>PROPS</literal> tag and the <literal>PROPERTY</literal> tags
    101. 

  101.    inside it are used to define mode-specific
    102. 

  102.    properties. Each <literal>PROPERTY</literal> tag must have a
    103. 

  103.    <literal>NAME</literal> attribute set to the property's name, and a
    104. 

  104.    <literal>VALUE</literal> attribute with the property's value.
    105. 

  105.   </para>
    106. 

  106.   <para>
    107. 

  107.    All buffer-local properties listed in <xref linkend="buffer-local" />
    108. 

  108.    may be given values in edit modes. In addition, the following mode
    109. 

  109.    properties have no buffer-local equivalent:
    110. 

  110.   </para>
    111. 

  111.   <itemizedlist>
    112. 

  112.    <listitem><para><literal>indentCloseBrackets</literal> -
    113. 

  113.    A list of characters (usually brackets) that subtract indent from
    114. 

  114.    the <emphasis>current</emphasis> line. For example, in Java mode this
    115. 

  115.    property is set to <quote>}</quote>.</para></listitem>
    116. 

  116.    <listitem><para><literal>indentOpenBrackets</literal> -
    117. 

  117.    A list of characters (usually brackets) that add indent to
    118. 

  118.    the <emphasis>next</emphasis> line. For example, in Java mode this
    119. 

  119.    property is set to <quote>{</quote>.</para></listitem>
    120. 

  120.    <listitem><para><literal>indentPrevLine</literal> -
    121. 

  121.    When indenting a line, jEdit checks if the previous line matches
    122. 

  122.    the regular expression stored in this property. If it does, a level
    123. 

  123.    of indent is added. For example, in Java mode this regular expression
    124. 

  124.    matches language constructs such as
    125. 

  125.    <quote>if</quote>, <quote>else</quote>, <quote>while</quote>, etc.</para>
    126. 

  126.    </listitem>
    127. 

  127.    <listitem><para><literal>doubleBracketIndent</literal> -
    128. 

  128.    If a line matches the <literal>indentPrevLine</literal> regular
    129. 

  129.    expression and the next line contains an opening bracket,
    130. 

  130.    a level of indent will not be added to the next line, unless
    131. 

  131.    this property is set to <quote>true</quote>. For example, with this
    132. 

  132.    property set to <quote>false</quote>, Java code will be indented like so:
    133. 

  133.    </para>
    134. 

  134.    <programlisting>while(objects.hasMoreElements())
    135. 

  135. {
    136. 

  136.         ((Drawable)objects.nextElement()).draw();
    137. 

  137. }</programlisting>
    138. 

  138.    <para>
    139. 

  139.      On the other hand, settings this property to <quote>true</quote> will
    140. 

  140.      give the following result:
    141. 

  141.    </para>
    142. 

  142.      <programlisting>while(objects.hasMoreElements())
    143. 

  143.         {
    144. 

  144.                 ((Drawable)objects.nextElement()).draw();
    145. 

  145.         }</programlisting></listitem>
    146. 

  146.   </itemizedlist>
    147. 

  147.   <para>
    148. 

  148.    Here is the complete <literal>&lt;PROPS&gt;</literal> tag for Java mode:
    149. 

  149.   </para>
    150. 

  150.   <programlisting>&lt;PROPS&gt;
    151. 

  151.     &lt;PROPERTY NAME="indentOpenBrackets" VALUE="{" /&gt;
    152. 

  152.     &lt;PROPERTY NAME="indentCloseBrackets" VALUE="}" /&gt;
    153. 

  153.     &lt;PROPERTY NAME="indentPrevLine" VALUE="\s*(((if|while)
    154. 

  154.         \s*\(|else|case|default)[^;]*|for\s*\(.*)" /&gt;
    155. 

  155.     &lt;PROPERTY NAME="doubleBracketIndent" VALUE="false" /&gt;
    156. 

  156.     &lt;PROPERTY NAME="commentStart" VALUE="/*" /&gt;
    157. 

  157.     &lt;PROPERTY NAME="commentEnd" VALUE="*/" /&gt;
    158. 

  158.     &lt;PROPERTY NAME="blockComment" VALUE="//" /&gt;
    159. 

  159.     &lt;PROPERTY NAME="wordBreakChars" VALUE=",+-=&lt;&gt;/?^&amp;*" /&gt;
    160. 

  160. &lt;/PROPS&gt;</programlisting>
    161. 

  161.  </sect1>
    162. 

  162.  <sect1 id="mode-tag-rules"><title>The RULES Tag</title>
    163. 

  163.   <para>
    164. 

  164.    <literal>RULES</literal> tags must be placed inside the
    165. 

  165.    <literal>MODE</literal> tag. Each <literal>RULES</literal> tag defines a
    166. 

  166.    <firstterm>ruleset</firstterm>. A ruleset consists of a number of
    167. 

  167.    <firstterm>parser rules</firstterm>, with each parser
    168. 

  168.    rule specifying how to highlight a specific syntax token. There must
    169. 

  169.    be at least one ruleset in each edit mode. There can also be more
    170. 

  170.    than one, with different rulesets being used to highlight different
    171. 

  171.    parts of a buffer (for example, in HTML mode, one rule set
    172. 

  172.    highlights HTML tags, and another highlights inline JavaScript).
    173. 

  173.    For information about using more
    174. 

  174.    than one ruleset, see <xref linkend="mode-rule-span" />.
    175. 

  175.   </para>
    176. 

  176.   <para>
    177. 

  177.    The <literal>RULES</literal> tag supports the following attributes, all of
    178. 

  178.    which are optional:
    179. 

  179.   </para>
    180. 

  180.   <itemizedlist>
    181. 

  181.    <listitem><para><literal>SET</literal> - the name of this ruleset.
    182. 

  182.    All rulesets other than the first must have a name.
    183. 

  183.    </para></listitem>
    184. 

  184.    <listitem><para><literal>HIGHLIGHT_DIGITS</literal> - if set to
    185. 

  185.    <literal>TRUE</literal>, digits (0-9, as well as hexadecimal literals
    186. 

  186.    prefixed with <quote>0x</quote>) will be highlighted with the
    187. 

  187.    <classname>DIGIT</classname> token type. Default is <literal>FALSE</literal>.
    188. 

  188.    </para></listitem>
    189. 

  189.    <listitem><para><literal>IGNORE_CASE</literal> - if set to
    190. 

  190.    <literal>FALSE</literal>, matches will be case sensitive. Otherwise, case
    191. 

  191.    will not matter. Default is <literal>TRUE</literal>.
    192. 

  192.    </para></listitem>
    193. 

  193.    <listitem><para><literal>DEFAULT</literal> - the token type for
    194. 

  194.    text which doesn't match
    195. 

  195.    any specific rule. Default is <literal>NULL</literal>. See
    196. 

  196.    <xref linkend="mode-syntax-tokens" /> for a list of token types.
    197. 

  197.    </para></listitem>
    198. 

  198.   </itemizedlist>
    199. 

  199.   <para>
    200. 

  200.    Here is an example <literal>RULES</literal> tag:
    201. 

  201.   </para>
    202. 

  202.   <programlisting>&lt;RULES IGNORE_CASE="FALSE" HIGHLIGHT_DIGITS="TRUE"&gt;
    203. 

  203.     <replaceable>... parser rules go here ...</replaceable>
    204. 

  204. &lt;/RULES&gt;</programlisting>
    205. 

  205.   <sidebar><title>Rule Ordering Requirements</title>
    206. 

  206.    <para>
    207. 

  207.     You might encounter this very common pitfall when writing your own modes.
    208. 

  208.    </para>
    209. 

  209.    <para>
    210. 

  210.     Since jEdit checks buffer text against parser rules in the order they appear
    211. 

  211.     in the ruleset, more specific rules must be placed before generalized ones,
    212. 

  212.     otherwise the generalized rules will catch everything.
    213. 

  213.    </para>
    214. 

  214.    <para>
    215. 

  215.     This is best demonstrated with an example. The following is incorrect rule
    216. 

  216.     ordering:
    217. 

  217.    </para>
    218. 

  218.    <programlisting><![CDATA[<SPAN TYPE="MARKUP">
    219. 

  219.     <BEGIN>[</BEGIN>
    220. 

  220.     <END>]</END>
    221. 

  221. </SPAN>
    222. 

  222. 

  223. <SPAN TYPE="KEYWORD1">
    224. 

  224.     <BEGIN>[!</BEGIN>
    225. 

  225.     <END>]</END>
    226. 

  226. </SPAN>]]></programlisting>
    227. 

  227.    <para>
    228. 

  228.     If you write the above in a rule set, any occurrence of <quote>[</quote>
    229. 

  229.     (even things like <quote>[!DEFINE</quote>, etc) 
    230. 

  230.     will be highlighted using the first rule, because it will be the
    231. 

  231.     first to match. This is most likely not the intended behavior.
    232. 

  232.    </para>
    233. 

  233.    <para>
    234. 

  234.     The problem can be solved by placing the more specific rule before the
    235. 

  235.     general one:
    236. 

  236.    </para>
    237. 

  237.    <programlisting><![CDATA[<SPAN TYPE="KEYWORD1">
    238. 

  238.     <BEGIN>[!</BEGIN>
    239. 

  239.     <END>]</END>
    240. 

  240. </SPAN>
    241. 

  241. 

  242. <SPAN TYPE="MARKUP">
    243. 

  243.     <BEGIN>[</BEGIN>
    244. 

  244.     <END>]</END>
    245. 

  245. </SPAN>]]></programlisting>
    246. 

  246.    <para>
    247. 

  247.     Now, if the buffer contains the text <quote>[!SPECIAL]</quote>, the
    248. 

  248.     rules will be checked in order, and the first rule will be the first
    249. 

  249.     to match. However, if you write <quote>[FOO]</quote>, it will be highlighted
    250. 

  250.     using the second rule, which is exactly what you would expect.
    251. 

  251.    </para>
    252. 

  252.   </sidebar>
    253. 

  253.   <sect2 id="mode-rule-terminate"><title>The TERMINATE Rule</title>
    254. 

  254.    <para>
    255. 

  255.     The <literal>TERMINATE</literal> rule specifies that parsing should stop
    256. 

  256.     after the specified number of characters have been read from a line. The
    257. 

  257.     number of characters to terminate after should be specified with the
    258. 

  258.     <literal>AT_CHAR</literal> attribute. Here is an example:
    259. 

  259.    </para>
    260. 

  260.    <programlisting>&lt;TERMINATE AT_CHAR="1" /&gt;</programlisting>
    261. 

  261.    <para>
    262. 

  262.     This rule is used in Patch mode, for example, because only the first
    263. 

  263.     character of each line affects highlighting. 
    264. 

  264.    </para>
    265. 

  265.   </sect2>
    266. 

  266.   <sect2 id="mode-rule-whitespace"><title>The WHITESPACE Rule</title>
    267. 

  267.    <para>
    268. 

  268.     The <literal>WHITESPACE</literal> rule specifies characters which are to
    269. 

  269.     be treated as keyword delimiters.
    270. 

  270.     Most rulesets will have <literal>WHITESPACE</literal> tags for spaces and
    271. 

  271.     tabs. Here is an example:
    272. 

  272.    </para>
    273. 

  273.    <programlisting>&lt;WHITESPACE&gt; &lt;/WHITESPACE&gt;
    274. 

  274. &lt;WHITESPACE&gt;        &lt;/WHITESPACE&gt;</programlisting>
    275. 

  275.   </sect2>
    276. 

  276.   <sect2 id="mode-rule-span"><title>The SPAN Rule</title>
    277. 

  277.    <para>
    278. 

  278.     The <literal>SPAN</literal> rule highlights text between a start
    279. 

  279.     and end string. The start and end strings are specified inside
    280. 

  280.     child elements of the <literal>SPAN</literal> tag.
    281. 

  281.     The following attributes are supported:
    282. 

  282.    </para>
    283. 

  283.    <itemizedlist>
    284. 

  284.     <listitem><para><literal>TYPE</literal> - The token type to highlight the
    285. 

  285.     span with. See <xref linkend="mode-syntax-tokens" /> for a list of token
    286. 

  286.     types</para></listitem>
    287. 

  287.     <listitem><para><literal>AT_LINE_START</literal> - If set to
    288. 

  288.     <literal>TRUE</literal>, the span will only be highlighted if the start
    289. 

  289.     sequence occurs at the beginning of a line</para></listitem>
    290. 

  290.     <listitem><para><literal>EXCLUDE_MATCH</literal> - If set to
    291. 

  291.     <literal>TRUE</literal>, the start and end sequences will not be highlighted,
    292. 

  292.     only the text between them will</para></listitem>
    293. 

  293.     <listitem><para><literal>NO_LINE_BREAK</literal> - If set to
    294. 

  294.     <literal>TRUE</literal>, the span will be highlighted with the
    295. 

  295.     <classname>INVALID</classname> token type if it spans more than one
    296. 

  296.     line</para></listitem>
    297. 

  297.     <listitem><para><literal>NO_WORD_BREAK</literal> - If set to
    298. 

  298.     <literal>TRUE</literal>, the span will be highlighted with the
    299. 

  299.     <classname>INVALID</classname> token type if it includes
    300. 

  300.     whitespace</para></listitem>
    301. 

  301.     <listitem><para><literal>DELEGATE</literal> - text inside the span will be
    302. 

  302.     highlighted with the specified ruleset. To delegate to a ruleset defined
    303. 

  303.     in the current mode, just specify its name. To delegate to a ruleset
    304. 

  304.     defined in another mode, specify a name of the form
    305. 

  305.     <literal><replaceable>mode</replaceable>::<replaceable>ruleset</replaceable></literal>.
    306. 

  306.     Note that the first (unnamed) ruleset in a mode is called
    307. 

  307.     <quote>MAIN</quote>.</para></listitem>
    308. 

  308.    </itemizedlist>
    309. 

  309.    <note>
    310. 

  310.     <para>
    311. 

  311.      Do not delegate to rulesets that define a <literal>TERMINATE</literal> rule
    312. 

  312.      (examples of such rulesets include <literal>text::MAIN</literal> and
    313. 

  313.      <literal>patch::MAIN</literal>). It won't work.
    314. 

  314.     </para>
    315. 

  315.    </note>
    316. 

  316.    <para>
    317. 

  317.     Here is a <literal>SPAN</literal> that highlights Java string literals,
    318. 

  318.     which cannot include line breaks:
    319. 

  319.    </para>
    320. 

  320.    <programlisting>&lt;SPAN TYPE="LITERAL1" NO_LINE_BREAK="TRUE"&gt;
    321. 

  321.    &lt;BEGIN&gt;"&lt;/BEGIN&gt;
    322. 

  322.    &lt;END&gt;"&lt;/END&gt;
    323. 

  323. &lt;/SPAN&gt;</programlisting>
    324. 

  324.    <para>
    325. 

  325.     Here is a <literal>SPAN</literal> that highlights Java documentation
    326. 

  326.     comments by delegating to the <quote>JAVADOC</quote> ruleset defined
    327. 

  327.     elsewhere in the current mode:
    328. 

  328.    </para>
    329. 

  329.    <programlisting>&lt;SPAN TYPE="COMMENT2" DELEGATE="JAVADOC"&gt;
    330. 

  330.    &lt;BEGIN&gt;/**&lt;/BEGIN&gt;
    331. 

  331.    &lt;END&gt;*/&lt;/END&gt;
    332. 

  332. &lt;/SPAN&gt;</programlisting>
    333. 

  333.    <para>
    334. 

  334.     Here is a <literal>SPAN</literal> that highlights HTML cascading stylesheets
    335. 

  335.     inside <literal>&lt;STYLE&gt;</literal> tags by delegating to the main
    336. 

  336.     ruleset in the CSS edit mode:
    337. 

  337.    </para>
    338. 

  338.    <programlisting>&lt;SPAN TYPE="MARKUP" DELEGATE="css::MAIN"&gt;
    339. 

  339.    &lt;BEGIN&gt;&amp;lt;style&amp;gt;&lt;/BEGIN&gt;
    340. 

  340.    &lt;END&gt;&amp;lt;/style&amp;gt;&lt;/END&gt;
    341. 

  341. &lt;/SPAN&gt;</programlisting>
    342. 

  342.    <tip>
    343. 

  343.     <para>
    344. 

  344.      The <literal>&lt;END&gt;</literal> tag is optional. If it is not specified,
    345. 

  345.      any occurrence of the start string will cause the remainder of the buffer
    346. 

  346.      to be highlighted with this rule.
    347. 

  347.     </para>
    348. 

  348.     <para>
    349. 

  349.      This can be very useful when combined with delegation.
    350. 

  350.     </para>
    351. 

  351.    </tip>
    352. 

  352.   </sect2>
    353. 

  353.   <sect2 id="mode-rule-eol-span"><title>The EOL_SPAN Rule</title>
    354. 

  354.    <para>
    355. 

  355.     An <literal>EOL_SPAN</literal> is similar to a <literal>SPAN</literal>
    356. 

  356.     except that highlighting stops at the end of the line, not after the end
    357. 

  357.     sequence is found. The text to match is specified between the opening and
    358. 

  358.     closing <literal>EOL_SPAN</literal> tags.
    359. 

  359.     The following attributes are supported:
    360. 

  360.    </para>
    361. 

  361.    <itemizedlist>
    362. 

  362.     <listitem><para><literal>TYPE</literal> - The token type to highlight the span
    363. 

  363.     with. See <xref linkend="mode-syntax-tokens" /> for a list of token
    364. 

  364.     types</para></listitem>
    365. 

  365.     <listitem><para><literal>AT_LINE_START</literal> - If set to
    366. 

  366.     <literal>TRUE</literal>, the span will only be highlighted if the start
    367. 

  367.     sequence occurs at the beginning of a line</para></listitem>
    368. 

  368.     <listitem><para><literal>EXCLUDE_MATCH</literal> - If set to
    369. 

  369.     <literal>TRUE</literal>, the start sequence will not be highlighted,
    370. 

  370.     only the text after it will</para></listitem>
    371. 

  371.    </itemizedlist>
    372. 

  372.    <para>
    373. 

  373.     Here is an <literal>EOL_SPAN</literal> that highlights C++ comments:
    374. 

  374.    </para>
    375. 

  375.    <programlisting>&lt;EOL_SPAN TYPE="COMMENT1"&gt;//&lt;/EOL_SPAN&gt;</programlisting>
    376. 

  376.   </sect2>
    377. 

  377.   <sect2 id="mode-rule-mark-prev"><title>The MARK_PREVIOUS Rule</title>
    378. 

  378.    <para>
    379. 

  379.     The <literal>MARK_PREVIOUS</literal> rule highlights from the end of the
    380. 

  380.     previous syntax token to the matched text. The text to match
    381. 

  381.     is specified between opening and closing <literal>MARK_PREVIOUS</literal>
    382. 

  382.     tags. The following attributes are supported:
    383. 

  383.    </para>
    384. 

  384.    <itemizedlist>
    385. 

  385.     <listitem><para><literal>TYPE</literal> - The token type to highlight the
    386. 

  386.     text with. See <xref linkend="mode-syntax-tokens" /> for a list of token
    387. 

  387.     types</para></listitem>
    388. 

  388.     <listitem><para><literal>AT_LINE_START</literal> - If set to
    389. 

  389.     <literal>TRUE</literal>,
    390. 

  390.     the text will only be highlighted if it occurs at the beginning of
    391. 

  391.     the line</para></listitem>
    392. 

  392.     <listitem><para><literal>EXCLUDE_MATCH</literal> - If set to
    393. 

  393.     <literal>TRUE</literal>, the match will not be highlighted,
    394. 

  394.     only the text before it will</para></listitem>
    395. 

  395.    </itemizedlist>
    396. 

  396.    <para>
    397. 

  397.     Here is a rule that highlights labels in Java mode (for example,
    398. 

  398.     <quote>XXX:</quote>):
    399. 

  399.    </para>
    400. 

  400.    <programlisting>&lt;MARK_PREVIOUS AT_LINE_START="TRUE"
    401. 

  401.     EXCLUDE_MATCH="TRUE"&gt;:&lt;/MARK_PREVIOUS&gt;</programlisting>
    402. 

  402.   </sect2>
    403. 

  403.   <sect2 id="mode-rule-mark-following"><title>The MARK_FOLLOWING Rule</title>
    404. 

  404.    <para>
    405. 

  405.     The <literal>MARK_FOLLOWING</literal> rule highlights from the start of the
    406. 

  406.     match to the next syntax token. The text to match
    407. 

  407.     is specified between opening and closing <literal>MARK_FOLLOWING</literal>
    408. 

  408.     tags. The following attributes are supported:
    409. 

  409.    </para>
    410. 

  410.    <itemizedlist>
    411. 

  411.     <listitem><para><literal>TYPE</literal> - The token type to highlight the
    412. 

  412.     text with. See <xref linkend="mode-syntax-tokens" /> for a list of token
    413. 

  413.     types</para></listitem>
    414. 

  414.     <listitem><para><literal>AT_LINE_START</literal> - If set to
    415. 

  415.     <literal>TRUE</literal>, the text will only be highlighted if the start
    416. 

  416.     sequence occurs at the beginning of a line</para></listitem>
    417. 

  417.     <listitem><para><literal>EXCLUDE_MATCH</literal> - If set to
    418. 

  418.     <literal>TRUE</literal>, the match will not be highlighted,
    419. 

  419.     only the text after it will</para></listitem>
    420. 

  420.    </itemizedlist>
    421. 

  421.    <para>
    422. 

  422.     Here is a rule that highlights variables in Unix shell scripts
    423. 

  423.     (<quote>$CLASSPATH</quote>, <quote>$IFS</quote>, etc):
    424. 

  424.    </para>
    425. 

  425.    <programlisting>&lt;MARK_FOLLOWING TYPE="KEYWORD2"&gt;$&lt;/MARK_FOLLOWING&gt;</programlisting>
    426. 

  426.   </sect2>
    427. 

  427.   <sect2 id="mode-rule-seq"><title>The SEQ Rule</title>
    428. 

  428.    <para>
    429. 

  429.     The <literal>SEQ</literal> rule highlights fixed sequences of text. The text
    430. 

  430.     to highlight is specified between opening and closing <literal>SEQ</literal>
    431. 

  431.     tags. The following attributes are supported:
    432. 

  432.    </para>
    433. 

  433.    <itemizedlist>
    434. 

  434.     <listitem><para><literal>TYPE</literal> - the token type to highlight the
    435. 

  435.     sequence with. See <xref linkend="mode-syntax-tokens" /> for a list of token
    436. 

  436.     types</para></listitem>
    437. 

  437.     <listitem><para><literal>AT_LINE_START</literal> - If set to
    438. 

  438.     <literal>TRUE</literal>, the sequence will only be highlighted if it occurs
    439. 

  439.     at the beginning of a line</para></listitem>
    440. 

  440.    </itemizedlist>
    441. 

  441.    <para>
    442. 

  442.     The following rules highlight a few Java operators:
    443. 

  443.    </para>
    444. 

  444.    <programlisting>&lt;SEQ TYPE="OPERATOR"&gt;+&lt;/SEQ&gt;
    445. 

  445. &lt;SEQ TYPE="OPERATOR"&gt;-&lt;/SEQ&gt;
    446. 

  446. &lt;SEQ TYPE="OPERATOR"&gt;*&lt;/SEQ&gt;
    447. 

  447. &lt;SEQ TYPE="OPERATOR"&gt;/&lt;/SEQ&gt;</programlisting>
    448. 

  448.   </sect2>
    449. 

  449.   <sect2 id="mode-rule-keywords"><title>The KEYWORDS Rule</title>
    450. 

  450.    <para>
    451. 

  451.     There can only be one <literal>KEYWORDS</literal> tag per ruleset.
    452. 

  452.     The <literal>KEYWORDS</literal> rule defines keywords to highlight.
    453. 

  453.     Keywords are similar to <literal>SEQ</literal>s, except that
    454. 

  454.     <literal>SEQ</literal>s match anywhere in the text, whereas keywords only
    455. 

  455.     match whole words.
    456. 

  456.    </para>
    457. 

  457.    <para>
    458. 

  458.     The <literal>KEYWORDS</literal> tag supports only one attribute,
    459. 

  459.     <literal>IGNORE_CASE</literal>. If set to <literal>FALSE</literal>, keywords
    460. 

  460.     will be case sensitive. Otherwise, case will not matter. Default is
    461. 

  461.     <literal>TRUE</literal>.
    462. 

  462.    </para>
    463. 

  463.    <para>
    464. 

  464.     Each child element of the <literal>KEYWORDS</literal> tag should be named
    465. 

  465.     after the desired token type, with the keyword text between the start and
    466. 

  466.     end tags. For example, the following rule highlights the most common Java
    467. 

  467.     keywords:
    468. 

  468.    </para>
    469. 

  469.    <programlisting>&lt;KEYWORDS IGNORE_CASE="FALSE"&gt;
    470. 

  470.    &lt;KEYWORD1&gt;if&lt;/KEYWORD1&gt;
    471. 

  471.    &lt;KEYWORD1&gt;else&lt;/KEYWORD1&gt;
    472. 

  472.    &lt;KEYWORD3&gt;int&lt;/KEYWORD3&gt;
    473. 

  473.    &lt;KEYWORD3&gt;void&lt;/KEYWORD3&gt;
    474. 

  474. &lt;/KEYWORDS&gt;</programlisting>
    475. 

  475.   </sect2>
    476. 

  476.   <sect2 id="mode-syntax-tokens"><title>Token Types</title>
    477. 

  477.    <para>
    478. 

  478.     Parser rules can highlight tokens using any of the following token
    479. 

  479.     types:
    480. 

  480.    </para>
    481. 

  481.    <itemizedlist>
    482. 

  482.    <listitem><para><literal>NULL</literal> - no special
    483. 

  483.    highlighting is performed on tokens of type <literal>NULL</literal>
    484. 

  484.    </para></listitem>
    485. 

  485.    <listitem><para><literal>COMMENT1</literal>
    486. 

  486.    </para></listitem>
    487. 

  487.    <listitem><para><literal>COMMENT2</literal>
    488. 

  488.    </para></listitem>
    489. 

  489.    <listitem><para><literal>FUNCTION</literal>
    490. 

  490.    </para></listitem>
    491. 

  491.    <listitem><para><literal>INVALID</literal> - tokens of this type are
    492. 

  492.    automatically added if a <literal>NO_WORD_BREAK</literal> or
    493. 

  493.    <literal>NO_LINE_BREAK</literal> <literal>SPAN</literal> spans more than
    494. 

  494.    one word or line, respectively.
    495. 

  495.    </para></listitem>
    496. 

  496.    <listitem><para><literal>KEYWORD1</literal>
    497. 

  497.    </para></listitem>
    498. 

  498.    <listitem><para><literal>KEYWORD2</literal>
    499. 

  499.    </para></listitem>
    500. 

  500.    <listitem><para><literal>KEYWORD3</literal>
    501. 

  501.    </para></listitem>
    502. 

  502.    <listitem><para><literal>LABEL</literal>
    503. 

  503.    </para></listitem>
    504. 

  504.    <listitem><para><literal>LITERAL1</literal>
    505. 

  505.    </para></listitem>
    506. 

  506.    <listitem><para><literal>LITERAL2</literal>
    507. 

  507.    </para></listitem>
    508. 

  508.    <listitem><para><literal>MARKUP</literal>
    509. 

  509.    </para></listitem>
    510. 

  510.    <listitem><para><literal>OPERATOR</literal>
    511. 

  511.    </para></listitem>
    512. 

  512.    </itemizedlist>
    513. 

  513.   </sect2>
    514. 

  514.  </sect1>
    515. 

  515. </chapter>
    516.