 |
|
1.Objectif de ce document
Vous trouverez l'ensemble des logiciels nécéssaire sur ce site sur http://www.stephane-arnault.net/download/docbook/
2.Le format DocBook
2.1.PrésentationDocBook est un langage de balisage conçu à la base pour les documentations techniques d’informatique (matériel et logiciel). C'est à l'origine une Définition de type de document (DTD) SGML. 2.2.La syntaxe DocbookDécrire l’ensemble des balises ainsi que leurs fonctionnalités ne serait pas très intéressant. Voici un petit exemple de fichier Docbook qui est très compréhensible et qui explique la facilité déconcertante avec laquelle on peut créer un fichier Docbook. <!DOCTYPE article PUBLIC " -//OASIS//DTD DocBook V3.1//EN"> 3.Les outilsC’est pour cette raison que le premier critère qui va faire le choix d’un outil plutôt qu’un autre sera sa portabilité. Heureusement, la majorité des outils permettant de travailler avec le Docbook sont écrits en Java. Nous pourrons donc exécuter ces applications sur toutes les machines sans avoir à s’adapter à un nouveau logiciel lorsqu’on change d’architecture. Comme nous le verrons, les programmes Java présentent l’inconvénient d’être un peu plus lent que ces homologues c++. Cependant la durée des traitements de génération de documents n’excède pas 30 secondes, ce qui reste acceptable. Tous les outils utilisés devront évidemment être libres d’utilisation.
3.1.Les feuilles de style
L’exportation des fichiers XML de type DocBook dans un format lisible tel que le html ou le pdf est basée sur l’utilisation des feuilles de style xsl. Le projet DocBook est hébergé par sourceforge à l’adresse suivante : http://docbook.sourceforge.net/projects/xsl/. On peut télécharger les feuilles de styles sur http://sourceforge.net/project/showfiles.php?group_id=21935&package_id=16608 . Sans ces feuilles de style, il est impossible de générer le moindre document puisque c’est ces feuilles XSL qui définissent l’affichage produit à partir du fichier XML.
3.2.Editer un fichier Docbook
Après avoir testé de nombreux logiciels pour écrire du Docbook, j’ai retenu deux solutions intéressantes pour créer un nouveau document.
Pour cela, de nombreux éditeurs existent en version freeware. Nous n’allons pas nous attarder sur cette partie, tous les lecteurs de ce document savent, je l’espère, de quoi il s’agit.
Parmi les éditeurs WYSIWYG, celui qui l’emporte haut la main est incontestablement Open-Office qui prend en charge le format DocBook nativement. Par ailleurs l’interface graphique est extrêmement semblable à celle de Microsoft Word, les rédacteurs ne seront donc pas dépaysés.
Note : Il peut être intéressant de rédiger l’intégralité d’un document avec un éditeur WYSIWYG afin de gagner du temps, puis de corriger les erreurs ou améliorer l’affichage en éditant le XML. Un mélange des deux « techniques » ne pose évidemment aucun problème.
3.3.Importer nos document existants en docbook
De la même façon qu’on a créé un document DocBook grâce à open-office, cet outil peut aussi nous servir pour importer nos documents existants. En effet, open-office supporte le format Doc utilisé par word. Il suffit donc d’ouvrir le fichier doc, puis de le sauvegarder en DocBook (XML).
3.4.Exporter un fichier docbook
Nous arrivons dans la partie la plus intéressante du format docBook, l’exportation du fichier. Comme nous l’avons rapidement abordé dans l’introduction, nous passons actuellement beaucoup trop de temps a générer les documents après leurs rédaction. Pire encore, la moindre petite modification du document tel que la correction d’une faute d’orthographe nécessite une nouvelle conversion en PDF, HTML, « parsage » en jsp, compression, envoi sur le site… Pour un simple « S » manquant, il y a 20 minutes de travail aussi intéressant que productif… Grâce à docBook, on modifie le document une seule fois, et les modifications sur les différents exports du document pourraient être automatisées !
3.4.1.Export htmlLe meilleur outil pour faire de l’export en HTML se nomme Saxon. Il est open-source et développé en Java (disponible sur http://saxon.sourceforge.net/.). Il en est à la version 6-5-5 à l’heure ou j’écris ces lignes, cependant le projet à l’air bien suivi et les évolutions sont régulières.
Attention, il existe aussi une version payante nommée Saxon-SA et maintenue par l’entreprise Saxonica, cette version ne nous intéresse évidemment pas.
Utilisation de Saxon Le site officiel nous propose de télécharger une archive qu’il suffit de décompresser. Le fichier que nous devons démarrer est « saxon.jar ». Pour cela nous allons executer la ligne de commande suivante afin de générer une page HTML :
java -jar saxon.jar test.xml "..docbook-xsl-1.69.1xhtmldocbook.xsl">out.html
Le chemin "..docbook-xsl-1.69.1xhtmldocbook.xsl" correspond au chemin de ma feuille de style qui défini l’affichage généré. Je vous invite à relire le chapitre 3.1 avoir de brèves informations sur ces feuilles de style ou pour savoir comment les télécharger.
3.4.2.Export pdf
Pour l’export PDF, la meilleur alternative provient de notre bien aimé fondation Apache. La encore le projet est développé en Java et est Open-Source. Ce logiciel s’appelle FOP et est disponible sur http://xmlgraphics.apache.org/fop. Bien qu’il n’en soit qu’à la version 0.91beta, je l’ai trouvé stable et simple d’utilisation.
Utilisation de FOP L’installation se résume à une simple décompression d’un fichier archivé. Apres avoir décompressé l’archive, on a un sous répertoire « build » qui contient le fichier « fop.jar » qui nous interresse. La commande pour lancer la génération du pdf est :
java -jar fop.jar -xml test.xml -xsl "..docbook-xsl-1.69.1 odocbook.xsl" -pdf out.pdf
Le chemin "..docbook-xsl-1.69.1 odocbook.xsl" correspond au chemin de ma feuille de style qui défini l’affichage généré. Je vous invite à relire le chapitre 3.1 avoir de brèves informations sur ces feuilles de style ou pour savoir comment les télécharger. / ! La feuille de style pour générer le fichier PDF n’est pas la même que celle qui permet de générer un fichier HTML. L’une se trouve dans le sous répertoire « fo » du chemin d’installation de « docbook-xsl », l’autre se trouve dans le sous répertoire xhtml. Lors de la génération du pdf, quelques Exceptions et erreurs peuvent survenir dans la console. Il ne faut pas s’en inquiéter, la génération fonctionnera malgré tout. 4.Travail collaboratif et mises à jour
4.1.Subversion
Comme nous l’avons vu, DocBook est basé sur XML. Il s’agit donc d’un fichier texte linéaire. Cela présente l’énorme avantage de pouvoir être synchronisable grâce à subversion (ou cvs). Ainsi, les conflits produits lors des modifications concurrentes du même document par plusieurs personnes seront gérés quasiment automatiquement. Il pourrait donc être extrêmement judicieux de conserver nos documents sources en Docbook sur subversion afin de pouvoir gérer le versionning et les accès concurrents.
4.2.Automatisation des générations de document
Afin de gagner beaucoup de temps, et pour nous épargner un travail ennuyeux de génération de documents, il serait intéressant d’automatiser la génération de nos documents. Pour cela, une solution très simple consistera à exécuter un script à intervalle de temps régulier (toute les heures par exemple) qui compare la date de modification du fichier source en Docbook et celle des fichiers générés (html, pdf). Ainsi tous les documents Docbook dont la date de modification est ultérieure à celle des documents générés pourraient être à nouveau générés pour être mis à jour sans aucune intervention manuelle. 5.Inconvénients du Docbook
Lors de mes tests, j’ai malgré eu quelques problèmes, principalement au niveau de la mise en page.
6.Conclusion
Nous avons vu dans ce document comment créer des fichiers Docbook, et comment migrer les documentations dans ce format. |
|
||||||||||||||||||||||||||||||||||||||
|
||||||||||||||||||||||||||||||||||||||||
