Créer des documents avec docbook

XML est une spécification décrivant des langages de balise. Elle est destinée à encadrer et à normaliser la création de documents contenant des données. Chaque document XML à sa propre structure. Cette structure est défini par le créateur du document. On utilise principalement deux normes pour décrire la structure d'un document XML : les schémas XML qui sont des documents XML et les fichiers DTD qui répondent à une spécification spécifiques. Ces fichiers permettent aux parseurs XML de vérifier la compatibilité d'un document XML avec la structure décrite.

XSLT est un langage de transformation de documents XML. Pour résumer il permet de transformer un document XML en un autre document XML. Il est par par exemple fréquent d'utiliser XSLT pour transformer un document XML en un document HTML. XSLT utilise pour cette transformation des feuilles de style XSL qui permettent de définir le comportement du processeur XSLT.

Docbook est une spécification destinée à la création de documentations, articles, livres, etc... L'existence d'une telle norme incite les développeurs à créer des feuilles de styles qui permettent de transformer les documents répondant à cette norme en de nombreux formats. Ainsi un document au format Docbook peut facilement être transformé en document HTML, PDF, etc... Il suffit pour cela de trouver la feuille de style appropriée.

Il n'est pas absolument nécessaire de télécharger la spécification. Le processeur XSLT l'utilise pour vérifier la conformité du document à la norme Docbook. On a deux solutions pour que cette vérification puisse se faire. On peut utiliser le fichier directement en ligne, dance ce cas là l'en-tête des document (ici un article) sera de cette forme.

<?xml version="1.0"?>
<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
"http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd">

          

Sinon on peut télécharger la DTD, ce qui nous donne un en-tête de la forme suivante :

<?xml version="1.0"?>
<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
"file:///C:/docbook/docbook-xml-4.2/docbookx.dtd">

          

Pour ma part j'utilise Saxon. Il est simple à télécharger et à utiliser. Il est un peu lent mais à l'avantage d'être en java et donc de pouvoir être utilisé sur toutes les plate-formes. Au moment de la rédaction de ce document, la version recommandée est la 6.5.3. D'autres versions existent déjà.

Téléchargement : http://saxon.sourceforge.net/

Ces feuilles de style ont été créée par Norman Walsh. Il est possible de les personnaliser mais ce n'est pas l'objet de ce tutorial.

On utlisera la feuille de style de Norman Walsh docbook.xsl située dans le répertoire html

Voici le .bat utilisé pour la génération des documents html. Je remet la variable PATH à jour mais si Java est installé correctement sur la machine cette manipulation est inutile. Le document source est manuelDocbook.xml, le document cible manuelDocbook.html.

SET SAXON_HOME=C:\docbook\saxon6_5_3
SET XSL_HOME=C:\docbook\docbook-xsl-1.65.1
SET JAVA_HOME=C:\Program Files\Java\j2re1.4.2_04
SET OUTPUT_PATH=OUTPUT
SET HTML_OUTPUT_PATH=%OUTPUT_PATH%\HTML
SET SRC_PATH=SRC
SET PATH=%PATH%;%JAVA_HOME%\bin
java -classpath %SAXON_HOME%\saxon.jar com.icl.saxon.StyleSheet -o %HTML_OUTPUT_PATH%\manuelDocbook.html %SRC_PATH%\manuelDocbook.xml %XSL_HOME%\html\docbook.xsl

Si tout va bien le fichier HTML est généré.

On ne crée pas directement un fichier CHM, on crée un projet qui permettra de compiler le fichier d'aide avec le programme HTML Help Workshop de Microsoft. Le principal problème est le répertoire de sortie des fichiers générés. En effet en se contentant de changer de feuille de style (on utilisera htmlhelp/htmlhelp.xsl) les fichiers sont générés dans le dossier de la source, ce qui est tout sauf pratique.

La première solution que j'ai trouvé consiste à générer directement à l'aide de l'utilitaire hhc.exe le fichier chm puis à supprimer les fichiers temporaires. Ca ne résoud pas vraiment le problème mais ça permet d'obtenir rapidement un résultat sans trop se pencher sur la feuille de style XSL. Pour cela voici le bat que j'ai utilisé : (HTML Help Workshop doit être installé)

SET SAXON_HOME=C:\docbook\saxon6_5_3
SET XSL_HOME=C:\docbook\docbook-xsl-1.65.1
SET JAVA_HOME=C:\Program Files\Java\j2re1.4.2_04
SET OUTPUT_PATH=OUTPUT
SET HTML_OUTPUT_PATH=%OUTPUT_PATH%\HTML
SET CHM_OUTPUT_PATH=%OUTPUT_PATH%\CHM
SET SRC_PATH=SRC
SET PATH=%PATH%;%JAVA_HOME%\bin
SET PATH=%PATH%;C:\Program Files\HTML Help Workshop
java  -classpath %SAXON_HOME%\saxon.jar com.icl.saxon.StyleSheet %SRC_PATH%\manuelDocbook.xml %XSL_HOME%\htmlhelp\htmlhelp.xsl htmlhelp.chm=%CHM_OUTPUT_PATH%\tutorialDocbook.chm htmlhelp.hhp=tutorialDocbook.hhp 
hhc.exe tutorialDocbook.hhp
del *.hhp *.hhc *.html

Pour bien se rendre compte de ce qu'il se passe il peut être intéressant de supprimer la dernière ligne, on voit ainsi tous les fichiers générés. A noter les deux paramètres de saxon : "htmlhelp.chm" et "htmlhelp.hhp". Ce sont en fait des paramètres de la feuille de style XSL. On aurait pu modifier directement la feuille de style mais la modification des feuilles de styles n'est pas l'objet de ce document. "htmlhelp.chm" est le nom du fichier qui sera généré par hhc.exe, par défaut c'est justement "htmlhelp.chm". "htmlhelp.hhp" est le nom du fichier projet de HTML Help Workshop, j'ai préféré le changer pour que ce nom n'arrive pas de nulle part. De même par défaut le fichier s'appelera "htmlhelp.hhp"