[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'