File created the 3rd of March 2003.

The Caml masquotte Htmlc : a general purpose batch editor and HTML files generator

Version 1.70

Compilation

This file can be compiled using:

htmlc -I ../../doc_src/Includes/ -env env0 -c example-eng.html

Defining the compiling environment

Environment files are lists of bindings. A binding defines a name (``an identifier'') to a constant value. A constant value could be an integer, a floating point number, a character, a character string, a boolean (either true or false), or a previously bound identifier.

Lexical conventions for constants and identifiers follow those of the Caml language.

Bindings may have one of the two following syntactic flavors:

Caml style syntax
A binding is a simple Caml binding of the form
let ident = value;;
Caml comments are properly skipped.
Free style syntax
A binding has one of the two following forms:
ident = value
or
ident value
Comments start with a sharp sign # and spread to the end of line.
Bindings should end with at least one newline.
Mixing the two flavors of bindings into the same environment file is strongly discouraged.

Examples of compiling environment files

The environment file env0 is free style:

#
# The environment file to expand the examples.
#
# We use free style syntax here.
#
# This is a list of binding of name to values,
# a binding is just a single line (except for string bindings).
#
# Use:
#
# let name = value;;
#
# name = value
#
# or
#
# name = "value"
#
# or even
#
# name "value"
#
# -- A name is an ident (Caml idents are warranted to be properly understood).
# -- A value can be either a number, a boolean, a char, or a string.
#
# Values are read as tokens according to the Caml lexical conventions.
# The value bound to a name is always converted to a Caml string.
#

environment_file_name = "env0"

HTMLCDOCDIR = "../../doc"

X = "hello"

Y = 1

a_long_definition_can_spread_on_more_than_one_line = "\
ca marche
même sur
plusieurs
lignes!"

# Adresse du campus de Rocquencourt
inria_addres = "\
INRIA<BR>\n\
Domaine de Voluceau-Rocquencourt<BR>\n\
78153 Le Chesnay CEDEX<BR>\n\
France"

#########################
# Ce qui concerne l'Hôtel
#########################

hotel = "«La Datcha»"

adresse_hotel = "\
$(hotel)\n\
128 rue de la souris qui se repose\n\
78000 Versailles\n\
France"
#########################

The environment file env1.ml is Caml style:

(*
    The environment file to expand the examples.

    It is in ``Caml'' style and uses simple Caml-like bindings of the form:

    let name = value;;
*)

let environment_file_name = "env1.ml";;

let HTMLCDOCDIR = "../../doc";;

let X = "hello";;

let Y = 1;;

let definition_on_2_lines =
  "J'espère que
 ça marche!";;

let a_long_definition_can_spread_on_more_than_one_line = "\
ca marche
même sur
plusieurs
lignes!";;

let short_def = "court!";;

(* Defining an alias for this over long identifier. *)
let long_def = a_long_definition_can_spread_on_more_than_one_line;;

let shorter_def = "c";;

(* Rocquencourt Campus's address. *)
let inria_address = "\
INRIA<BR>\n\
Domaine de Voluceau-Rocquencourt<BR>\n\
78153 Le Chesnay CEDEX<BR>\n\
France";;

(***********************
        The Hotel
 ***********************)
let hotel = "«La Datcha»";;
let hotel_address = "\
128 rue de la souris qui se repose\n\
78000 Versailles\n\
France"
;;

(* Also check that newline escapes are properly handled (i.e. ``à la
   Caml''). *)
let newline_escaped_string = "\
    1\
    2\
    3\
    "
;;

(****** (* Nested comments are properly handled *) *******)
(****** (* Including when "nasty strings are added inside *)"
                           the nested comments. *) *******)
(***** Who said that Scanf is not heavy duty ? :) *)

let advi_version = "1.60";;

# We are obliged to fix the htmlc version, in order to get reproducible tests!
let htmlc_version = "1.70";;

let package_version = htmlc_version;;

let last_variable = true;;

So that the Htmlc'c environment variable $X is expanded as hello, and the variable $Y as an integer (1).

And similarly, the system variable <$HOME> is now found to be the value of the variable $HOME in the user's global environment.

As usual, the hôtel $hotel is situated at $hotel_address.

Note that aliases are possible, as the definition of $long_def which is properly bound to the value of $a_long_definition_can_spread_on_more_than_one_line, which is:

ca marche même sur plusieurs lignes!
In the environment file, we purposedly choose to name the last variable defined $last_variable and it is bound to the value true: we can check that its value is effectively ``true''.

Note that $adresse_hotel is :
$adresse_hotel. Meaning that the value bound to a variable can refer to the value of another variable.

As usual, the hôtel «La Datcha» is situated at 128 rue de la souris qui se repose 78000 Versailles France.

File inclusion

Here, we include the file included-eng.html.

Here is the beginning of the file included-eng.html. In this included file, we also have some variables to be expansed, as <$HOME> (bound in the Unix environment) or the INRIA's Rocquencourt campus adress (bound in the Htmlc expansion environment). We write:

$inria_address
and since the variable ($(inria_address)) is defined in the environment file ``env1.ml'', we obtain:
INRIA
Domaine de Voluceau-Rocquencourt
78153 Le Chesnay CEDEX
France

Here is the end of the file included-eng.html.

Executing arbitrary commands: exec

If command name is the name of a Unix command accessible to the compiler, then write

<!--#exec cmd="command name"-->
to include the output of the command in your document. For instance, using "ls *.ml", we get the list of ml files in the test directory of the compiler's source:
catpp.ml
env1.ml
env2.ml
env3.ml
env4.ml
env9.ml
prepro.ml

So for instance, you get the date of compilation with the following line:

<!--#exec cmd="date"-->

Size of files: fsize

An easy way to have the size of a file is to ask it to the underlying file system, using:

<!--#fsize file="example-eng.html"-->
for instance, (the source file of) this file is 6261 bytes long.

Printing names: echo

The command echo let's you output the value bound to a variable:

<!--#echo var="$myvar"-->

Defining names: set and define

You can define variables in your document using the command define as follows:

<!--#define myvar="myvalue"-->
You can bind names to constants
<!--#define myvar="Pierre Weis, INRIA researcher"-->

Then <!--#echo var="$myvar"--> gives you: Pierre Weis, INRIA researcher
You can also bind names to constants computed at compile time
<!--#define myvar_with_quotes="«$myvar»"-->

Then <!--#echo var="$myvar_with_quotes"--> gives you: «Pierre Weis, INRIA researcher»
Using set, you can bind names to arbitrary values computed at file expansion time
Using exec, you compute the value you want to bind via set:
<!--#set thefiles="<!--#exec cmd=\"ls *[eng,fra].html\"-->"-->
This way, the value of the variable $thefiles is set to the list of files in the current working directory that contain eng or fra in their names and have suffix .html, at the time of compilation of this very source file. The value given to $thefiles is also obtained by calling echo:
<!--#echo var="$thefiles"-->
that is:
example-eng.html
example-fra.html
included-eng.html
included-fra.html