À qui s'adresse ce document
Le but de ce document est de décrire les outils utilisés pour produire les pages HTML contenant les traductions françaises de la Gazette Linux à partir des fichiers DocBook.
Il s'adresse à toute personne désireuse de comprendre comment fonctionnent les outils mis en place. Il n'est pas du tout nécessaire de le lire pour savoir utiliser ces outils.
Ce texte ne décrit pas en détails les outils. Des commentaires se trouvent dans les fichiers pour répondre à ce genre d'interrogations.
Rappel
Les traductions de la Gazette Linux sont rédigées dans le format DocBook. Elles sont ensuite converties en HTML pour être publiées sur le site http://gazette.traduc.org/nouvelle_lecture.php où les articles sont lus par les visiteurs du site.
Le DocBook est une convention définissant des balises XML. Ces balises sont conçues pour désigner les différents éléments constituant un document. Le DocBook s'attache à identifier le contenu du document et, dans un monde idéal, ne devrait pas devoir s'occuper de la mise en page.
Convertir le DocBook en HTML
La conversion d'un document DocBook dans un autre format nécessite deux choses: une série de règles pour effectuer la conversion et un moteur sachant appliquer ces règles.
Le moteur utilisé pour convertir le DocBook est xsltproc et les règles de conversions pour le HTML sont fournies par les Docbook XSL Stylesheets de Norman Walsh.
Cependant les fichiers HTML produits par docbook.xsl sont plutôt minimalistes. Nous avons donc créé une couche au dessus des feuilles de style classiques pour adapter la mise en page à nos besoins.
Contenu des outils fournis
Les outils créés contiennent trois fichiers: gazette.xsl, gazette.css et Makefile.
gazette.xsl
Ce fichier contient les règles que nous voulons voir appliquer par xsltproc lorsqu'il converti un fichier DocBook en HTML. Toutefois, produire un fichier HTML n'est pas une mince affaire et le gros du travail a déjà été fait dans le fichier docbook.xsl. Par conséquent, gazette.xsl repose sur docbook.xsl et redéfini simplement les éléments qui ne nous conviennent pas. Le principe appliqué porte le nom de «Customization Layer».
Pour convertir un document DocBook en HTML grâce à gazette.xsl, il suffit de demander à xsltproc d'utiliser notre feuille de style plutôt que docbook.xsl. Toutefois, toutes les distributions n'installent pas docbook.xsl au même endroit. Il est donc nécessaire d'indiquer à xsltproc où se trouve docbook.xsl sur le système hôte grâce à l'option --path:
xsltproc --path /usr/share/xml/docbook/stylesheet/nwalsh/xhtml gazette.xsl lg000-A.xml > lg000-A.html
Le fichier gazette.xsl importe le fichier docbook.xsl se trouvant à l'endroit indiqué par la ligne de commande.
Le langage employé dans gazette.xsl utilise deux technologies: XSLT qui défini les instructions de traduction du DocBook et XPath qui désigne les éléments sur lesquels les instructions XSLT s'appliquent.
Le principe consiste à repérer les éléments sur lesquelles on veut appliquer des transformations et les remplacer par du code HTML. Dans le cas de gazette.xsl, nous n'avons heureusement que quelques éléments à redéfinir.
Par exemple, considérons le fragment de code suivant:
<xsl:template match="bibliography[@id='authorbiblio']"> ... <xsl:template/>
L'instruction XPath définie dans match s'applique aux balises bibliography du document dont le id vaut exactement authorbiblio. Toute balise correspondant à ce critère déclenchera l'exécution de la séquence XSLT contenue dans la balise xsl:template. Cette séquence n'est pas montrée ici mais elle a pour but de différencier les bibliographies contenant une liste d'ouvrages de références de la bibliographie de l'auteur.
gazette.css
Le code HTML seul n'est pas suffisant pour obtenir une présentation attrayante. Il est nécessaire de lui adjoindre une feuille de style CSS. Le navigateur qui lit l'article utilisera cette feuille de style CSS pour mettre en forme le HTML affiché. C'est la feuille de style XSL gazette.xsl qui insère le lien vers le fichier gazette.css dans le fichier HTML.
Par défaut, le document HTML ainsi produit s'attend à trouver le fichier gazette.css dans le même répertoire que le fichier HTML mais il est possible de changer cela en redéfinissant le paramètre html.stylesheet lors de l'appel de xsltproc:
xsltproc --path /usr/share/xml/docbook/stylesheet/nwalsh/xhtml \ --stringparam html.stylesheet ../gazette.css gazette.xsl lg000-A.xml > lg000-A.html
Signalons que le fichier gazette.css n'est pas du tout nécessaire pour convertir le document DocBook en HTML. Il n'est même pas nécessaire que le fichier gazette.css soit à l'emplacement indiqué à xsltproc. Seul le navigateur qui lit l'article en HTML doit pouvoir trouver le fichier gazette.css au moment où il charge la page HTML.
Makefile
Même sans chercher à traduire de nombreux articles, taper à chaque fois les commandes pour exécuter xstlproc peut vite devenir fastidieux.
Pour simplifier la tâche, le fichier Makefile contient des instructions qui automatisent cette opération. Ces instructions valident et convertissent en HTML tout document XML qui a été ajouté ou modifié depuis la dernière conversion. Makefile est lu par la commande make bien connue des développeurs. Cette commande doit être présente sur votre ordinateur pour que le fichier Makefile vous soit d'une quelconque utilité.
Étant donné que Makefile valide le document DocBook avec xmllint, cette commande doit également être installé sur votre ordinateur. Si ce n'est pas le cas, il est possible (mais pas recommandé du tout) de désactiver cette étape en modifiant le fichier Makefile.
Avant de pouvoir utiliser Makefile, vous devez ajuster le chemin qui se trouve dans la variable xsldir pour qu'elle contienne le répertoire où se trouve le fichier xhtml/docbook.xsl. Ce chemin diffère d'une distribution à l'autre.
La mise à jours de tous les documents HTML contenus dans le répertoire courant où se trouvent aussi les fichiers DocBook (dont le nom correspond à lg*.xml), Makefile et gazette.xsl est réalisée en tapant la commande
make
Les fichiers DocBook dont le nom correspond au masque lg*.xml seront vérifiés avec xmllint puis, si il n'y a pas d'erreur, ils seront convertis en HTML par xsltproc. Si un document n'a jamais été converti et n'a donc pas encore de fichier HTML associé, il sera converti en même temps. Autrement dit, après avoir exécuté la commande make, vous obtiendrez tous les fichiers HTML correspondants aux fichiers lg*.xml du répertoire courant.
Si vous souhaitez mettre à jour un seul fichier HTML même si d'autres fichiers XML ont été modifiés, utilisez plutôt la commande
make lg177-A.html
Notez que la commande indique le nom du fichier HTML à mettre à jour. Ce fichier peut ne pas exister. Dans ce cas, il est créé.
Si make trouve que le fichier HTML est déjà assez récent mais que vous êtes sûr du contraire, forcez la création du fichier HTML avec la commande
make -B lg177-A.html
De même, make -B force la création ou la mise à jour de tous les documents HTML possédant un fichier XML dans le répertoire courant.
Makefile propose encore une fonctionnalité qui peut s'avérer très utile. Il permet de faire une copie de sauvegarde des articles DocBook qui se trouvent dans le répertoire courant avec la commande
make backup
Tous les fichiers lg*.xml ainsi que les outils gazette.css, gazette.xsl et Makefile seront archivés dans un fichier lg-date.tar.bz2 où date est remplacé par la date du jour au format AAAAMMJJHHMM. Cela ne remplace pas un bon gestionnaire de révisions de sources tel que git mais si vous l'utilisez régulièrement, il peut vous protéger contre les mésaventures qui viennent perturber la vie tranquille d'un document sous forme informatique.
