% comment
@autoexec{mod=ml9_2_html}
@header Markup Language 9

@para
'''Markup Language 9''' (or just ml9) is a
simple markup language
handling many different types of data in a single
unified framework.

Ml9  documents are designed to be written with a standard text editor
(like emacs) - they can be processed in many different ways.

I'd welcome any feedback ~http://erlang.sics.se:5000/wiki/showPage?node=ml9|on the ML 9 wiki page~ of the Erlang wiki.

@addindex
@index Mixing different things in  the same file
@para
Let's start
off with a simple example, suppose we want to mix
Makefiles, Erlang and Java in a ''single'' document, how can we do this?.
Easy! - just create an ml9 file with the following content.
@pre
 @java
 // My java program
 import java.applet.*;
 import java.awt.*;

 public class Foo extends Applet {
    private int bar = 0;
    private int baz = 0;
 ....

 @erlang
 -module(foo).
 -export([bar/2]).
 -import(lists, [member/2]).
 ...

 @make
 .SUFFIXES: .erl .beam .yrl

 .erl.beam:
	erlc -W $<
@para

  This  is pretty  easy  to  understand. Easy  section  starts with  a
'''@tag'''  in  column  1  and  ends with  the  character  immediately
''before'' the start of the next tag.

  The ''data'' associated with each tag starts ''immediately after the
end of the tag'' - note that this data is uninterpreted and unquoted -
it's just  a stream  of bytes  terminated with a  '''@''' in  column 1
following a carriage return.

The parse tree of:
@pre
 @someTag AAA
 ...
 ZZZ
 @nextTag
@para
is just
@pre {}
someTag{data = "AAA ... ZZZ"}
@para
@index Adding meta data to the data
@para Sometimes we want top add meta data to the data. Meta data is
data which describes the data and is not part of the data itself. Suppose
we want a yellow preformatted block. The tag is '''pre''' the ''meta data''
is '''color=yellow'''. This we can write like this:
@pre
 @pre {color=yellow}
 This is a yucky yellow
 block of pre-formatted data
 @nextTag
@para
Which might get rendered like this:
@pre {color=yellow}
This is a yucky yellow
block of pre-formatted data
@para
Yunck. 

@index ML9 chunks format
@para Each block of data in an ml9 document is called a ''chunk'', chunks
are written like this:
@pre
 @tagName {Key1=Val1, Key2=Val2 ..., KeyN=ValN}AAA
 ...
 ZZZ
 @nextTagName.
@para
The ''''{Key1=Val1, ...KeyN=ValN}'''' is ''meta data''. The string
'''AAA...ZZZZ''' is parsed just as if we had defined a tag named
''''data'''' whose value is the string ''''AAA...ZZZ'''. Thus
@pre
 @tag1 Hello
 joe
 @...
@para
and 
@pre
 @tag1 {data="Hello\njoe"}
 @...
@para
Have identical parse trees.
@index Autoxec
@para
Now the fun starts. If the first tag in a file is written like this:
@pre
 @autoexec{mod=Mod}
@para
Then the shell command:
@pre
&gt; ./ml9 File
@para
Will cause the ml9 file to parsed and the Erlang expression
''''Mod:exec(File, Parse)'''' will be evaluated. Here ''''Parse'''' is
the Erlang parse tree of the ml9 file, and ''''File'''' is the filename
supplied on the command line.

This is a very powerful mechanism, since it turns every ml9 file into
a potential program. Indeed the ml9 file containing this
documentation starts with the line:
@pre
 @autoexec{mod=ml2_2_html}
@para
Just you interest you can look at ~doc.ml9|doc.ml9~ to get an idea of
how simple the syntax of an ml9 file can be. Translation of ml9 into
html is really easy. The ''''ml9_2_html'''' handler is
really easy ~ml9_2_html.erl|take a look at the code~.

@index Comparison with XML
@para
XML data structures are basically like this
@pre
 &lt;tag name1="Val1" name2="Val2"&gt;
    ... data ...
 &lt;/tag&gt;
@para
The ''''name=Val1'''' etc can be thought of as being ''meta data''.
The ''body'' of the data structure ''''... data ...'''' is ''structured data''.

In XML the meta data is ''simple and flat'' ie keywords and values
are just simple strings with no structure. Data on the other hand is
''complex'' ie can have structure.

ML9 is ''completely the opposite'' - both keys are values are
arbitrarily complex Erlang terms. Data is flat - ie an uninterpreted
stream of bytes.

Since the data is just a stream of bytes, its interpretation depends entirely
upon the values of specific items in the meta-data. Thus
@pre
 @erlang
 -module(...)
 ...
 @...
@para Means ''the data following the tag is in Erlang syntax'' etc.
The easiest way to view a chunks document is to see what the
input to this document was. ~doc.ml9|this was the input to this document~.

@index Images and Links
@para
~http://www.sics.se/\~joe/images/joeold.jpg

Links can be written like ~doc.ml9~ or
~http://www.sics.se/\~joe|joe's home page~ or ~http://erlang.sics.se/~ 

@index Download
@para Here is the code ~ml9.tgz~.

@index About ML 9
@para ML9 was developed to be the input language for 
~http://www.sics.se/\~joe/erlguten.html|ErlGuten~.

There is no significance in the name. I wanted UML ''Universal Markup Language'' but this was taken - as was SML ''Simple Markup Language''.