Htmlc : un générateur de fichiers HTML

Version 1.70

Compilation

Ce fichier se compile à l'aide de la commande:

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

Définition de l'environnement de compilation

Les fichiers d'environnement sont des listes de liaisons. Une liaison définit un nom (un identificateur) et le lie à une valeur constante. Une constante est soit un entier, un flottant, un caractère, une chaîne de caractères, un booléen (soit true soit false), ou encore un identificatuer préalablement défini.

Les conventions lexicales pour les constantes et les identificateurs suivent celles du langage Caml.

Les définitions doivent suivre l'une des deux syntaxes suivantes:

Style Caml

Une liaison obéit à la même syntae que celle d'une liaison Caml simple:

let nom = valeur;;

Les commentaires Caml sont acceptés.

Style libre

Une liaison a l'une des deux formes suivantes:

nom = valeur

ou

nom valeur

Les commentaires commencent par un dièse # et se terminent à la fin de la ligne.

Dans tous les cas une liaison doit se terminer par au moins un retour charriot.

Mélanger les deux syntaxes admises pour les liaisons est vivement déconseillé.

Exemples de fichiers d'environnement

Le fichier env0 est en style libre:

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

Le fichier d'environnement env1.ml est, lui, en style Caml:

(*
    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";;

(****** (* 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;;

Ainsi, la variable d'environnement HTMLC $X est remplacée par hello et la variable $Y devient (1).

De même, la variable système <$HOME> devient la valeur de la variable $HOME obtenue dans l'environnement système de l'utilisateur.

Notez que les alias sont possibles: $long_def est lié à la valeur de $a_long_definition_can_spread_on_more_than_one_line, c'est-à-dire:

ca marche même sur plusieurs lignes!

Notez que $adresse_hotel vaut :
$adresse_hotel. ce qui signifie que la valeur liée à une variable peut faire référence à la valeur d'une autre variable.

Comme d'habitude, l'hôtel est «La Datcha». Il est situé au 128 rue de la souris qui se repose 78000 Versailles France.

Inclusion de fichiers

Ici on inclut un fichier, le fichier included-fra.html.

Debut de l'inclusion du fichier included-fra.html... Dans les fichiers inclus les variables sont aussi expansées.

Par exemple le répertoire maison, <$HOME>, est expansé par recherche dans l'environnement de l'utilisateur qui compile le fichier, tandis que l'adresse du site de l'INRIA Rocquencourt est facilement obtenue en écrivant:

$inria_address

INRIA
Domaine de Voluceau-Rocquencourt
78153 Le Chesnay CEDEX
France

Fin de l'inclusion du fichier included-fra.html.

Exécution de commandes arbitraires: exec

Si command name est le nom d'une commande Unix accessible à l'utilisateur du compilateur, alors on écrit

<!--#exec cmd="command name"-->

env1.ml
env2.ml
env3.ml

De même, on produit la date de compilation avec la ligne:

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

Taille des fichiers: fsize

Un moyen facile d'obtenir la taille d'un fichier est d'interroger le système de fichiers sous-jacent à l'aide de la commande prédéfinie fsize:

<!--#fsize file="example-fra.html"-->

Impression de noms définis: echo

La commande echo vous permet d'imprimer la valeur liée à un nom:

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

Définition de noms dans les documents: set et define

On peut définir des variables directement dans le fichier source avec la commande define:

<!--#define myvar="myvalue"-->

On peut lier des noms à des constantes

<!--#define myvar="Pierre Weis, INRIA researcher"-->

Puis <!--#echo var="$myvar"--> produit le texte: Pierre Weis, INRIA researcher

On peut aussi lier des noms à des constantes calculées au moment de la compilation

<!--#define myvar_with_quotes="«$myvar»"-->

alors <!--#echo var="$myvar_with_quotes"--> produit: «Pierre Weis, INRIA researcher»

Avec set, on peut lier des noms à des valeurs arbitraires calculées au moment de l'expansion du fichier

Avec la commande prédéfinie exec, on calcule la valeur qu'on désire attribuer à une variable à l'aide de set:

<!--#set thefiles="<!--#exec cmd=\"ls *[eng,fra].html\"-->"-->

Ainsi, la valeur de la variable $thefiles est la liste des noms de fichiers du répertoire courant qui contiennent eng ou fra dans leur nom et ont le suffixe .html, au moment de la compilation de ce fichier. La valeur attribuée à $thefiles est encore obtenue avec la commande echo:

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

c'est-à-dire:

example-eng.html
example-fra.html
included-eng.html
included-fra.html