Htmlc: un générateur de fichiers texte

Version 2.6

Où trouver le logiciel ?

Les sources d'Htmlc par http sont ici (protocole http).

ou là (protocole ftp).

De quoi s'agit-il ?

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:

  1. macro génération d'un programme avant compilation,
  2. fabrication de documentation, cours et documents divers,
  3. création et maintenance des pages d'un site WEB.

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.

I Principe

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.

II Comment s'en servir ?

Écriture des textes sources

Inclusion de textes

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

où «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.

Inclusion de textes sans modifications (programmes)

En ce cas, les caractères spéciaux de HTML sont automatiquement échappés (par exemple < devient &lt; 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"-->

où «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.

Inclusion de la date de modification du fichier source

:

On écrit

<!--#echo var="LAST_MODIFIED"-->

et cette remarque est remplacée dans le fichier par la date en clair de la dernière modification du fichier.

Internationalisation des dates par les suffixes

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:

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.

Internationalisation des dates par une option

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

expanse le fichier 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

expanse le fichier foo.html en utilisant l'anglais comme langue par défaut.

Substitution de la valeur d'une variable d'environnement

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 cfranchi et mon répertoire principal a pour adresse /home/cfranchi.

Substitution de la valeur d'une variable prédéfinie

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 2014.

Production des textes finaux

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

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).

III Comment utiliser 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:

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:

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.

Discussion

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.

IV Exemples

Inclusion d'entêtes

Pour inclure systématiquement le type du document, on écrira en première ligne de chaque fichier:

<!--#include virtual="doctype" -->

ce qui ordonne l'inclusion du texte du fichier 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">

alors le fichier
<!--#include virtual="doctype" -->

<HTML>

<HEAD>
<TITLE>Foire aux questions au sujet de Caml</TITLE>
</HEAD>

devient
<!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>

Inclusion d'un pied de page

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.

le fichier source
<!--#include virtual="basdepage-fra.html"-->

</BODY>
</HTML>

est transformé par 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>

Inclusion d'un programe

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

Alors, si le fichier exemple_caml.ml contient:
 let succ x = x + 1;;
 succ : int -> int = <fun>

la ligne d'inclusion sera remplacé par:
 let succ x = x + 1;;
 succ : int -&gt; int = &lt;fun&gt;

Maquettes de pages HTML

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

En effet, si l'on suppose que

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

est expansé par 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>
 

Définition de variable

Nous définissons maintenant une variable spécifique à l'expansion de ce fichier:

 <!--#define $HtmlcVersion="2.6"-->

La version de Htmlc est maintenant connue du compilateur. Par exemple

Voilà la version:
<!--#echo var="$HtmlcVersion"-->.

produit le texte
Voilà la version:
2.6.

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

pour obtenir
Voilà la version: 2.6

Htmlc is a cool tool to generate text files!


Contacter l'auteur Pierre.Weis@inria.fr

Fichier créé le: 20 février 2000
Dernière modification le lundi 21 mars 2011 (sur la machine double-glazed , par l'utilisateur cfranchi).

Copyright © 1997 - 2014 INRIA, tous droits réservés.