Anubis / Anubis

                                          MAML4

                           The public interface (and documentation). 


transmit tools/basis.anubis
transmit tools/ANSI-colors.anubis
transmit_tools/file_and_dir.anubis
transmit tools/2-4tree.anubis
transmit lexical_analysis/fast_lexer_5.anubis


   
   
   $begin   
   $input(../anubis_doc.maml)
   $define(article)(0)()
   $input(basis.maml)
   $define(mark)(1)($rgb(100,0,0)($$$1))
   
   $section(themaml)(MAML (The Minimalist Anubis Markup Language))
   

   MAML was first implemented in 2005 and was mainly to be used for writing texts within a 
   web page. It was called 'minimalist' since it was to be used by web site users, hence had
   to remain very simple.$p
   
   After some time, a need for a more generic and flexible tool appeared. 
   This led to some modifications in the original MAML (this was version 2). However, we wanted 
   to make everything cleaner, more efficient concerning LaTeX code generation, and also easier 
   to use for the programer. This was version 3, and finally, this version 4 is mainly equivalent
   to version 3 except that it is about 8 times faster, due to the use of the tools available in 
   $fname(lexical_analysis/fast_lexer_5.anubis) and $fname(tools/2-4tree.anubis).$p 
   
   MAML texts can be translated into HTML and PDF (via LaTeX). Notice that producing HTML output
   also uses LaTeX if the $mark(latex) mark is used in the MAML source text.$p
   
   This program requires that the following are installed if LaTeX is to be used:
   $list(
      $item LaTeX2e (together with some LaTeX packages; see below)
      $item dvipng  (used only for producing images for the HTML output in presence of the $mark(latex) mark)
      )
   LaTeX2e and dvipng are available under Linux and Windows (you can use MiKTeX under Windows). 
   The LaTeX packages used by MAML are:
   $list(
      $item babel
      $item inputenc
      $item amsfonts
      $item amsmath
      $item amssymb
      $item latexsym
      $item xy
      $item color
      $item graphicx
   )
   Normally, they should be all present in a standard distribution.
   
   $subsection(howto)(How to write texts in MAML) 
   
   A $em(user's guide) for writing texts in MAML can be found in $fname(maml4_tutorial.maml) in $fname(library/doc_tools). 
   This is a MAML file that you can process as follows (provided that $fname(library/doc_tools/maml4.anubis) is first 
   compiled):
   
   $ecode(anbexec maml maml4_tutorial.maml -pdf)
   
   This requires that LaTeX2e and dvipng are installed because, of course, the tutorial examplifies the 
   $mark(latex) mark. This produces $fname(maml4_tutorial.maml.html) and $fname(maml4_tutorial.maml.pdf). Actually, 
   these two files are already 
   part of the distribution. The HTML file refers to images which are also stored in $fname(library/doc_tools).$p
   
   Actually, $fname(maml4_tutorial) is mainly intended for insertion into the online documentation of a web site, if this web
   site wants to offer some text formating facilities to its users (for example, if it is a forum). 
   
   $subsection(errors)(Errors) 

   Of course, syntax errors can be found during the parsing of the MAML text, and also later during
   the output. Positions within source texts are formalized as:
   $acode(
public type MAML_Pos:   // position in a MAML text
   position    
     (String    file_path,   // absolute path of the file where the error was found
      String    file_name,   // name of this file
      Int       line,        // line number at which the error was found
      Int       column,      // column number
      Int       offset).     // offset in file

public type LexerAux:
   laux    (String                         path, 
            String                         fname,
            Var(Bool)                      noprimitive_v, 
            (MAML_Pos,String) -> String    noprimitive_msg). 
      )
   
   $acode(
public type MAML_Error:
   lexical                         (MAML_Pos                pos,                  
                                    LexicalError(One)       lexical_error),
   lexical                         (MAML_Pos                pos,                  
                                    LexicalError(LexerAux)  lexical_error),
   missing_end                     (String                  path,
                                    String                  fname),
   end_in_operand                  (MAML_Pos                pos), 
   end_in_list                     (MAML_Pos                pos), 
   unknown_mark                    (MAML_Pos                pos, 
                                    String                  mark_name), 
   premature_end_of_file           (String                  path,
                                    String                  file),
   missing_operand                 (MAML_Pos                pos,
                                    String                  mark_name), 
   too_many_operands               (MAML_Pos                pos,
                                    String                  mark_name), 
   file_not_found                  (MAML_Pos                pos,
                                    String                  path), 
   cannot_read_file                (MAML_Pos                pos,
                                    String                  path),
   cannot_open_file                (String                  path),
   cannot_create_file              (String                  path), 
   cannot_write_file               (String                  path), 
   cannot_execute_latex, 
   cannot_execute_dvipng,
   png_file_corrupted              (String                  path),
   dvipng_error                    (Int                     code),
   regexpr                         (MAML_Pos                pos, 
                                    RegExprError            e),
   latex_error                     (MAML_Pos                pos, 
                                    String                  logfname), 
   latex_error                     (Int                     code,
                                    String                  logfname),
   integer_expected                (MAML_Pos                pos),
   must_be_a_color                 (MAML_Pos                pos,
                                    String                  s),
   boolean_expected                (MAML_Pos                pos, 
                                    String                  s), 
   must_be_an_int                  (MAML_Pos                pos,
                                    String                  s),
   must_be_a_nzint                 (MAML_Pos                pos,
                                    String                  s),
   must_be_a_positive_int          (MAML_Pos                pos,
                                    String                  s),
   must_be_a_symbol                (MAML_Pos                pos,
                                    String                  s),
   string_expected                 (MAML_Pos                pos,
                                    String                  s),
   invalid_initial_counter_value   (MAML_Pos                pos, 
                                    String                  value), 
   unknown_counter                 (MAML_Pos                pos, 
                                    String                  counter_name),
   unknown_macro_name              (MAML_Pos                pos, 
                                    String                  s), 
   invalid_number_to_add           (MAML_Pos                pos, 
                                    String                  value),
   unknown_colorizer               (String                  name),
   colorizer_already_exists        (MAML_Pos                pos, 
                                    String                  name),
   not_a_colorizercall_mode        (MAML_Pos                pos, 
                                    String                  s),
   unknown_accumulator             (MAML_Pos                pos, 
                                    String                  name),
   invalid_apply_name              (MAML_Pos                pos, 
                                    String                  name), 
   bad_apply_arity                 (MAML_Pos                pos, 
                                    String                  name),
   not_a_list                      (MAML_Pos                pos,
                                    String                  s),
   misplaced_right_bracket         (MAML_Pos                pos), 
   misplaced_right_par             (MAML_Pos                pos), 
   adm_not_found                   (MAML_Pos                pos,
                                    String                  name),
   cannot_read_adm                 (MAML_Pos                pos,
                                    String                  name),
   timeout_adm                     (MAML_Pos                pos,
                                    String                  name),
   adm_damaged                     (MAML_Pos                pos,
                                    String                  name),
   adm_bad_version                 (MAML_Pos                pos,
                                    String                  name),
   adm_wrong_type                  (MAML_Pos                pos,
                                    String                  name),
   incompatible_operands           (MAML_Pos                pos,
                                    String                  name),
   invalid_macro_vars              (MAML_Pos                pos,
                                    List((String,Int))      namevars). 
   )
   
   The function below formats a MAML error into an English text. 
    
   $acode(
public define String    to_English  (MAML_Error   e). 
   )


   $subsection(options)(Parsing options) 

   Options can be transmitted to the MAML parser. 
   
   $acode(
public type MAML_Option:
   verbose, 
   pdf,       // produce a PDF output (HTML only by default)
   justify, 
   width(Int). 
   )
   

   $subsection(html)(Generating an HTML output) 
   
   A MAML source text is read through the use of a $em(lexing stream) as defined in: 
   $acode( 
read lexical_analysis/fast_lexer_5.anubis
   )
   This allows to read MAML texts from files, network connections and character strings (and more; see 
   $fname(fast_lexer_5.anubis)). You can of course also use the $ref(cmdlinetool)(command line tool 
   $att(maml)).$p
   
   In order to produce an HTML or a PDF output, you need to provide some parameters. These parameters
   are gathered into a datum of type $att(MAML_HTML_Options) for HTML output and $att(MAML_PDF_Options) for
   PDF output. 
   $acode(
public type MAML_HTML_Options:...     (explained below)
   )
   There is a default value: 
   $acode(
public define MAML_HTML_Options default. 
   )
   
   We use the type $att(Text) for storing texts. This is a variant of $att(Printable_tree). Such data can 
   be printed.
   $acode(
public type Text:...
public define One      print(WStream   s, Text    text). 
   )
   In order to produce an HTML output, use the following:
   $acode(
public define Result(MAML_Error,Text)
   to_HTML
   (
     List(MAML_Option)           maml_options,
     LexingStream                maml_source,
     MAML_HTML_Options           options             // you can put 'default' here
   ). 
   )
   
   $subsection(pdf)(Generating LaTeX and PDF output) 
   
   Again there are options and a default value: 
   $acode(
public type MAML_PDF_Options:...    
public define MAML_PDF_Options default. 
   )
   
   $acode(
public define Result(MAML_Error,Text)
   to_PDF
   (
     List(MAML_Option)          maml_options,
     LexingStream               maml_source,
     Maybe((String,String))     pdf_output_path_and_name,    
                                // no output file if 'failure'
     MAML_PDF_Options           options                      
                                // you can put 'default' here
   ). 
   )
   
   Putting $att(failure) for $att(pdf_output_path_and_name) is used if one wants only the LaTeX text. 
   
   
   $subsection(options)(Managing options)
   
   If you are not satisfied by the default options, you can create your own by defining data of 
   these types: 
   $acode(
public type MAML_HTML_Options:
   options
   (
     // directories:
     String      png_path_server,          
     // the directory where dvipng generated images will be stored
     //   for example:   site_directory/"public/png"
     String      png_path_client,          
     // the same one but seen from the client viewpoint (i.e. included 
     //   in the HTML text) in this case: "png"   since site_directory/"public" 
     //   is the root from the client viewpoint
     String      tmp_path,                 
     // the directory for temporary files on the server (.tex, .dvi, .aux, ...)
     
     // Sizes:
     Int         font_size,                
     // font size for main text (in pixels)
     Int         note_font_size,           
     // font size for text in footnotes
     Int         text_width,          
     // width of text in pixels
     Bool        right_justify
   ).
   )

   $acode(
public type MAML_PDF_Options:  
   options
   (
     // directories:
     String      tmp_path,             
     // the directory for temporary files (.tex, .dvi, .aux, .log, ...)
     
     // LaTeX specific:
     String      babel_language,       
     // the language for the Babel package ("english", "french", ...)
     String      add_to_preambule,     
     // what you want to add just before \begin{document}
     Int         page_width,           
     // in millimeters
     Int         page_height           
     // in millimeters
   ).
   )
   
   You can of course use the value $att("") for $att(add_to_preambule). If you want to include a table of contents, 
   use $att($mark(ifpdf)(\tableofcontents)) in your MAML source, etc...  

   
   $subsection(first)(Parsing MAML first)

   Here is how to avoid parsing twice the MAML source text if you want to produce both outputs.  
   You can first parse the MAML source, which yields a datum of type:
   $acode(   
public type MAML3:...
 public type alias MAML = MAML3. 

public define Result(MAML_Error,MAML3)
   parse_MAML
   (
     List(MAML_Option)    maml_options,
     LexingStream         s
   ). 
   )
   and from this datum produce the HTML, LaTeX and PDF outputs:
   $acode(
public define Result(MAML_Error,Text)
   to_HTML
   (
     MAML3                maml_text,
     MAML_HTML_Options    options                      // you can put 'default' here
   ). 

public define Result(MAML_Error,Text)
   to_PDF
   (
     MAML3                maml_text,
     Maybe(String)        pdf_output_path_and_name,    // no output file if 'failure'
     MAML_PDF_Options     options                      // you can put 'default' here
   ). 
   )
   
   $define(nl)(0)( 
)   
   
   $label(cmdlinetool)
   $subsection(cmdline)(Command line tool) 
   $acode($id($nl)anbexec maml $nt(file) $nt(options)    
   )
   The command line tool $att(maml) reads the file given as its argument, but only between
   the marks $mark(begin) and $mark(end). These pairs of marks can be present several times
   in the file and the texts they delimit are all parsed.$p
   
   The option $att(-pdf) tells maml to produce a PDF output (by default, it produces a HTML 
   output only).$p
   
   An option $att(-verbose) is also available.  

   
   $end