path: root/kate/data/language.dtd

<!--
        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>
        modified (c) 2005 Dominik Haumann <dhdev@gmx.de>

        This file describes the XML format used for syntax highlight descriptions
        for the Kate text editor, which is part of the Trinity Desktop Environment.

        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 tdelibs:
         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">

<!-- Default Styles
  Allowed predefined default styles for itemData, available are:
    - dsNormal,   used for normal text
    - dsKeyword,  used for keywords
    - dsDataType, used for data types
    - dsDecVal,   used for decimal values
    - dsBaseN,    used for values with a base other than 10
    - dsFloat,    used for float values
    - dsChar,     used for a character
    - dsString,   used for strings
    - dsComment,  used for comments
    - dsOthers,   used for 'other' things
    - dsAlert,    used for warning messages
    - dsFunction, used for function calls
    - dsRegionMarker, used for region markers
    - dsError,    used for error highlighting.
-->
<!ENTITY % defStyles "dsNormal|dsKeyword|dsDataType|dsDecVal|dsBaseN|dsFloat|dsChar|dsString|dsComment|dsOthers|dsAlert|dsFunction|dsRegionMarker|dsError">

<!-- 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=true] FIXME: This is not implemented yet
  priority:    Priority of this language, if more than one are usable for the file [optional]
  author:      Name of author of this hl file [optional]
  license:     License for this hl file [optional]
  hidden:      Should it be hidden in menu [boolean, optional, default=false]

TODO
  - Which matches are affected by casesensitive? keyword, RegExpr, StringDetect...?

WARNING: due to helper scripts, the language opening tag must be on a
*single line* and *cannot* be split in multiple lines.

-->
<!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
  author        CDATA       #IMPLIED
  license       CDATA       #IMPLIED
  hidden        (%boolean;) #IMPLIED
>

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

<!-- List of folding
  indentationsensitive: If true, the code folding is indentation based.
-->
<!ELEMENT folding EMPTY>
<!ATTLIST folding
  indentationsensitive (%boolean;) #IMPLIED
>

<!-- 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]
  region:       The region name of the foldable multiline comment. If you have
                beginRegion="Comment" ... endRegion="Comment" you should use
                region="Comment". This way uncomment works even if you do not
                select all the text of the multiline comment.
  position:     only availalbe for type singleLine. Default is column0, to insert
                the single line comment characters after the whitespaces
                (= before the first non space) set position to "afterwhitespace"
-->
<!ELEMENT comment EMPTY>
<!ATTLIST comment
  name      (singleLine|multiLine)  #REQUIRED
  start     CDATA                   #REQUIRED
  end       CDATA                   #IMPLIED
  region    CDATA                   #IMPLIED
  position  (afterwhitespace)       #IMPLIED
>

<!-- Keyword options
  casesensitive:        Whether keywords are matched case sensitive. [boolean, optional, default=true]
  weakDeliminator:      Add weak deliminators [optional, default: ""]
  additionalDeliminator: Add deliminators [optional]
  wordWrapDeliminator:  characters that are used to wrap long lines [optional]

-->
<!ELEMENT keywords EMPTY>
<!ATTLIST keywords
  casesensitive         CDATA   #IMPLIED
  weakDeliminator       CDATA   #IMPLIED
  additionalDeliminator CDATA   #IMPLIED
  wordWrapDeliminator   CDATA   #IMPLIED
>

<!-- Indentation options
  mode:        indentation mode to use

TODO
  - Explain (weak) deliminators
-->
<!ELEMENT indentation EMPTY>
<!ATTLIST indentation
  mode         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]
  dynamic:          Dynamic context [boolean, 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 | DetectSpaces | DetectIdentifier)*>
<!ATTLIST context
  name              CDATA       #IMPLIED
  attribute         CDATA       #REQUIRED
  lineEndContext    CDATA       #REQUIRED
  lineBeginContext  CDATA       #IMPLIED
  fallthrough       (%boolean;) #IMPLIED
  fallthroughContext CDATA      #IMPLIED
  dynamic           (%boolean;) #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]
  firstNonSpace: should this rule only match at first non-space char in line?
  column: should this rule only match at given column in line (column == count of chars in front)
-->
<!ENTITY % commonAttributes
 "attribute     CDATA       #IMPLIED
  context       CDATA       #IMPLIED
  beginRegion   CDATA       #IMPLIED
  endRegion     CDATA       #IMPLIED
  lookAhead     (%boolean;) #IMPLIED
  firstNonSpace (%boolean;) #IMPLIED
  column        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
  AnyChar is allowed as a child rule. TODO: The source code allows
  *all* rules to be child rules, shall we change the DTD in some way?
-->
<!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
  StringDetect is allowed as a child rule. TODO: The source code allows
  *all* rules to be child rules, shall we change the DTD in some way?
-->
<!ELEMENT Int (StringDetect)*>
<!ATTLIST Int
  %commonAttributes;
>

<!-- Detect a single character
  commonAttributes: Common attributes
  char:             The character to look for
  dynamic:          Uses 0 ... 9 as placeholders for dynamic arguments (in fact, first char of arg...) [boolean, optional, default=false]
-->
<!ELEMENT DetectChar EMPTY>
<!ATTLIST DetectChar
  %commonAttributes;
  char          CDATA   #REQUIRED
  dynamic       (%boolean;) #IMPLIED
>

<!-- Detect two characters
  commonAttributes: Common attributes
  char:             The first character
  char1:            The second character
  dynamic:          Uses 0 ... 9 as placeholders for dynamic arguments (in fact, first char of arg...) [boolean, optional, default=false]
-->
<!ELEMENT Detect2Chars EMPTY>
<!ATTLIST Detect2Chars
  %commonAttributes;
  char          CDATA   #REQUIRED
  char1         CDATA   #REQUIRED
  dynamic       (%boolean;) #IMPLIED
>

<!-- 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]
  dynamic:          Uses %0 ... %9 as placeholders for dynamic arguments [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
  dynamic       (%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']
  dynamic:          Uses %0 ... %9 as placeholders for dynamic arguments [boolean, optional, default=false]
-->
<!ELEMENT RegExpr EMPTY>
<!ATTLIST RegExpr
  %commonAttributes;
  String        CDATA       #REQUIRED
  insensitive   (%boolean;) #IMPLIED
  minimal       (%boolean;) #IMPLIED
  dynamic       (%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
  includeAttrib:       If this is true, the host context of the IncludeRules
                       will be given the attribute of the source context
-->
<!ELEMENT IncludeRules EMPTY>
<!ATTLIST IncludeRules
  context       CDATA   #REQUIRED
  includeAttrib (%boolean;) #IMPLIED
>

<!-- Detect all following Spaces
-->
<!ELEMENT DetectSpaces EMPTY>
<!ATTLIST DetectSpaces
          %commonAttributes;
>

<!-- Detect an Identifier ( == LETTER(LETTER|NUMBER|_)*)
     -->
<!ELEMENT DetectIdentifier EMPTY>
<!ATTLIST DetectIdentifier
          %commonAttributes;
>

<!-- 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]
  backgroundColor    CDATA #IMPLIED     The background color for this style [optional]
  selBackgroundColor CDATA #IMPLIED     The background color for this style when text is selected [optional]
-->
<!ELEMENT itemData EMPTY>
<!ATTLIST itemData
  name          CDATA   #REQUIRED
  defStyleNum   (%defStyles;) #REQUIRED
  color         CDATA   #IMPLIED
  selColor      CDATA   #IMPLIED
  italic        (%boolean;) #IMPLIED
  bold          (%boolean;) #IMPLIED
  underline     (%boolean;) #IMPLIED
  strikeout     (%boolean;) #IMPLIED
  backgroundColor    CDATA  #IMPLIED
  selBackgroundColor CDATA  #IMPLIED
>