[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 befor
e any use of verbatims:
     
   1  load help;
     


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

Each verbatim that is captioned with "name" contains an ID string of the help entry, exam
ple:
     
   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 tha
t 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 "ti
tle":
     
   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". Insid
e 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 w
     ay. (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 chec
     king;
  *  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'