    [NAME]
    ALL.help.format

    [TITLE]
    Format of The Help Files

    [DESCRIPTION]

    Help files are regular Dao source files which contain mostly verbatim texts, and can be
    loaded as regular Dao modules. Such files must have the following loading statement
    before any use of verbatims:

       1  load help;

    Then the captions of the verbatims determine how they will be interpreted by the help
    system.

    Each verbatim that is captioned with "name" contains an ID string of the help entry,
    example:

       1  @[name]
       2  help.format
       3  @[name]

    All the help entries in the help system are organized as a tree. Such ID string instructs
    how this entry will be stored in the tree, and how it will be located. Each ID string is
    composed of multiple parts which are delimited by dots. There is one node in the tree
    that is corresponding to each part of the ID string.

    Each help entry may have a title which is represented by a verbatim text captioned by
    "title":

       1  @[title]
       2  Format of The Help Files
       3  @[title]

    The main text of the help must be placed in verbatim strings captioned with "text".
    Inside the text, several tags are supported for formatting the text:
      1. Referencing help entry:

            1  @[node]entry_id@[node]

         For example:

            1  @[node]help.format@[node]

         produces this help.format.
      2. Text coloring:

            1  @[foreground]text@[foreground]
            2  @[:background]text@[:background]
            3  @[foreground:background]text@[foreground:background]

         For example:

            1  @[blue]text@[blue]
            2  @[:green]text@[:green]
            3  @[blue:green]text@[blue:green]

         produce: text text text.
      3. Item listing:

            1  @[list]
            2  --Item 1;
            3  --Item 2;
            4  @[list]

         Use == for ordered list and -- for unordered list.
      4. Code highlighting:

            1  @[code(lang)]
            2  io.writeln( 'hello world!' );
            3  sum = 0
            4  for( i = 1 : 5 ) sum += i
            5  @[code(lang)]

         Where lang can be anything, but currently they will all be highlighted in the same
         way. (lang) can also be omitted.

         The above example produces:

            1  io.writeln( 'hello world!' );
            2  sum = 0
            3  for( i = 1 : 5 ) sum += i

    Tests of Dao scripts can be embedded into the help file by using a pair of @[code(test)]
    . The scripts embedded by this may declare the following global variables and constants
    for checking the status of the testing result:
      *  global __result__: this variable should be used to hold the object that needs
         checking;
      *  global __answer__: this variable should contain the expected value of __result__;
      *  cosnt __stdout__: this constant can be defined to hold the expected standard
         output;
      *  cosnt __stderr__: this constant can be defined for negative tests which must fail;
         it should contain a phrase that is expected to be found in the error message.

    An example to check a result object:

       1  tup = ( index => 123, 'abc' )
       2  tup.index = 456
       3
       4  global __result__ = tup
       5  global __answer__ = ( 456, 'abc' )

    An example to check the standard output:

       1  io.writeln( 'hello!' )
       2
       3  const __stdout__ = 'hello!\n'

    An example to check the error:

       1  tup = ( 123, 'abc' )
       2  idx = tup.non_existing_field
       3
       4  const __stderr__ = 'Member not exist'