Htmlc
: un générateur de fichiers texte
On utilise htmlc
pour produire des fichiers textes dont
certaines parties doivent être calculées pendant la génération du texte.
Des exemples typiques:
Dans chacun de ces cas, il est nécessaire d'incorporer des données qui ne sont pas connues au moment de l'écriture du texte. Ces données sont obtenues en utilisant des moyens divers: interrogation du système d'exploitation (pour connaître le type de machine sur lequel le programme va s'exécuter, pour avoir la date et l'heure afin d'identifier précisément la version d'un logiciel); utilisation de données fabriquées à la volée (notamment des résultats de calcul et d'exemples) ou simplement incorporation systématique de certaines parties du document qui sont partagées pour en changer facilement et de façon cohérente dans tous les textes d'un corpus.
À partir d'un fichier source annoté spécialement, htmlc
produit le fichier texte attendu qui intègre les parties calculées du fichier
source.
On obtient ainsi facilement des textes issus de patrons ou squelettes de documents (en anglais templates) écrits une fois pour toutes.
Exemple:
pour les pages d'un site WEB, le patron comporte un entête et un pied de
page qui définit la signature graphique du site.
À partir d'un tel patron, htmlc
produit un fichier HTML standard et
vous offre ainsi le moyen de gérer le site WEB en définissant un
ensemble de modèles de pages qui factorise une bonne fois pour toutes
l'écriture des parties répétitives des pages HTML.
Pour diriger la génération des textes, on utilise des
directives pour htmlc
; ces directives sont des
commentaires HTML présents dans le fichier source HTML, et
htmlc
les exécute et écrit leur résultat dans le fichier
de sortie.
Les directives pour htmlc
ont la syntaxe des
directives des serveurs Apache (lorsque les directives Apache
correspondantes existent). htmlc
est donc une sorte de
compilateur des pages HTML servies par le serveur, puisque les macros
sont complètement expansées dans les fichiers produits par
htmlc
. L'intérêt de cette pratique est évidemment que le
serveur Apache n'a plus à faire dynamiquement l'analyse des fichiers
qu'il sert à la recherche des directives: le travail est réalisé statiquement
lors de la génération de la page. Avantage supplémentaire: on détecte
les erreurs très tôt, pendant la phase d'expansion des directives, au
lieu de découvrir ces erreurs lors du service des pages (ce qui est de
toutes façons trop tard puisque la page erronée est déjà parvenue au
client).
De plus, vos pages sources ne sont plus dépendantes des
spécificités d'un serveur HTTP particulier qui comprenne et traite les
directives des pages: les directives htmlc
n'ont pas à
être réécrites si vous changez votre serveur ou sa configuration.
Bien plus, les pages produites par htmlc
sont aussi
complètement indépendantes d'un serveur HTTP: elle peuvent être
consultées sans serveur. C'est une propriété généralement
souhaitable, mais bien entendu indispensable dès qu'il s'agit de
produire un site WEB consultable localement, en dehors de tout accès
réseau. Par exemple, un site dont les pages sont expansées par
htmlc
est directement utilisable sur CD-ROM, ses pages
sont lisibles par tout navigateur, sans nécessiter l'installation d'un
serveur HTTP sur l'ordinateur de l'utilisateur.
À l'endroit où l'on veut inclure le texte, on écrit une directive d'inclusion du fichier contenant ce texte. Cette directive consiste en une seule ligne contenant le nom du fichier à inclure:
<!--#include virtual="nom du fichier à inclure"-->
nom du fichier à inclure
» est le nom du fichier
contenant le texte à inclure.
Exemple: inclusion systématique du type du document, ou du pied de page.
Remarque: les fichiers à inclure
sont recherchés dans une liste de répertoires commençant par le
répertoire courant. On modifie cette liste en appelant le générateur
avec une ou des options -I nom_de_répertoire
qui ajoute
nom_de_répertoire
à la liste des répertoires où chercher
les fichiers à inclure.
En ce cas, les caractères spéciaux de HTML sont automatiquement échappés
(par exemple <
devient <
dans le texte
inclus, et sera de la sorte correctement compris par le navigateur).
À l'endroit où l'on veut inclure un texte verbatim, on écrit
<!--#include verbatim="nom du fichier à inclure"-->
nom du fichier à inclure
» est le nom du fichier
contenant le texte à inclure.
Exemple: inclusion de programmes.
Remarque: les fichiers verbatims à inclure sont aussi recherchés dans la liste des répertoires d'inclusion.
On écrit
<!--#echo var="LAST_MODIFIED"-->
htmlc
tente de déterminer le langage utilisé par le fichier
source afin d'inclure la date dans la langue du fichier source (et non pas
systématiquement en anglais). La langue est déterminée d'après le nom du
fichier traité. Les règles utilisées sont les suivantes:
nompropre-lang.extension
(ou bien
nompropre.lang.extension
), où
nompropre
est une suite de lettres (le nom
particulier du fichier),-
ou d'un caractère
.
,lang
de deux ou
trois lettres,.
,extension
(en général
html
).lang
du nom du
fichier, qui est interprétée comme le fait Internet pour les noms de
pays. Si cette interprétation échoue, la langue du fichier
est supposée être l'anglais.lang
n'existe pas, mais que
l'extension existe, on tente d'interpréter le nompropre
comme l'indication de langue.htmlc
les seules langues
reconnues sont le français et l'anglais.Exemple: le fichier htmlc-fra.html
a pour
indication de langue fra
, comprise comme fr
;
htmlc-fra.html
est donc supposé être un document écrit en
français. De même pour htmlc.fra.html
ou fra.html
ou fr.html
ou même fr.ml
.
htmlc
offre la possibilité de fixer la langue utilisée pour
l'expansion des fichiers: le mécanisme de recherche de la langue par
détection des suffixes dans les noms de fichiers n'est alors plus utilisé et
c'est la langue spécifiée en ligne de commande qui prévaut.
Exemple:
htmlc -lang fr foo.html
foo.html
en utilisant le français.
htmlc
permet aussi de fixer la langue par défaut (celle
qui est utilisée si aucune règle de suffixe ne s'applique).
Exemple:
htmlc -default-lang uk foo.html
foo.html
en utilisant l'anglais comme
langue par défaut.
Si l'on cite le nom d'une variable entre <
et
>
, ce texte est remplacé par la valeur de la variable
d'environnement citée.
Exemple:
Mon nom est <$USER> et mon répertoire principal a pour
adresse <$HOME>.
produit le texte suivant:
Mon nom est weis et mon répertoire principal a pour adresse /home/yquem/cristal/weis.
Au lancement, htmlc
définit un certain nombre de
variables. Par example, les variables last_year
,
this_year
et next_year
sont prédéfinies et valent
respectivement la valeur de l'année dernière, celle de cette année et celle
de l'année prochaine.
Exemple:
Cette année est l'année <$this_year>.
produit le texte suivant:
Cette année est l'année 2009.
La commande htmlc
est le générateur des textes finaux à
partir des textes source. Elle fonctionne à la manière d'un compilateur
qui traite les fichiers dont les noms lui sont donnés sur la ligne
de commande et produit des textes en sortie débarrassés des directives
contenues dans les fichiers d'entrée.
htmlc
propose de nombreuses options pour diriger son
fonctionnement.
Exemple: htmlc
admet des options classiques de compilateur comme
-I <dirname>
pour ajouter un répertoire dans le
chemin de recherche des fichiers à lire,-c <file_name.html>
pour compiler
file_name.html
vers le fichier file_name.htm
,-o <file_name>
pour obtenir le résultat dans le
fichier file_name
,-debug
pour obtenir des informations lors de l'exécution
de la commande.Voici un court abbrégé de la manière d'utiliser htmlc
:
Usage: htmlc [-I] [include-dir] <source> <destination> or htmlc <source> or htmlc [-i|-f|-from] <source> [-o|-t|-to] <destination>
Pour plus d'information sur les options de htmlc
, consultez
sa page de manuel Unix ou l'aide fournie par la commande avec l'option
-help
.
Note: par défaut, l'entrée de htmlc
est lue sur
l'entrée standard et sa sortie est écrite sur la sortie
standard. htmlc
peut ainsi servir de processeur dans une
succession de commandes (un pipe Unix).
htmlc
pour gérer un site web ?Le problème réside principalement dans le grand nombre de fichiers à
traiter. Nous proposons une méthodologie basée sur des fichiers de
configuration pour l'utilitaire Unix make
qui s'est révélée
efficace dans la pratique.
Un point clé est de soigneusement distinguer entre les
sources des fichiers HTML et les objets: les sources
sont les fichiers non expansés (ceux qu'on édite), et les objets sont
les fichiers expansés (ceux qu'on n'édite pas et qui sont produits
automatiquement par htmlc
).
On adopte donc les conventions suivantes:
.html
,.htm
.Les fichiers objets seront placés dans un répertoire accessible au
serveur HTTP (quelquefois appelé aussi serveur WEB),
nommons-le répertoire WEB
, puisque ce sont précisément
ces fichiers que le serveur HTTP enverra sur le réseau. En revanche
les fichiers sources seront placés dans un répertoire gérés
par les éditeurs du site, nommons-le répertoire SRC
, qui
sera sans doute inaccessible au serveur HTTP.
La méthode préconisée consiste à utiliser deux Makefiles pour gérer le site:
SRC/Makefile
gère l'expansion de
l'ensemble des fichiers sources en les fichiers objets correspondants.WEB/Makefile
recopie les fichiers
expansés du répertoire SRC
dans le répertoire WEB
.On remarque donc que le répertoire WEB
ne comporte que
les fichiers strictement nécessaires à la consultation des pages HTML,
tandis que le répertoire SRC
comporte à la fois les
sources de ces pages et leurs objets. Le répertoire SRC
comporte aussi un sous-répertoire pour les fichiers à inclure; on
supposera dans la suite que ce répertoire s'appelle Includes
,
et la commande d'expansion des fichiers sources comportera donc
systématiquement l'option -I Includes
.
SRC
FILES=htmlc-fra.html htmlc-eng.html HTMLC=htmlc -I Includes OBJS=$(FILES:.html=.htm) all: $(OBJS) clean: /bin/rm -f $(OBJS) .SUFFIXES: .SUFFIXES: .htm .html .html.htm: $(HTMLC) -f $< -t $@
FILES
pour y mettre la liste des fichiers source (la
liste donnée ici correspond à la propre documentation de Htmlc
).
WEB
(ce fichier est disponible en ligne)
SRC=../doc_src FILES=htmlc-fra.htm htmlc-eng.htm AUTO=.Makefile.auto all: $(AUTO) expand $(FILES) expand: cd $(SRC); make clean: $(AUTO) cd $(SRC); make clean /bin/rm -f $(FILES) $(AUTO): Makefile $(AUTO): /bin/rm -f $(AUTO) for i in $(FILES); do j=`basename $$i .htm`; echo $$i: $(SRC)/$$j.htm >> $(AUTO); echo >> $(AUTO); echo $(SRC)/$$j.htm: >> $(AUTO); echo -n " chmod +w $$j.htm; " >> $(AUTO); echo "cp -p $(SRC)/$$j.htm $$j.htm" >> $(AUTO); done include $(AUTO)
SRC
et FILES
pour y mettre respectivement
l'adresse du répertoire des sources et la liste des fichiers objets
désirés. La méthode de construction consiste à copier les fichiers du
répertoire $(SRC)
dans le répertoire des objets. Pour
cela le Makefile fabrique l'ensemble des règles de copie correspondant
aux fichiers à créer. Ces règles sont alors incluses automatiquement
par la dernière ligne du fichier. Cela explique pourquoi, il faut
initialiser le processus lors de l'installation de ce Makefile, en
tapant
touch .Makefile.auto make all
.Makefile.auto
et
permet ensuite de lancer le Makefile pour créer les règles
nécessaires avant de compiler les fichiers.
Cette organisation en deux répertoires séparés présente de nombreux
avantages: le site proprement dit ne comporte que les fichiers
strictement nécessaires, les fichiers auxiliaires ne se trouvant que
dans le répertoire SRC
; en outre les modifications
apportées au site ne sont pas immédiatement effectives et visibles de
l'ensemble des lecteurs du site Web: on peut modifier les pages
sources et même les expanser et les examiner à loisir sans troubler
les utilisateurs du site; après toutes les vérifications utiles, une
simple commande make
exécutée dans le répertoire
WEB
publie ces modifications en les rendant accessibles
au server WEB.
Cette organisation s'est révélée extrêmement efficace pour l'écriture et le développement de l'ensemble des pages HTML de la FAQ du langage Caml.
Pour inclure systématiquement le type du document, on écrira en première ligne de chaque fichier:
<!--#include virtual="doctype" -->
doctype
dans le fichier.
Si le fichier doctype
contient:
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN" "http://www.w3.org/TR/REC-html40/loose.dtd">
<!--#include virtual="doctype" --> <HTML> <HEAD> <TITLE>Foire aux questions au sujet de Caml</TITLE> </HEAD>
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN" "http://www.w3.org/TR/REC-html40/loose.dtd"> <HTML> <HEAD> <TITLE>Foire aux questions au sujet de Caml</TITLE> </HEAD>
Pour inclure dans une page HTML, un pied de page défini une fois
pour toutes dans le fichier basdepage-fra.html
, il suffit
d'écrire, la ligne:
<!--#include virtual="basdepage-fra.html"-->
Alors, si le fichier basdepage-fra.html
contient:
<P> <HR> <EM>Dernière modification: </EM> <!--#echo var="LAST_MODIFIED" --> <BR> <A HREF="copyright-fra.htm">Copyright</A> © 1997 - 2005 INRIA, tous droits réservés.
<!--#include virtual="basdepage-fra.html"--> </BODY> </HTML>
htmlc
en:
<P> <HR> <EM>Dernière modification: </EM> <!--#echo var="LAST_MODIFIED" --> mardi 15 février 2005 <BR> <A HREF="copyright-fra.htm">Copyright</A> © 1997 - 2005 INRIA, tous droits réservés. </BODY> </HTML>
Pour inclure dans votre texte le programme Caml contenu dans le fichier
exemple_caml.ml
, il suffit d'écrire, la ligne:
<!--#include verbatim="exemple_caml.ml"-->
exemple_caml.ml
contient:
let succ x = x + 1;; succ : int -> int = <fun>
let succ x = x + 1;; succ : int -> int = <fun>
Pour alléger l'écriture des pages d'un site WEB, on peut très bien définir un ensemble de maquettes comportant des inclusions prédéfinies.
Par exemple, le fichier maquette de trois lignes suivant, permet d'abstraire le type du document, son entête et son pied de page:
<!--#include virtual="avanttitre-fra.html"--> <!--#include virtual="aprestitre-fra.html"--> <!--#include virtual="findepage-fra.html"-->
Le créateur des pages HTML n'a plus qu'à mettre le titre de la page entre les deux lignes d'inclusion pour obtenir un fichier HTML complet:
<!--#include virtual="avanttitre-fra.html"--> L'expanseur <CODE>htmlc</CODE> <!--#include virtual="aprestitre-fra.html"--> <H2 ALIGN=LEFT>De quoi s'agit-il ?</H2> <P>On utilise ... <!--#include virtual="findepage-fra.html"-->
avanttitre-fra.html
contient:
<!--#include virtual="doctype" --> <!-- Fichier avanttitre-fra.html inclus avant le titre de la page --> <HTML> <HEAD> <TITLE>
aprestitre-fra.html
contient:
<!-- Fichier aprestitre-fra.html inclus après le titre de la page --> </TITLE> </HEAD> <BODY BGCOLOR="#FFFFFF"> <!--#include virtual="hautdepage-fra.html"-->
findepage-fra.html
contient:
<!-- Fichier findepage-fra.html inclus à la dernière ligne de la page --> <P> <HR> <EM>Dernière modification: </EM> <!--#echo var="LAST_MODIFIED" --> </BODY> </HTML>
hautdepage-fra.html
contient:
<ADDRESS>Contacter l'auteur <A HREF="mailto:Pierre.Weis@inria.fr">Pierre.Weis@inria.fr</A></ADDRESS>
doctype
et
findepage-fra.html
ont le même contenu que ci-dessus
Alors le fichier:
<!--#include virtual="avanttitre-fra.html"--> L'expanseur <CODE>htmlc</CODE> <!--#include virtual="aprestitre-fra.html"--> <H2 ALIGN=LEFT>De quoi s'agit-il ?</H2> <P>On utilise ... <!--#include virtual="findepage-fra.html"-->
htmlc
en le fichier:
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN" "http://www.w3.org/TR/REC-html40/loose.dtd"> <!-- Fichier avanttitre-fra.html inclus avant le titre de la page --> <HTML> <HEAD> <TITLE> L'expanseur <CODE>htmlc</CODE> <!-- Fichier aprestitre-fra.html inclus après le titre de la page --> </TITLE> </HEAD> <BODY BGCOLOR="#FFFFFF"> <ADDRESS>Contacter l'auteur <A HREF="mailto:Pierre.Weis@inria.fr">Pierre.Weis@inria.fr</A></ADDRESS> <H2 ALIGN=LEFT>De quoi s'agit-il ?</H2> <P>On utilise ... <!-- Fichier findepage-fra.html inclus à la dernière ligne de la page --> <P> <HR> <EM>Dernière modification: </EM> <!--#echo var="LAST_MODIFIED" --> mardi 15 février 2005 <BR> <A HREF="copyright-fra.htm">Copyright</A> © 1997 - 2005 INRIA, tous droits réservés. </BODY> </HTML>
Nous définissons maintenant une variable spécifique à l'expansion de ce fichier:
<!--#define $HtmlcVersion="2.21"-->
La version de Htmlc est maintenant connue du compilateur. Par exemple
Voilà la version: <!--#echo var="$HtmlcVersion"-->.
Voilà la version: 2.21.
Mais cette méthode est inutilement compliquée: inutile d'utiliser une directive pour obtenir la valeur d'une variable! Après sa définition, il suffit de citer cette variable, car Htmlc sait alors la remplacer par sa valeur. On écrit donc simplement
Voilà la version: $HtmlcVersion
Voilà la version: 2.21
Contacter l'auteur Pierre.Weis@inria.fr
Fichier créé le:
20 février 2000
Dernière modification le
mardi 15 septembre 2009
(sur la machine yquem
, par l'utilisateur weis).
Copyright © 1997 - 2009 INRIA, tous droits réservés.