<!--
        Copyright (c) 2001 Joseph Wenninger <jowenn@kde.org>
        modified (c) 2002 Anders Lund <anders@alweb.dk>
        modified (c) 2003 Simon Huerlimann <simon.huerlimann@access.unizh.ch>

        This file describes the XML format used for syntax highlight descriptions
        for the Kate text editor (http://kate.kde.org), which is part of the KDE
        desktop environment (http://www.kde.org).
        You'll find the "Writing a Kate Highlighting XML File HOWTO" at
        http://kate.kde.org/doc/hlhowto.php

        This format is identified using the SYSTEM identifier
        SYSTEM "language.dtd"

        Files using this format should include a DOCTYPE declaration like this:
        <!DOCTYPE language SYSTEM "language.dtd">

        You can validate your syntax files using checkXML from the development
        package of kdelibs:
         checkXML yourSyntax.xml
        If you see any 'validity error' lines, you should fix them. If you get
        a lot of 'No template matches' lines, everything's just fine. You've
        produced a valid syntax file!

        It's also possible to use the (much faster) xmllint which comes with the
        GNOME (oops:-) XML Library libxml2:

         xmllint - -dtdvalid language.dtd yourSyntax.xml
	 (don't use a space between the two - That's just because XML
         comments don't allow that:-(

        To use your syntax file, copy it to .kde/share/apps/katepart/syntax/ in
        your home directory. You have to open a new instance of kwrite/kate to use
        the new syntax file.

TODO
  - find a more readable way for the - -dtdvalid stuff, it's just annoying
    xml comments don't allow it.
-->

<!-- Entity declarations
  You can use '&per;' instead of '.'. This seems to be useful in <item> elements.

TODO
  - Are there any more such pre-defined entities?
-->
<!ENTITY per "." >

<!-- Boolean type
  Attributes that are of type boolean allow the following values:
  'true', 'TRUE' and '1' all meaning true,
  'false', FALSE' and '0' all meaning false.

  It is encouraged to use 'true' and 'false' instead of the alternatives.
-->
<!ENTITY % boolean "true|false|TRUE|FALSE|0|1">

<!-- Language specification
  name:        The name of this syntax description. Used in the Highlightning Mode menu
  section:     The logical group to which this syntax description belongs. Used for sub menus
  extensions:  A file glob or pattern to decide for which documents to use this syntax description
  mimetype:    A list of mimetypes to decide for which documents to use this syntax description [optional]
  version:     Version number of this syntax description [optional]
  kateversion: Kate version required for using this file [optional]
  casesensitive: Whether text is matched case sensitive. [boolean, optional, default=false]
  priority:    Priority of this language, if more than one are usable for the file [optional]

TODO
  - Which matches are affected by casesensitive? keyword, RegExpr, StringDetect...?
-->
<!ELEMENT language (highlighting, general?)>
<!ATTLIST language
  name          CDATA       #REQUIRED
  section       NMTOKEN     #REQUIRED
  extensions    CDATA       #REQUIRED
  mimetype      CDATA       #IMPLIED
  version       CDATA       #IMPLIED
  kateversion   CDATA       #IMPLIED
  casesensitive (%boolean;) #IMPLIED
  priority      CDATA       #IMPLIED
>

<!-- General options -->
<!ELEMENT general (comments|keywords)*>

<!-- List of comments -->
<!ELEMENT comments (comment)+>

<!-- Comment specification
  name:         Type of this comment. Allowed are 'singleLine' and 'multiLine'
  start:        The comment starts with this string
  end:          The comment ends with this string [optional]
-->
<!ELEMENT comment EMPTY>
<!ATTLIST comment
  name      (singleLine|multiLine)  #REQUIRED
  start     CDATA                   #REQUIRED
  end       CDATA                   #IMPLIED
>

<!-- Keyword options
  casesensitive:        Whether keywords are matched case sensitive. [boolean, optional, default=false]
  weakDeliminator:      Add weak deliminators [optional]
  additionalDeliminator: Add deliminators [optional]

TODO
  - Explain (weak) deliminators
-->
<!ELEMENT keywords EMPTY>
<!ATTLIST keywords
  casesensitive         CDATA   #IMPLIED
  weakDeliminator       CDATA   #IMPLIED
  additionalDeliminator CDATA   #IMPLIED
>

<!-- Highlighting specification -->
<!ELEMENT highlighting (list*, contexts, itemDatas)>
<!ATTLIST highlighting
>

<!-- List of items
  name:     Name of this list
-->
<!ELEMENT list (item)*>
<!ATTLIST list
  name  CDATA   #REQUIRED
>

<!-- List item
  contains string used in <keyword>
-->
<!ELEMENT item (#PCDATA)>

<!-- List of contexts -->
<!ELEMENT contexts (context)+>

<!-- context specification
  name:             The name of this context specification. Used in '*Context' attributes [optional]
  attribute:        The name of the ItemData to be used for matching text
  lineEndContext:   Next context if end of line is encountered
  lineBeginContext: Next context if begin of line is encountered [optional]
  fallthrough:      Use a fallthrough context [optional]
  fallthroughContext: Fall through to this context [optional]

TODO:
  - Explain fallthrough.
  - Do we need fallthrough at all? It could be true, if fallthroughContext is set, false otherwhise.
  - Make lineEndContext optional, defaults to '#stay'. Reasonable?
-->
<!ELEMENT context (keyword | Float | HlCOct | HlCHex | HlCFloat | Int | DetectChar | Detect2Chars | AnyChar | StringDetect | RegExpr | LineContinue | HlCStringChar | RangeDetect | HlCChar | IncludeRules)*>
<!ATTLIST context
  name              CDATA       #IMPLIED
  attribute         CDATA       #REQUIRED
  lineEndContext    CDATA       #REQUIRED
  lineBeginContext  CDATA       #IMPLIED
  fallthrough       (%boolean;) #IMPLIED
  fallthroughContext CDATA      #IMPLIED
>

<!-- Common attributes
  attribute:    The name of the ItemData to be used for matching text
  context:      The name of the context to go to when this rule matches
  beginRegion:  Begin a region of type beginRegion [optional]
  endRegion:    End a region of type endRegion [optional]
-->
<!ENTITY % commonAttributes
 "attribute     CDATA   #REQUIRED
  context       CDATA   #REQUIRED
  beginRegion   CDATA   #IMPLIED
  endRegion     CDATA   #IMPLIED"
>

<!-- Detect members of a keyword list
  commonAttributes: Common attributes
  String:           Name of the list
  weakDelimiter:    Use weak deliminator

TODO:
  - Should be weakDeliminator
  - Explain deliminator
  - Doesn't seem to be suported in highligh.cpp
-->
<!ELEMENT keyword EMPTY>
<!ATTLIST keyword
  %commonAttributes;
  String    CDATA   #REQUIRED
  weakDelimiter CDATA #IMPLIED
>

<!-- Detect a floating point number
  commonAttributes: Common attributes
-->
<!ELEMENT Float (AnyChar)*>
<!ATTLIST Float
  %commonAttributes;
>

<!-- Detect an octal number
  commonAttributes: Common attributes
-->
<!ELEMENT HlCOct EMPTY>
<!ATTLIST HlCOct
  %commonAttributes;
>

<!-- Detect a hexadecimal number
  commonAttributes: Common attributes
-->
<!ELEMENT HlCHex EMPTY>
<!ATTLIST HlCHex
  %commonAttributes;
>

<!-- Detect a C-style floating point number
  commonAttributes: Common attributes
-->
<!ELEMENT HlCFloat EMPTY>
<!ATTLIST HlCFloat
  %commonAttributes;
>

<!-- Detect C-style character
  commonAttributes: Common attributes

TODO
  - Did I get this right?
-->
<!ELEMENT HlCChar EMPTY>
<!ATTLIST HlCChar
  %commonAttributes;
>

<!-- Detect an integer number
  commonAttributes: Common attributes
-->
<!ELEMENT Int (StringDetect)*>
<!ATTLIST Int
  %commonAttributes;
>

<!-- Detect a single character
  commonAttributes: Common attributes
  char:             The character to look for
-->
<!ELEMENT DetectChar EMPTY>
<!ATTLIST DetectChar
  %commonAttributes;
  char          CDATA   #REQUIRED
>

<!-- Detect two characters
  commonAttributes: Common attributes
  char:             The first character
  char1:            The second character
-->
<!ELEMENT Detect2Chars EMPTY>
<!ATTLIST Detect2Chars
  %commonAttributes;
  char          CDATA   #REQUIRED
  char1         CDATA   #REQUIRED
>

<!-- Detect any group of characters
  commonAttributes: Common attributes
  String:           A string representing the characters to look for

TODO
  - Description is not descriptive enough, I'm not sure what it exactly does:-(
-->
<!ELEMENT AnyChar EMPTY>
<!ATTLIST AnyChar
  %commonAttributes;
  String        CDATA   #REQUIRED
>

<!-- Detect a string
  commonAttributes: Common attributes
  String:           The string to look for
  insensitive:      Whether the string is matched case INsensitive. [boolean, optional, default=false]

TODO
  - What's default of insensitive? I'm not sure...
-->
<!ELEMENT StringDetect EMPTY>
<!ATTLIST StringDetect
  %commonAttributes;
  String        CDATA       #REQUIRED
  insensitive   (%boolean;)  #IMPLIED
>

<!-- Detect a match of a regular expression
  commonAttributes: Common attributes
  String:           The regular expression pattern
  insensitive:      Whether the text is matched case INsensitive. [boolean, optional, default=false]
  minimal:          Wheather to use minimal matching for wild cards in the pattern [boolean, optional, default='false']
-->
<!ELEMENT RegExpr EMPTY>
<!ATTLIST RegExpr
  %commonAttributes;
  String        CDATA       #REQUIRED
  insensitive   (%boolean;) #IMPLIED
  minimal       (%boolean;) #IMPLIED
>

<!-- Detect a line continuation
  commonAttributes: Common attributes
-->
<!ELEMENT LineContinue EMPTY>
<!ATTLIST LineContinue
  %commonAttributes;
>

<!-- Detect a C-style escaped character
  commonAttributes: Common attributes

TODO:
  - Did I get this right? Only one character, or a string?
-->
<!ELEMENT HlCStringChar EMPTY>
<!ATTLIST HlCStringChar
  %commonAttributes;
>

<!-- Detect a range of characters
  commonAttributes: Common attributes
  char:             The character starting the range
  char1:            The character terminating the range
-->
<!ELEMENT RangeDetect EMPTY>
<!ATTLIST RangeDetect
  %commonAttributes;
  char          CDATA   #REQUIRED
  char1         CDATA   #REQUIRED
>

<!-- Include Rules of another context
  context:             The name of the context to include
-->
<!ELEMENT IncludeRules EMPTY>
<!ATTLIST IncludeRules
  context       CDATA   #REQUIRED
>

<!-- List of attributes -->
<!ELEMENT itemDatas (itemData)+>
<!ATTLIST itemDatas
>

<!-- Attribute specification
  name          CDATA   #REQUIRED       The name of this attribute
  defStyleNum   CDATA   #REQUIRED       The index of the default style to use
  color         CDATA   #IMPLIED        Color for this style, either a hex triplet, a name or some other format recognized by Qt [optional]
  selColor      CDATA   #IMPLIED        The color for this style when text is selected [optional]
  italic        CDATA   #IMPLIED        Whether this attribute should be rendered using an italic typeface [optional, boolean, default=false]
  bold          CDATA   #IMPLIED        Whether this attribute should be renederd using a bold typeface [optional, boolean, default=false]
  underline     CDATA   #IMPLIED        Whether this attribute should be underlined [optional, boolean, default=false]
  strikeout     CDATA   #IMPLIED        Whether this attribute should be striked out [optional, boolean, default=false]
-->
<!ELEMENT itemData EMPTY>
<!ATTLIST itemData
  name          CDATA   #REQUIRED
  defStyleNum   CDATA   #REQUIRED
  color         CDATA   #IMPLIED
  selColor      CDATA   #IMPLIED
  italic        (%boolean;) #IMPLIED
  bold          (%boolean;) #IMPLIED
  underline     (%boolean;) #IMPLIED
  strikeout     (%boolean;) #IMPLIED
>
