== À 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 [[http://linuxgazette.net|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 [[../Format_DocBook|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 Doc''''''Book 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 Doc''''''Book 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 Doc''''''Book 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 Doc''''''Book est {{{xsltproc}}} et les règles de conversions pour le HTML sont fournies par les [[http://wiki.docbook.org/topic/DocBookXslStylesheets|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 Doc''''''Book 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 «[[http://www.sagehill.net/docbookxsl/CustomMethods.html|Customization Layer]]». Pour convertir un document Doc''''''Book 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: [[http://www.w3schools.com/xsl/|XSLT]] qui défini les instructions de traduction du Doc''''''Book et [[http://www.w3schools.com/xpath/default.asp|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: {{{ ... }}} 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 [[http://www.w3.org/TR/CSS21/|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 Doc''''''Book 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 [[http://www.gnu.org/software/make/manual/make.html|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 Doc''''''Book 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 Doc''''''Book (dont le nom correspond à {{{lg*.xml}}}), {{{Makefile}}} et {{{gazette.xsl}}} est réalisée en tapant la commande {{{ make }}} Les fichiers Doc''''''Book 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 Doc''''''Book 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.