Bien.
Alors je commence par rédiger ma documentation en .xml.
Un exemple rapide :
Code : Tout sélectionner
<?xml version="1.0" encoding="utf-8"?>
<book id="ex_de_doc" lang="fr">
<title>Livre très simple</title>
<chapter id="ex_de_chapitre">
<title>Chapitre très court</title>
<para>Bonjour tout le monde !</para>
<para>Ceci est un paragraphe ...</para>
<para>Et ceci est un très long parapjrzozpx kpok efke pkrfpoek pwok poekf
poekfx opefkx epofkx eopfk pok tpok pokgx rgopkc rgopckergopk
erpovkehpegkrxpoerkgcprogk xfkopzk xpeozkfzpeokw
opzekfxeopzfkopwzekfpoekwpeokw</para>
</chapter>
</book>
Ensuite, j'ai besoin de générer vers d'autres formats. Pour cela, on applique des feuilles XSL de
DocBook que l'on peut
télécharger sur le site de DocBook (via sourceforge). Une fois l'archive décompressée, on a une multitude de dossiers portant le nom de différents formats de sorties (Eclipse, FO, HTML, HTMLHelp —
a fortiori CHM —, JavaHelp, ManPages, Slides, Template, Website et XHTML dans sa version 1.73.2). Dans chaque dossier il faut chercher le fichier docbook.xsl qui normalement importe tous les autres fichiers et ainsi lancent la transformation. Si ce fichier n'existe pas, on tente de trouver le fichier qui importe tous les autres (c'est là où c'est joyeux
), mais on le trouve rapidement.
Pour pouvoir appliquer toutes ces transformations, on a besoin d'un processeur XSLT. Une multitude de ces processeurs existe. Sur PHP 5, on a la lib_xslt qui contient DomXml, Sablotron et XsltProc je crois. Mais si vous voulez le faire sans PHP (mon cas pour l'instant), il faut installer un processeur XSLT. Sur les plates-formes Unix et Mac OS (BSD il me semble aussi), vous avez xsltproc déjà installé, donc pratique. Pour Windows j'en ai aucune idée. Il existe Saxon (téléchargeable au même lien que tout à l'heure), qui est un processeur Java. Pas besoin de l'installer, il suffit d'avoir la machine virtuelle Java, et on lance la transformation en appelant le .jar (attention donc à faire
java -jar saxon.jar -s:filename -xsl:filename -o:filename -p:on par exemple). En ce qui concerne XSLT, la commande est beaucoup plus simple :
xsltproc -o <output> <chemin vers les feuilles XSL> <fichier XML DocBook>.
Avec des méthodes, vous pourrez générer tous les formats cités ci-précédent.
Pour avoir des formats d'imprimeries (Tex, PS, DVI, PDF), j'utilise un autre utilitaire qui s'appelle
dblatex (
dblatex via SF). Il existe également db2latex, mais moins puissant, plus lent, enfin bref, moins bien. dblatex supporte plus de langage de sorties. Pas besoin de passer par le format FO. On lui donne le fichier XML, et il se débrouille. La documentation est très clair. Je ne donne qu'un exemple rapide pour lancer une commande :
dblatex -t ps -T simple -o Output.ps Test.xml, ceci va prendre le fichier Test.xml et le transformer en Output.ps avec le style (-T) simple. Par défaut il utilise le rendu de db2latex, mais il est pas si beau que ça. Le style
simple se rapproche du rendu Latex. Si on veut générer un fichier Latex, ça se fait de la même façon. En revanche pour générer les DVI, PS et PDF depuis Latex (via Texmaker, TexLive etc.) il faut avoir la bibliothèque docbook.sty. Je n'ai pas encore essayé depuis Tex, mais j'ai juste remarqué ça en lisant la source.
L'avantage est immédiat : on peut générer des maths depuis DocBook. Très pratique.
Pour utiliser dblatex, il faut lancer un petit script python qui va lancer l'installation :
python ./install.py dans le dossier de dblatex.
Voilà, avec ça, on sort vers tous les formats. Ah oui, pour avoir le format d'aide Windows (CHM), DocBook génère un fichier HHP, que l'on doit ensuite compilé sur Windows avec l'utilitaire Windows. Cet utilitaire s'appelle hhc.exe et fait partie de la suite de développement Microsoft HTML Help SDK. Donc utilitaire gratuit et téléchargeable partout sur Internet.
Moi ce que m'embêtait, c'était de ne pas pouvoir ajouter un suffixe au titre des pages HTML par exemple.
Voici l'astuce.
On commence par créer son fichier XSL qui va lancer les fichiers DocBook, mais on va ajouter nos petites transformations à nous. Donc le fichier commence par :
Code : Tout sélectionner
<?xml version="1.0" encoding="utf-8"?>
<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" version="1.0">
<xsl:import href="/UsersOfPHPFrance/Hywan/docbook/xsl-stylesheets/xhtml/chunk.xsl" />
On n'oubliera pas de fermer de </xsl:stylesheet> à la fin du fichier.
Puis, pour modifier le titre :
Code : Tout sélectionner
<xsl:template name="head.content">
<xsl:param name="node" select="." />
<xsl:param name="title">
<xsl:apply-templates select="$node" mode="object.title.markup.textonly" />
</xsl:param>
<title>
<xsl:copy-of select="$title" />
<xsl:text> — Le suffixe de mon titre !</xsl:text>
</title>
</xsl:template>
Ceci ajoutera " — Le suffixe de mon titre !" à chaque page (livre, ou découpé).
Si jamais on veut ajouter du code en début de fichier, il faut appeler la template
user.header.navigation, pour la fin du fichier :
user.footer.navigation, pour le head :
user.head.content etc. On trouve tout ça en fouillant dans les diverses documentations.
Les liens utiles :
Voili voilou, j'espère que ça aidera quelqu'un un jours
. Je n'ai mis que quelques modifications pour transformer la sortie HTML, mon fichier est bien plus gros que ça. Mais je laisse le soin aux lecteurs de programmer comme bon leur semble
.
.