Table des matières
Il existe plusieurs façon de travailler avec Docbook :
La première, qui ne sera pas décrite ici, utilise certains logiciels de traitement de texte comme OpenOffice.org ou Abiword.
Les autres consitent à utiliser un éditeur de texte plus ou moins spécialisé pour le xml, et utiliser ensuite des outils de conversion. Ces outils utilisent des feuilles de style pour faire les conversions et l'on distingue principalement deux familles : les feuilles de style DSSSL, utilisées par Jade et Openjade, et les feuilles de style XSL utilisées par divers processeurs XSLT (xsltproc , Xalan, etc ...).
Cette méthode utilise les feuilles de style XSLT. C'est la méthode privilégiée à l'heure actuelle, car la plus rapide et la plus simple à mettre en oeuvre.
Selon les distributions, les noms peuvent varier un peu, mais sous Debian on installera particulierement (avec leurs dépendances) :
docbook-xml
libxml2-utils (pour xmllint)
xsltproc
On peut commencer par tester la validité du document :
[furax@localtux]$ xmllint --noout --valid docbook.dbk.xml
Si rien ne s'affiche, le document est valide : c'est à dire que le document respecte les rêgles d'écriture d'XML et que l'organisation des balises et des données respecte la DTD.
Il ne reste plus qu'Ã compiler ce document en utilisant la feuille de style docbook.xsl :
[furax@localtux]$ xsltproc --timing -o docbook.html /usr/share/xml/docbook/stylesheet/nwalsh/xhtml/docbook.xsl docbook.dbk.xml
Ceci va vous générer dans le répertoire courant un fichier docbook.html.
L'option --timing permet d'afficher les temps d'execution et est complètement facultative.
L'option --nonet empèche xsltproc d'aller chercher la DTD sur Internet.
La commande xsltproc effectue une validation XML simple, mais ne vérifie pas la validité par raport à la DTD (comme xmllint).
Ou encore en utilisant la feuille de style chunk.xsl ::
[furax@localtux]$ xsltproc --timing /usr/share/xml/docbook/stylesheet/nwalsh/xhtml/chunk.xsl docbook.dbk.xml
Ceci va vous générer dans le répertoire courant plusieurs fichiers html de type ch02s02.html.
Pour mettre les pages html dans le répertoire ./html et utiliser une feuille de style personnalisée (docbook.xsl) :
[furax@localtux]$ xsltproc --timing --nonet -stringparam base.dir html/ docbook.xsl docbook.dbk.xml
L'utilisation des feuilles de style XSL personnalisées sera décrite à la section intitulée « La feuille de style XSLT ».
Tous les outils défini dans la section précédante existent dans la collection d'outils Cygwin pour Windows.
Cette méthode utilise les feuilles de style DSSSL. C'est la méthode historique, mais ça n'est plus la méthode privilégiée à l'heure actuelle.
L'installation sous Windows n'est pas tout à fait simple, mais voici la marche à suivre.
Cette note est extraite de la documentation originale et n'est peut-être plus à jour.
Tout d'abord, il faut récupérer les packages suivants :
Décompressez l'archive de Jade dans C:\jade par exemple, puis décompressez Docbook dans c:\sgml\Docbook\. On continue avec les feuilles de style dans c:\Docbook, et on fini par les iso-entities dans c:\sgml\Docbook (donc le même répertoire sur Docbook).
Il faut ensuite se placer sous un shell DOS et placer quelques variables d'environement :
C:\> PATH=%PATH%;c:\jade C:\> set SGML_CATALOG_FILES=c:\sgml\Docbook\Docbook.cat;c:\jade\catalog
Ensuite on peut se lancer et faire un essai avec xxxxxxxxxxx :
C:\> jade -t rtf -d c:\Docbook\print\Docbook.dsl test.sgm
Vous pouvez maintenant apprendre à faire des documents au format Docbook.
Selon les distributions, les noms peuvent varier un peu, mais sous Debian on installera particulierement (avec leurs dépendances) :
docbook
docbook-dsssl
openjade
jadetex
Le dernier package sert uniquement à faire des fichiers LateX avec OpenJade.
Après avoir instalé tous les packages avec le gestionnaire de votre choix (apt, urpmi, yum, etc ...). C'est pour ainsi dire terminé ...
Il ne reste plus qu'Ã essayer en compilant par exemple la source de ce document :
[furax@localtux]$ openjade -G -t rtf -i html -E 5 -d /usr/share/sgml/docbook/stylesheet/dsssl/modular/print/docbook.dsl -c /etc/sgml/docbook-xml.cat -o docbook.rtf /usr/share/sgml/declaration/xml.dcl docbook.dbk.xml
Les problèmes les plus courants sont dus au catalogue ou à l'en-tête du fichier sgml. Si vous avez eu des problèmes à partir du fichier test.sgm dans le style :
jade:test.dsl:1:72:W: cannot generate system identifier for public text "-//James Clark//DTD DSSSL Style Sheet//EN"
Dans ce cas, il faut vérifier que votre variable SGML_CATALOG_FILES est bien défine. Attention, le séparateur pour DOS est le point-virgule (;) alors que sous Linux c'est le double point (:). Une erreur courante (et ça m'est arrivé) est de mettre le nom du répertoire qui contient le fichier catalog à la place du fichier lui-même dans la variable SGML_CATALOG_FILES.
Les avertissements concernant DTDDECL (non supporté) ne sont pas très importants et peuvent être ignorés.