Syntax Plugin Specifications:

Included in this document are the specifications of what is needed to write a 
a new module to extend the syntax highlighting support in Editra.

0: Before you begin
    - Editra uses Scintilla for its text control. Since documentation is not
      readily available, its suggested that you grab the Scintilla sources and 
      see what settings are available for each language.

1: File Specifications
    - The plugin file is a python module that provides the editor with the 
      information that it needs to properly setup the lexer.

2: What the plugin needs to provide

    CLASS: SyntaxData a subclass instance of syndata.SyntaxDataBase

    METHODS:
      - FUNCTION: GetKeywords(self)
        DESC: Provides a set of language keywords and their level to set in
              the editor.
        PARAM: None
        RETURN: A list of tuples.
        SPECIFICATIONS:
            The tuples in the list each contain two items.
                -The first item is an integer value specifying the Scintilla
                 keyword type to set for the Lexer.
                -The second is a string of space separated keywords.
        EXAMPLE RETURN: [(0, "spam ni"), (1, "monty python")]

      - FUNCTION: GetSyntaxSpec(self)
        DESC: This function is called to get the mapping of the stc style attributes
              to the Editra Style Sheet tags.
        PARAM: None
        RETURN: List of tuple string pairs, that pair the STC value to the wanted
                style tag.
        SPECIFICATIONS:
            The values in tuples of the return list must be ordered as follows
                - (STC_* value, Editra Style Tag)
        EXAMPLE RETURN: [('STC_C_DEFAULT', 'default_style'), 
                         ('STC_C_COMMENT', 'comment_style')] 

      - FUNCTION: GetProperties(self)
        DESC: This function is called to get any extra lexer properties that the
              editor should set for the given language.
        PARAM: None
        RETURN: List of tuples
        SPECIFICATIONS:
            The values in the tuples of the return list must be as follows
                - ("property", "value")
            If there are no needed  properties to set the function should
            return an empty list.
        EXAMPLE RETURN: [("fold", "1"), ("fold.comment", "1")]

    - FUNCTION: GetCommentPattern(self)
        DESC: Get the patern of comment meta characters to use for commenting
              out code in the given language.
        PARAM: None
        RETURN: Ordered List of strings
        SPECIFICATIONS:
            The returned list of strings must be in the order that the characters
            are to be added to the document. This only applies to languages that
            have multi character sequences required for comments.
        EXAMPLE RETURN:
            - Bash: [ "#" ]
            - C:    ["/*", "*/]


OPTIONAL EXTENSIONS:

Optional Features that language extensions can provide. These methods can be
added to a syntax module by using the syndata.SyntaxDataBase.RegisterFeature
method.

Currently Supported Features:

    - FUNCTION: StyleText(stc, start, end)
        DESC: Used for styling the text in a buffer that is using a container
              lexer.
        PARAM: stc The EditraStyledText control instance to do the styling in
        PARAM: start The start position of the styling
        PARAM: end The end position to style to
        SPECIFICATIONS: Register with the synglob.FEATURE_STYLETEXT id
        EXAMPLE:

    - FUNCTION: AutoIndenter(stc, current_pos, indent_char)
        DESC: Provide context sensitive auto indentation support
        PARAM: stc The buffer to do the indentation in
        PARAM: current_pos The current position of the caret in the buffer
        PARAM: indent_char Prefered character to use for indentation 
               ("\t" or " " * tabwidth)
        SPECIFICATIONS: Called when the Return key is hit. Note that the new
                        line character is not sent to the buffer so it needs
                        to be handled by this method. This method must also
                        call AddText to add the new whitespace to the buffer.

                        Register with the synglob.FEATURE_AUTOINDENT id