Anubis / Anubis

$comment(                        The MAML3 tutorial       (written in MAML3)               )


$define(title)(1)($par$par$center($big($big($bold($1))))$par$par)
$define(MAML)(0)($bold($red(MAML)))
$define(em)(1)($italic($1))
$define(argu)(1)($rgb(0,80,0)(<$1>))
$define(mark0)(1)($label($1)$subsection($red($tt($$$1))))
$define(mark1)(2)($label($1)$subsection($red($tt($$$1$lpar$argu($2)$rpar))))
$define(mark2)(3)($label($1)$subsection($red($tt($$$1$lpar$argu($2)$rpar$lpar$argu($3)$rpar))))
$define(mark3)(4)($label($1)$subsection($red($tt($$$1$lpar$argu($2)$rpar$lpar$argu($3)$rpar$lpar$argu($4)$rpar))))
$define(LaTeX)(0)($latex(\LaTeX))
$define(tcode)(1)($code(255,255,255)($1))

$ifpdf($latex(
\parskip2mm
\textheight24cm
\textwidth16cm
\topmargin-2cm
))

$title(The $MAML  (version 3) Tutorial)

$MAML   (the $em(Minimalist Anubis Markup Language)) is a very easy to use tool for writing texts. It provides
commands for using different $bold(font) $italic(styles), $big(font $big(sizes)), $red(colors), for making lists, tables, 
sectionning units, inserting images
and 
hypertext links, and most sorts of things which are useful for writting texts which are agreable to read. The $MAML   
compiler produces HTML and PDF files from a $MAML  source text. 
This $ifpdf(PDF )documentation itself was written in $MAML. 


$ifpdf({\parskip0mm\tableofcontents})

$define(tocsec)(2)($big($ref($1)($2))$par)
$define(tocsubsec)(2)($box(20)()$ref($1)($2)$par)
$ifhtml($par$par$center($bold($big(Contents)))$input(maml3_tutorial.maml.mamltoc)$par)

$section(The $MAML  syntax)
A $MAML  text is interpreted as pure text until the character $tt($dollar)  is encountered.$note(Except that the 
character $tt($~) is interpreted as a non breakable space, as in $LaTeX. It is of course translated to $tt(&nbsp;) 
in HTML. If you want to insert an actual $em(tilde) character in your text, just write $tt($dollar$~).) This character indicates
that what follows is a $em(mark). The name of the mark immediatly follows the character $tt($dollar). The arguments
of the mark follow this name, and each one must be delimited by a pair of parentheses. For example, if you
want to render some text in blue, you can write:
$center($tcode($$blue(this text is rendered in blue)
))
which will produce this: 
$center($blue(this text is rendered in blue))
$par
Each mark accepts a fixed number of arguments. Since each argument must be delimited by a pair of parentheses 
(which are not part of the argument itself), the
parentheses which are part of the argument, if any, must be balanced, otherwise the $MAML  parser will not find the closing
parenthese. Nevertheless, you can still include unbalanced parentheses in an argument provided that you write them 
$tt($$lpar) (left parenthese) and $tt($$rpar) (right parenthese). 
$par
$par
The mark $tt($$blue) takes one argument as you saw above. As another example, $tt($$tlink) takes two
arguments, and the text:
$center($tcode($$tlink(Visit 
   $$big($$blue(G)$$red(o)$$yellow(o)$$blue(g)$$green(l)$$red(e)))
      (http://www.google.com)
))
will produce this$ifhtml( (that you can click upon)): 
$par
$center($tlink(Visit $big($blue(G)$red(o)$yellow(o)$blue(g)$green(l)$red(e)))(http://www.google.com))
$par
$em(Remark:) The name of a mark is right delimited by the first character which is not an acceptable character
for such a name. If this character is a space, it is discarded. On the contrary, if a second
space follows, it is not discarded. Hence for example, 
$tt($$lpar x) will produce $lpar x, whereas $tt($$lpar$box(16)()x) (with at least two spaces between 
$tt($$lpar) and $tt(x)) will produce $lpar  x.  
$par
$par
The mark $tt($$define) allows to define new marks. The details are given $ref(define)(here). 





$section(Creating your own style)
The primitive $MAML  marks are rather basic, and should be preferably used in the value argument of $tt($$define)
marks. In other words, it's better to first define (using the $tt($$define) mark) the concepts you will use in your 
text, rather than writing them from scratch at each occurrence. In some sens, defining these concepts is the same as
creating your own style. 
$par$par
For example, it can be the case that some concept of your discourse has to be emphasized in a particular way, say printed
in red. You should not use $tt($$red(...)) in the text. You should better first give a name (say $tt(thething)) to
your concept, and define it near the beginning of the text:
$par$par
$tt($$define(thething)(1)($$red($$1)))
$par$par
and write $tt($$thething(...)) in the text instead of $tt($$red(...)).
$par
$par
This will structure your text in a useful semantic way, instead of a non significant way, making it easier
to later update. 
It also has the advantage that you can later easily change the layout of the text by modifying
only the values in these $tt($$define). 
$par
$par
The $tt($$input) mark let you ``input'' a $MAML  source at any point of nother $MAML  source. Hence, you should
define your style in a file (say $tt(mystyle.maml)) and put an $tt($$input(mystyle.maml)) at the beginning of your
source file. 



$label(colorize)
$section(Automatic colorization)
$MAML  has a simple (rather rudimentary) system for automatic colorization of computer texts. Within a $MAML  source text, 
you can define one or several colorizers, and later apply them at will.$par$par 

However, you must be warned that
colorizing will not work on text containing $MAML  marks (except macros producing text containing no
$MAML  mark). This is because the colorizer can only act on character strings, not on $MAML  trees. If
a $MAML  mark is present in the text the coloriser will reformat it in the form of a source text before
colorizing, so that you will get some $MAML  source into the result.$par$par

In order to create a colorizer, you must:
$list(
  $item define one or several $italic(color rules),
  $item when done, create the $italic(colorizer). 
)
A color rule has the form:
$center($tt($$colorrule(<colorizer name>)(<regular expression>)(r,g,b)))
where $tt(r), $tt(g) and $tt(b) are integers between 0 and 255.$par$par

The name of the colorizer must be an ordinary symbol. Regular expressions must follow the syntax defined in 
$bold($tt(library/lexical_analysis/fast_lexer_5.anubis)).$par$par

Once the color rules are setup, you can ceate the colorizer as follows:$par
$center($tt($$colorizer(<colorizer name>)))
Then you can colorize a text as follows:$par
$center($tt($$colorize(<colorizer name>)(<text>)))

As an example, consider the following definition of a colorizer:
$code(255,255,255)(
$$colorrule(mycolorizer)([0-9]+)(120,0,0)
$$colorrule(mycolorizer)([a-z]+)(0,120,0)
$$colorrule(mycolorizer)([A-Z][a-z]+)(0,0,120)
$$colorizer(mycolorizer)
)
$colorrule(mycolorizer)([0-9]+)(120,0,0)
$colorrule(mycolorizer)([a-z]+)(0,120,0)
$colorrule(mycolorizer)([A-Z][a-z]+)(0,0,120)
$colorizer(mycolorizer)
If you write this:$par
$center($tt($$colorize(mycolorizer)(There are more than 4543225 stars in the sky.)))
You get this:$par
$center($colorize(mycolorizer)(There are more than 4543225 stars in the sky.))

$section(The catalog of $MAML  marks)
Below are the $MAML  marks in alphabetic order: 

  $mark1(big)(text) Prints its argument $argu(text) bigger. This mark can be nested. 

  
  $mark1(bold)(text) Prints its argument $argu(text) in $bold(bold).
  
  $mark2(box)(width)(text) This mark puts $argu(text) into an invisible box of width $argu(width). The text if left aligned
  within the box. This mark can be used for simulating tabulators. For example, 
  $tcode(
  $$box(50)(Smith) $$box(50)(John) $$box(30)(24) Baltimore $$par
  $$box(50)(Ford)  $$box(50)(Max)  $$box(30)(32) New York  $$par
  )
  produces:
  $par$par
  $box(50)(Smith) $box(50)(John) $box(30)(24) Baltimore $par
  $box(50)(Ford)  $box(50)(Max)  $box(30)(32) New York  $par
  $par
  Of course, if you have to produce such tables, you should better first define a new mark whose role is to display
  a single line of the table. This mark should include the $tt($$par) at the end of line. 
  
  $mark1(center)(text) This mark horizontally centers the $argu(text) in the page.
  
  $mark2(code)(background color)(text) This marks is for writing computer code. 
  The $argu(background-color) argument must have the form $tt(r,g,b), where $tt(r), $tt(g) and $tt(b) are intensities of
  red green and blue and must be integers between 0 and 255. 
  The $argu(text) argument is formated using a fixed width
  (typewriter) font, spaces and newlines are taken into account, so that the result has essentially the same layout as the
  original.  Nevertheless, $MAML  marks are allowed within $argu(text), but some of them, such as $tt($$list), 
  can produce incoherent result. For example, 
  $par
  $tcode($$code(220,220,220)(
$$red(define) $$blue(Int)
  length
  (
    List($$dollar T) l
  ) =
  $$red(if) l $$red(is) 
  {
    [ ]      $$red(then) 0,  $$green(// the list is empty)
    [h . t]  $$red(then) 1+length(t)    
  }.
  ))
  $par
  produces:
  $par
  $code(220,220,220)(
$red(define) $blue(Int)
  length
  (
    List($$T) l
  ) =
  $red(if) l $red(is) 
  {
    [ ]      $red(then) 0,  $green(// the list is empty)
    [h . t]  $red(then) 1+length(t)    
  }.
  )
  (But actually, you should better define a $ref(colorize)(colorizer) for colorizing the code.)
  $par$par
  See also $ref(tt)($tt($$tt(...))) and $ref(verbatim)($tt($$verbatim(...)))
  
  
  $mark1(comment)(text) This mark allows you to put a comment, which will not be rendered, in your $MAML  source text. 
  $par
  $em(Warning:) Parentheses must be balanced within $argu(text), otherwise the $MAML  parser will not find the end of the
  comment. 
  
  $mark3(define)(name)(numer of arguments)(value)
    This mark let you define new marks (i.e. macros). It takes three arguments. The first argument $argu(name) is the name of the new mark. It should
    not be already in use, must be made only of letters (A to Z and a to z) and numbers (0 to 9), and
    must contain at least one letter. The second argument $argu(number of arguments) is the number of arguments your new mark will accept. It must
    be a positive or zero integer. The last argument $argu(value) is the value of the mark. This is a $MAML  text, and it can
    contain marks of the form $tt($$1), $tt($$2), $tt($$3), ... (called $MAML  $em(variables)) which represent the arguments
    of the mark, and which will be later replaced by the actual arguments when the mark is used in the text. 

  $mark0(dollar) This mark inserts a character $$  in the text. Notice that $tt($$tt($$dollar)) 
  produces $tt($dollar), wheras $tt($$dollar) produces $dollar. You can also write $tt($) instead of $tt($$dollar), 
  provided that the character $tt($) is not followed by an integer, nor a latin letter nor a tilde character. 
    
  $mark0(end) This mark indicates that the MAML compiler should stop reading. In case this mark appears within a
  source text read through an $tt($$input) mark, the ``input'' file is closed and parsing resumes in the
  calling source. 
  
  $mark1(ifhtml)(text) The argument $argu(text) will be present in the HTML output, but not in the $LaTeX  nor in the PDF
  output. 
  
  $mark1(ifpdf)(text) The argument $argu(text) will be present in the $LaTeX  and in the PDF
  output, but not in the HTML output.
    
  $mark2(image)(width)(file path)
    This mark allows you to insert an image in the text. The argument $argu(width) is the width the image will have
    when displayed (in pixels in the case of HTML, and points in the case of $LaTeX), and $argu(file path) is the path of the file
    containing the image. For example, 
    $tcode($$center($$image($$ifpdf(100)$$ifhtml(200))(cows.jpg))) 
    will produce this:
    $center($image($ifpdf(100)$ifhtml(200))(cows.jpg))
    At the same time, you remark that the width of the image can be computed by $MAML  marks. 
    $par
    $em(Warning:) The $argu(file path) of the image is relative to the root directory on the server in the case of 
    an HTML output. In the case of a $LaTeX/PDF output, it is relative to the directory within which
    the MAML parser is executed. 
    
    
  $mark1(input)(file name)
  This mark let you insert the content of another $MAML  file. This other file could for example contain your own $MAML
  macros or be the file with extension $tt(.mamltoc) generated by the $MAML  compiler (see $ref(section)($tt($$section))). 
   For security reasons, this mark has restricted use in the web version of MAML. It can read files from one directory
   only. 
    
  $mark1(italic)(text) Prints its argument $argu(text) in $italic(italic).
  
  $mark0(item) Marks the begining of an $em(item) within a $ref(list)($tt($$list))
  
  $mark1(label)(tag) This mark defines a $em(label) in the text, in other words, a position where to jump. 
  This is to be used in conjunction with $ref(ref)($tt($$ref)). 
  
  $mark1(latex)(formula) This mark allows to include math formulas to be formated by $LaTeX. 
     For example, 
     $center($tcode($$latex($dollar$$\int_0^\infty\frac{dx}{1+x^2}$dollar$dollar)))
     will be rendered as: 
     $latex($$\int_0^\infty\frac{dx}{1+x^2}$$) 
     This mark should not be used for big pieces of $LaTeX   
     text. It is mainly intended for math formulas, especially for HTML output where the formula is rendered
     as a PNG image with transparent background. 
     $par$par
     You can use $tt($$latex) in the text. The result will be correctly aligned with the text. For example,$par
     $center($tcode(the polynomial $$latex($$X^2+X+1$dollar) is of degree 2))
     is rendered as~:
     $center(the polynomial $latex($X^2+X+1$) is of degree 2)
     
  $mark1(list)(items) This mark allows to create a list. The argument $argu(items) must be a sequence of $em(items), 
  i.e. texts which are all prefixed by the mark $ref(item)($tt($$item)).
     
  $mark0(lpar) This mark inserts a left (opening) parenthese into the text. You must use $tt($$lpar) and/or
  $tt($$rpar) if you want to introduce unbalanced parentheses within an argument of a mark.
     
  $mark2(mailto)(address)(text) This marks, which appears as $argu(text), 
  creates a link which is supposed, in the HTML case, to open your mail agent in order to let you
  send an email to the indicated $argu(address). In the PDF case, the $argu(address) is just indicated between parentheses
  beside $argu(text). 
  For example,
  $center($tt($$blue($$mailto(XZ32@planet.mars)(the martian)))) produces: 
  $blue($mailto(XZ32@planet.mars)(the martian))

  $mark1(note)(text) This mark produces a footnote containing $argu(text). 
  In the case of $LaTeX/PDF  this is a usual
  footnote.$ifpdf($note(Like this one.)) In the case of HTML, this is a popup which appears at the bottom of the browser's window when the mouse
  passes over this indication : $ifhtml($note(Here is the note !))$ifpdf(($sup(note))).$ifhtml( Try it !)
  
  $mark2(output)(file path)(text) This mark does not produce anything in the resulting HTML or PDF files, but outputs
  $argu(text) (without any modification) into the file $argu(file path). For security reasons, this mark is not available 
  in the web version of MAML.
  
  $mark0(par) This marks generates a line break. You can use several $tt($$par) in order to make some
  vertical space in your text. 
  $par$par
  $em(Warning:) The MAML parser doesn't take newline characters into account (they are just read as spaces). Hence,
  using $tt($$par) is often necessary. 
  
  $mark2(ref)(tag)(text) 
  This mark creates an internal hyperlink. When clicked upon, this moves the text
  to the position of the $ref(label)($tt($$label)) (this is a $tt($$ref) !) with the same tag name. 
  
  $mark2(rgb)(color)(text) This mark sets the color of characters in $argu(text) to $argu(color), where
  $argu(color) has the form of three integers separated by commas, representing the intensities of red, green and blue. 
  These numbers must be between 0 and 255. For example, 
  $center($tcode($$$rgb(255,0,0)(the text)))
  produces:
  $center($rgb(255,0,0)(the text))
  $par
  The marks $tt($$red(...)), $tt($$green(...)), $tt($$blue(...)), $tt($$yellow(...)) and  
  $tt($$grey(...)) are predefined. 
  
  $mark0(rpar) This mark inserts a right (closing) parenthese into the text. You must use $tt($$lpar) and/or
  $tt($$rpar) if you want to introduce unbalanced parentheses within an argument of a mark. 
       
  $mark1(section)(title) This mark defines a $em(section) within the text. It is translated into 
  $tt(<h3>$argu(title)</h3>) in HTML and into $tt(\section{$argu(title)}) in $LaTeX. Sections are automatically numbered.
  $par$par
  When it encouters either $tt($$section), $tt($$subsection) or $tt($$subsubsection), the $MAML
  compiler adds a line to the file with the same name as the source file but with $tt(.mamltoc) appended. This file contains
  marks of the form $tt($$tocsec(label)(text)) (and similarly $tt($$tocsubsec) and 
  $tt($$tocsubsubsec)), and it is up to you to define the meaning of these marks. Combined with $tt($$input) this lets
  you make a table of contents for the HTML output. Actually, this is how the table of contents of the present tutorial
  was made. 
  
  $mark1(sub)(text) This mark lowers $argu(text) and renders it in a smaller size. For example, $tt(x$$sub(1))
  produces x$sub(1). 
  
  $mark1(subsection)(title) This mark defines a $em(subsection) within the text. It is translated into 
  $tt(<h4>$argu(title)</h4>) in HTML and into $tt(\subsection{$argu(title)}) in $LaTeX. Subsections are automatically
  numbered. 

  $mark1(subsubsection)(title) This mark defines a $em(subsubsection) within the text. It is translated into 
  $tt(<h5>$argu(title)</h5>) in HTML and into $tt(\subsubsection{$argu(title)}) in $LaTeX. Subsubsections are automatically
  numbered. 

  $mark1(sup)(text) This mark raises $argu(text) and renders it in a smaller size. For example, $tt(x$$sup(1))
  produces x$sup(1). 
  
  $mark2(tbgc)(color)(text) This mark ($em(text background color)) shows $argu(text) over a background of color
  $argu(color). For example,
  $center($tcode($$tbgc(255,200,200)(Some text.)))
  produces: $tbgc(255,200,200)(Some text.) $em(Warning:) This will force $argu(text) to be on a single line, so that
  it is valuable only for very short texts. See also $ref(code)($tt($$code(...))). 
  
  $mark2(tlink)(text)(url) This mark creates an hypertext link targeting the $argu(url), and shown as the clickable
  $argu(text) (which can also be an image). 

  $mark1(tt)(text) This mark renders $argu(text) in fixed width (typewriter) font. It is similar to 
  $ref(code)($tt($$code(...))), with the difference that $argu(text) is put inline instead of as a separate block. 
  For example, $tt($$tt(This) is $$code(255,255,255)(an) example.)
  produces: $tt(This) is $tcode(an) example.
  $par
  See also $ref(code)($tt($$code(...))) and $ref(verbatim)($tt($$verbatim(...))).
  
  $mark1(verbatim)(text) This marks reproduces its content without any change with two exceptions. 
  Indeed, $MAML  marks within 
  $argu(text) are not interpreted, except the two marks $tt($$lpar) and $tt($$rpar), which allows you
  to produce unbalanced parentheses in $argu(text) despite the fact that actual parentheses $em(must) be 
  balanced in $argu(text). Example: 
  $par
  $tcode($$verbatim(
  In this ($$blue(text))(), ((parentheses) are) $$rpar$$rpar$$lpar balanced.
  ))
  $par
  produces:
  $verbatim(
  In this ($blue(text))(), ((parentheses) are) $rpar$rpar$lpar balanced.
  )
  Nevertheless, colors are applied if $tt($$verbatim(...)) is within a $tt($$rgb(...)(...)). Indeed, 
  $tcode($$rgb(255,0,0)($$verbatim(Red verbatim text)))
  produces:
  $rgb(255,0,0)($verbatim(Red verbatim text))
  $par
  See also $ref(code)($tt($$code(...))) and $ref(tt)($tt($$tt(...))).
 

$ifhtml($par$par$par$par$par$par$par$par$par$par$par$par$par$par$par$par$par$par$par$par$par$par$par)