Abstract
Le but de cet article est de décrire un système de publication basé sur DocBook en utilisant les feuilles de style de transformation XML, XLST, plutôt que les sgml-tools qui sont le plus souvent décrits dans les tutoriels.Table of Contents
L'utilisation de DocBook se divise en deux parties :
la rédaction du document en lui-même, qui consiste à créer un fichier texte délimité par des balises XML (comme un fichier HTML par exemple)
la transformation de ce document en un autre type de document : HTML, PDF, PS ou autre. Pour cela on utilise une sorte de moulinette qui réunit le fichier DocBook à publier et un fichier contenant le style à appliquer pour obtenir le document final
Car l'avantage de DocBook est bien celui-là : pouvoir séparer complètement le contenu de la présentation. Combien de documents ont du être réecrit pour changer de média ou simplement d'outils. Avec DocBook, une fois le document écrit, il peut être décliné suivant ses besoins, juste en déclarant le style, mais en conservant le texte et sa structure.
Il existe deux versions du système DocBook, une version SGML et une version XML. Je ne perdrai pas de temps à discuter de leurs différences qui ne me semble pas très significative au point de vue du document DocBook en lui même. Par contre la distinction prend tout son sens lorsqu'on aborde la partie édition. La version SGML utilise des feuilles de styles DSSSL un peu trop compliqués à mon gout, et souvent publier un document DocBook revient à utiliser un squelette mis au point par un gourou du fin fond du New-Jersey qui ne nous convient pas vraiment. En plus, je ne pense pas qu'il soit rentable de s'investir dans l'apprentissage de DSSSL alors que son équivalent XML, XSLT monte en puissance et est relativement simple d'emploi.
Comme je n'ai pas trouvé de document expliquant comment se passer des outils SGML pour publier avec DocBook, et utiliser des outils XML, j'ai décidé d'écrire cet article.
On peut aborder DocBook de plusieurs façon. Par exemple on peut dire que DocBook est basé sur une DTD définissant 300 balises, préparer son aspirine et se lancer dans l'exploration. Mais on peut aussi se dire que DocBook c'est vachement simple, aussi simple que ça :
<?xml version="1.0" encoding="iso-8859-1"?>
<article>
<title>Mon document DocBook</title>
<section>
<title>DocBook, c'est simple</title>
<para>La structure d'un document DocBook est assez évidente au premier coup
d'oeil</para>
<para>On retrouve instinctivement les élément qui composent un document</para>
</section>
</article>
La bonne manière d'aborder le sujet, c'est donc de se dire que la base est extrèmement simple, et que par la suite on dispose de 300 balises pour fignoler notre document, ajouter des images, des liens, des notes de bas de page et ce genre de choses.
On enregistre ce fichier sous essaidocbook.xml
Maintenant qu'on est content d'avoir ce document DocBook, il faudrait pouvoir l'utiliser de façon concrète, c'est à dire qu'il doit pouvoir être lu. C'est là qu'entre en jeu la moulinette dont on a parlé tout à l'heure.
On va continuer à faire simple en transformant notre document en HTML. Et on verra qu'une fois notre modèle établi, on pourra écrire autant de document DocBook que l'on veut pour créer un ensemble de documents HTML ayant un style cohérent.
Pour créer notre document, on utilisera les feuilles de style XML destinés à la transformation : XSLT, eXtensible Styleheet Transformation. Par transformation, il faut comprendre qu'on transforme un document XML ( DocBook ) en un autre fichier XML ( HTML ). Il existe d'autres feuilles de style, dites de formattage, qui permettent de transfomer le XML en un document complètement différent ( PDF, PS ou RTF par exemple) et qui porte le nom de Formatting Objects, d'ou le nom XSL-FO.
Pour arriver à notre fin, il nous suffit d'écrire notre feuille de style et passer le tout à travers notre moulinette. Cette moulinette porte le nom de Processeur XSLT. Le processeur va lire chaque balise du fichier XML, regarder dans la feuille de style s'il y a quelque chose à faire pour chacune d'entre elle.
La Fondation Apache qui aime bien XML nous propose un processeur XSLT appelé Xalan, qui existe en Java ou en C++. On peut le récuperer à l'adresse suivant : http://xml.apache.org/xalan-c. Il existe des versions pour plusieurs plateformes et l'installation ne pose pas de problème particulier.
Il nous reste à écrire la feuille de style.
<?xml version="1.0" encoding="iso-8859-1"?>
<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" version="1.0">
<xsl:output method="html" indent="yes"/>
<xsl:template match="article">
<html>
<head>
<title><xsl:value-of select="title"/></title>
</head>
<body>
<xsl:apply-templates select="section"/>
</body>
</html>
</xsl:template>
<xsl:template match="section">
<h1><xsl:value-of select="title"/></h1>
<xsl:for-each select="para">
<p><xsl:value-of select="."/></p>
</xsl:for-each>
</xsl:template>
</xsl:stylesheet>
On enregistre ce fichier sous essaidocbook.xsl. Il ne nous reste plus qu'a traiter notre fichier DocBook essaidocbook.xml crée au chapitre précédent avec notre feuille de style essaidocbook.xsl, afin de créer un fichier essaidocbook.html.
Pour cela il suffit de taper :
Xalan -o essaidocbook.html essaidocbook.xml essaidocbook.xsl
Et on obtient le fichier essaidocbook.html suivant :
<html>
<head>
<META http-equiv="Content-Type" content="text/html; charset=iso-8859-1"/>
<title>Mon document DocBook</title>
</head>
<body>
<h1>DocBook, c'est simple</h1>
<p>La structure d'un document DocBook est assez évidente au premier coup d'oeil</p>
<p>On retrouve instinctivement les élément qui composent un document</p>
</body>
</html>
Voilà, pas besoin d'en rajouter. Bien sûr, le résultat actuel, c'est le degré zéro du HTML, mais rien ne nous empêche d'ajouter tout le style HTML que l'on veut dans les balises HTML de notre fichier essaidocbook.xsl.
La grande force de ce système, c'est que vous pouvez maintenant ajouter des sections et des paragraphes à votre fichier docbook.xml. En réexecutant Xalan, vous mettrez à jour le fichier HTML conformément au style.
Et bien lorsque le principe de base est éclairci, on peut se lancer dans la lecture des spécifications complètes :
Celle de DocBook et ses 300 balises
DocBook : The definitive guide chez O'Reilly (en anglais)
HowTo : Démarrer avec DocBook (en français)
Celle de XSLT
Transformation XSLT (en français)
XSLT - XSL Transformations (en anglais)
On se rend compte que les spécifications DocBook sont assez complètes et qu'on est loin avec notre petit de l'avoir couverte. Même pour écrire cet article j'ai utilisé un tout petit sous-ensemble de DocBook et le fichier XSLT utilisé ne permet pas de transformer n'importe quel document DocBook. Toutefois, ça me permet de maitriser complètement le résultat final.
Il y a aussi une question que je n'ai pas abordé jusqu'ici. Si DocBook est une simple liste de balise, pourquoi s'encombrer d'une spécification lourde et ne pas se contenter d'utiliser XSLT avec notre propre ensemble de balises ? En fait, DocBook est une DTD, une Document Type Definition publiée par OASIS ( ou Organization for the Advancement of Structured Information Standards ). C'est donc un standard que vous pourrez distribuer facilement, même à ceux qui utilisent les sgml-tools.
Ensuite, et surtout, il n'est jamais très interessant de réinventer la roue. On dispose avec DocBook d'une DTD entièrement rédigée et vérifiée. Et cette DTD va nous permettre de verifier notre document. Car en utilisant un éditeur de texte pour créer notre document, il y a de fortes chances pour qu'on se soit un peu mélangé les balises à un moment ou à un autre, surtout dans un document important.