% these are the old sources from which the man page was generated with 
% debian/camlmix.1: debian/camlmix.mkd
% 	pandoc -s -w man $^ -o $@
%
% CAMLMIX(1) camlmix User Manual
% Sylvain Le Gall
% December 2, 2010

# NAME

camlmix - preprocessor which converts text with embedded OCaml.

# SYNOPSIS

camlmix [options] file1 file2 ... fileN

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

# DESCRIPTION

## 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 explicitly 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


# 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|\--help
:   Display this list of options

