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

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

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

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:

• le nom du fichier est mis sous la forme nompropre-lang.extension (ou bien nompropre.lang.extension), où
  • nompropre est une suite de lettres (le nom particulier du fichier),
  • suivi d'un caractère - ou d'un caractère .,
  • suivi d'une indication de langue lang de deux ou trois lettres,
  • suivie d'un caractère .,
  • suivi d'une extension (en général html).
  
  Alors la langue est la partie 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.
• Si le champ lang n'existe pas, mais que l'extension existe, on tente d'interpréter le nompropre comme l'indication de langue.
• Par défaut, la langue du fichier est supposée être l'anglais.
• Dans cette version de 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.

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

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

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

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

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:

• un fichier source porte le suffix .html,
• un fichier objet porte le suffix .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:

• le fichier SRC/Makefile gère l'expansion de l'ensemble des fichiers sources en les fichiers objets correspondants.
• le fichier 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.

• Voici un exemple de fichier Make pour le répertoire SRC

  FILES=htmlc-fra.html htmlc-eng.html
  HTMLC=htmlc -I Includes
  
  OBJS=$(FILES:.html=.htm)
  
  all: $(OBJS)
  
  clean:
          rm -f $(OBJS)
  
  .SUFFIXES:
  .SUFFIXES: .htm .html
  
  .html.htm:
          $(HTMLC) -f $< -t $@
  

  
  Pour utiliser ce fichier, il suffit de modifier la variable FILES pour y mettre la liste des fichiers source (la liste donnée ici correspond à la propre documentation de Htmlc).
• Voici un exemple de fichier Make pour le répertoire 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
          rm -f $(FILES)
  
  $(AUTO): Makefile
  
  $(AUTO):
          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)
  

  
  Pour utiliser ce fichier, il suffit de modifier les variables 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
  

  
  ce qui crée le fichier de règles vide .Makefile.auto et permet ensuite de lancer le Makefile pour créer les règles nécessaires avant de compiler les fichiers.

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

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>

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.

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

</BODY>
</HTML>

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

 let succ x = x + 1;;
 succ : int -> int = <fun>

 let succ x = x + 1;;
 succ : int -> int = <fun>

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

• le fichier avanttitre-fra.html contient:

      <!--#include virtual="doctype" -->
      <!-- Fichier avanttitre-fra.html inclus avant le titre de la page -->
  
      <HTML>
  
      <HEAD>
      <TITLE>
     

• le fichier 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"-->
     

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

• le fichier hautdepage-fra.html contient:

     <ADDRESS>Contacter l'auteur <A HREF="mailto:Pierre.Weis@inria.fr">Pierre.Weis@inria.fr</A></ADDRESS>
     

• tandis que les fichiers 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"-->

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

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

Voilà la version: 2.6

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.