General rules:
=============
Text between ## and ## is considered as a block of code.
A block of code is normally some OCaml code. It can be any
kind of toplevel expressions such as definitions or application
of printing functions:

  This is ocaml version ## print Sys.ocaml_version ##

If it starts with = the OCaml code is interpreted as an expression
of type string that will printed like the rest of the text:

  This is ocaml version ##= Sys.ocaml_version ##


The document blocks are printed by default on stdout using the "print"
function. 
For ## to be printed, ### should be used.

White space introduced by OCaml can be controlled
by ##. and .## symbols:
    ##. causes any white space to the left of the symbol
        to be omitted from the output. Similarly
    .## causes any white space followed by one newline
        to be omitted from the output.

Directives:
==========
Blocks of code that start with the @ character (possibly preceded 
by spaces) are directives for Camlmix.
The following directives are available:
  include "somefile.mlx"; (* inserts a camlmix file *)
  skip;                   (* ignores the next block of text *)

e.g.: Hello ## @include "world.mlx"; skip .## ## let x = 123 ##!


Conversion into a "render" function for dynamic rendering:
===========================================================
The -fun option, used in combination with -c and often -co produces 
an OCaml source file which provides a function with the following signature:

  val render : ?print:(string -> unit) -> ANYTYPE -> unit

where ANYTYPE is the type the "param" object which is available in
the template. "param" can be used to pass runtime arguments, such
as CGI parameters if you are serving dynamic web pages.
The "print" function is used to set the initial value of Camlmix.printer
(see below) and should be used if you want to be able to put the output
into some other container than stdout. It's default value is:

  fun s -> print_string s; flush stdout


Advanced usage:
==============
The OCaml program that is generated from the Camlmix files first defines
a module called Camlmix. This module contains several variables that are 
updated automatically and may be used explicitely by the user.

module Camlmix :
  sig
    val source : string ref
    val line   : int ref
    val char   : int ref        
        (* source, line and char refer to the location of the first 
           character of the current block in its source file
           (source file, line number starting from 1, position in the line
           starting from 1). They are updated automatically at the beginning
           of each (code or text) block. *)

    val printer : (string -> unit) ref 
        (* the function that prints text blocks. It is initialized with
           the "print" function *)

    val print_with : (string -> unit) -> unit
        (* print_with f prints the next block of text using f instead
           of the current printer. 
           Its behavior is undefined if it is called several 
           times in the same OCaml block. *)

    val print_if : bool -> unit
        (* print_if cond prints the next block of text only 
           if cond is true. It uses print_with. *)
  end


Usage: camlmix [options] file1 file2 ... fileN

A temporary file "fileN.ml" is created and then executed
with ocaml.

Command line options:
  -c  only generate the .ml file
  -co <filename>  specify a name for the .ml file or "-" for stdout
  -fun  make it the body of a function named "render", using a single argument named "param"
  -e <ocaml>  specify ocaml executable
  -o <file>  specify an output file
  -clean  remove the temporary .ml file after execution
  -insert <ocaml code>  insert this code first
  -remix  try a conversion to the camlremix syntax
  -version   prints the version of Camlmix and exits
  -help  Display this list of options
  --help  Display this list of options