Sylvain Tertois 19 juillet 2003 1.0 31 octobre 2002 Première version 1.1 19 juillet 2003 compléments d'information sur les problèmes mémoire (), création d'une nouvelle section sur les différents soucis rencontrés ().

Cet article présente comment avoir un environnement de travail confortable pour écrire des documents en DocBook, et comment les exporter en divers formats, surtout PDF et HTML. Cet article présente l'installation et l'utilisation des différents produits sous Windows, et à la fin je parle aussi de l'installation sous FreeBSD. On peut parfaitement l'utiliser avec un autre Unix, étant donné que tous les outils utilisés sont soit en java, soit open source avec des versions pour la plupart des Unix. Ce document est écrit en utilisant cet environnement, en format DocBook, et peut être récupéré dans les formats DocBook, PDF, et HTML sur le site . Je tiens à préciser que ce document décrit ce qui est à mon avis un environnement simple, confortable et utilisable à la date d'écriture. Bien sûr tout le monde ne sera pas de mon avis, donc les outils que je propose ici ne sont pas forcément ceux qui vous conviendront.

De nombreux éditeurs existent pour les documents XML, mais la plupart sont orientés structure. C'est à dire qu'ils présentent le fichier XML sous forme d'arbre, auquel on peut ajouter des éléments, définir les attributs etc... Le texte est présenté et utilisé comme un élément, ce qui rend peu pratique l'utilisation de tels outils pour éditer un document contenant essentiellement du texte, ce qui est le cas d'un fichier DocBook. Ensuite certains éditeurs de texte, comme Emacs, proposent de gérer les balises XML en fonction de la DTD. Ceci permet d'éditer facilement des fichiers DocBook, tout en étant sûr de générer un document XML bien formé, et en général valide. Par contre on édite forcément au niveau source XML. L'outil que j'ai finalement retenu ici est XXE (XMLMind XML Edit), qui a l'avantage de fonctionner de la même manière qu'un traitement de texte, c'est à dire en pseudo-wysiwyg. Les balises XML sont cachées (mais quand même accessibles) ce qui est appréciable pour du DocBook qui a tendance à multiplier le nombre de balises. Enfin il comprend des dictionnaires anglais et français, et on peut ajouter de nombreux autres langages. Voici une copie d'écran pour se faire une idée du logiciel:

XXE nécessite une machine virtuelle java pour fonctionner, et il est fortement conseillé de prendre celle de Sun, avec une version au moins égale à la 1.4_01. Effectivement chez moi ça ne marche pas avec la version 1.3. Donc si votre machine java n'est pas à jour, ou si vous n'en avez pas, commencez par la télécharger sur le site de Sun: allez sur , puis suivez les liens Downloads, J2SE 1.4 - All Platforms dans la partie Java™ 2 Platform, Standard Edition (J2SETM), puis Windows - all languages - JRE. Une fois le fichier téléchargé, installez la machine Java. Ensuite il faut installer l'éditeur, qu'on peut trouver à . Pour Windows, il existe une version auto-installable qui installe tous les fichiers et crée les raccourcis dans le menu démarrer. Ensuite vous pouvez lancer XXE et éditer vos documents DocBook. N'oubliez pas de faire le tutoriel sur le site de XMLMind, il permet de se familiariser avec le logiciel et surtout de comprendre les différences avec un traitement de texte classique.

Les deux transformations qui seront sans doute le plus utilisés avec DocBook vont être abordées ici: on va regarder comment générer un document PDF et des pages HTML à partir d'un fichier DocBook. Il va falloir tout d'abord télécharger des fichiers de transformation XSLT et quelques outils.

De bons fichiers XSL pour DocBook sont disponibles sur le site . Il faut prendre le fichier docbook-xsl, et la documentation est incluse dans l'archive téléchargée. J'utilise la version 1.54.1, et je conseille de prendre au moins celle-là, étant donné que certaines versions antérieures ont quelques problèmes avec PassiveTeX. Ensuite il faut un processeur XSLT. Un des processeurs conseillés par les auteurs des fichiers XSL, et qui fonctionne à la fois sous Windows et Unix, est xsltproc. Il fonctionne bien, est rapide et supporte quelques extensions exslt qui peuvent être utiles (exslt:document notamment). On peut le télécharger pour Windows ici: . Il faut télécharger libxml, libxslt et xsltproc. Dézippez les trois archives dans le même dossier, et mettez le chemin de ce dossier dans le PATH pour que Windows puisse retrouver l'exécutable et les bibliothèques nécessaires pour faire une transformation xsl. Pour vérifier que tout fonctionne bien, ouvrez une fenêtre DOS, dans un répertoire autre que celui dans lequel est installé xsltproc, et tapez xsltproc. Il ne devrait pas y avoir d'erreur, et xsltproc devrait donner la liste des options disponibles. Pour éviter que xsltproc charge systématiquement la dtd sur internet, vous pouvez utiliser un fichier catalogue, qui contient la liste des identifieurs PUBLIC que vous utilisez dans les documents xml et un fichier dtd stocké en local sur votre machine. Vous pouvez par exemple vous inspirer du fichier catalogue de XXE (le fichier catalog.xml dans le répertoire config). Il faudra sans doute changer les chemins relatifs dans le catalogue, puisqu'ils doivent être relatifs au répertoire de travail de xsltproc, donc celui de vos documents docbook. Une fois le fichier de catalogue créé, il faut créer une variable d'environnement (panneau de configuration, système, environnement) qui s'appelle XML_CATALOG_FILES et qui contient le chemin vers le fichier de catalogue.

Les fichiers xsl sont rangés dans différents dossiers suivant leur utilisation. On va surtout s'intéresser aux dossiers html et fo. Dans le dossier html se trouvent les xsl qui vont générer des fichiers html. Les deux que l'on va utiliser sont html/docbook.xsl et html/chunk.xsl. docbook.xsl crée un grand fichier html qui contient tout le document DocBook en une fois, tant dis que chunk.xsl va créer plusieurs petits fichiers, un par chapitre en général. chunk.xsl nécessite l'utilisation d'un processeur XSLT qui reconnaît l'extension exslt:document, ce qui est le cas de xsltproc. Dans le dossier fo le fichier fo/docbook.xsl permet de générer un fichier au format xsl-fo, ce qui permettra de générer un fichier PDF. Ces fichiers XSL sont largement personnalisables, et sont contrôlés par une série de paramètres. On peut préciser la valeur des paramètres que l'on veut redéfinir sur la ligne de commande du processeur xslt, mais à la longue c'est beaucoup plus simple de les préciser dans son propre fichier xsl, en utilisant la fonctionnalité xsl:import. En effet on appliquera au fichier docbook son propre fichier xsl, qui fera appel aux fichiers xsl cités précédemment. Dans notre fichier xsl, on peut donner la valeur qu'on veut aux différents paramètres. Voici par exemple un fichier xsl qui permet de produire un document xsl-fo avec les extensions pour PassiveTeX, les équations au format LateX, et une sortie avec indentation pour pouvoir lire soi-même le fichier fo: <?xml version="1.0"?> <xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" version="1.0"> <!-- importation de la transformation docbook en fo--> <xsl:import href="file://E:/docbook-xsl/fo/docbook.xsl"/> <!-- sortie indentée --> <xsl:output method="xml" indent="yes" encoding="iso-8859-1"/> <!-- extensions PassiveTeX --> <xsl:param name="tex.math.in.alt" select="'latex'"/> <xsl:param name="passivetex.extensions" select="1"/> </xsl:stylesheet> J'ai utilisé un chemin absolu pour le fichier xsl importé, ce qui me permet d'utiliser ce fichier xsl n'importe où sur mon disque. Avec les fichiers xsl il y a une documentation qui contient tous les paramètres avec une petite explication sur ce qu'ils font et quelle valeur ils ont par défaut.

Commencez par faire votre fichier xsl, comme ci-dessus, en important au choix le fichier html/docbook.xsl pour créer une grande page html, ou le fichier html/chunk.xsl pour créer plusieurs petites pages. Dans ce dernier cas, le paramètre chunk.section.depth permet de régler la profondeur de la découpe (le niveau d'imbrication au bout duquel on place le contenu dans un nouveau fichier) et le paramètre chunk.first.sections permet de dire si l'on veut que la première section soit sur la même page que le sommaire ou sur une page séparée. Voici par exemple le fichier xsl qui a servi à changer ce document en ensemble de pages html (vous aurez sans doute besoin de changer le chemin absolu vers le fichier xsl): <?xml version="1.0" encoding="iso-8859-1"?> <xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" version="1.0"> <xsl:import href="../xsl/html/chunk.xsl"/> <!-- caractéristiques des pages html générées --> <xsl:param name="chunker.output.indent" select="'yes'"/> <xsl:param name="chunker.output.doctype-public" select="'-//W3C//DTD HTML 4.01 Transitional//EN'"/> <xsl:param name="html.stylesheet" select="'style.css'"/> <!-- extensions passivetex --> <xsl:param name="tex.math.in.alt" select="'latex'"/> <xsl:param name="passivetex.extensions" select="1"/> <!-- pas de svg en sortie --> <xsl:param name="use.svg" select="0"/> <!-- numérotation des sections --> <xsl:param name="section.autolabel" select="1"/> <!-- table des matières sur une page séparée --> <xsl:param name="chunk.first.sections" select="1"/> </xsl:stylesheet> Ensuite utilisez xsltproc pour faire la transformation. Si vous créez plusieurs fichiers html (si vous passez par html/chunk.xsl, donc) vous n'avez pas besoin de rediriger la sortie. Une commande comme ceci, dans une fenêtre DOS dans le répertoire du fichier docbook fonctionnera: xslrproc mon_fichier_transform.xsl mon_fichier_docbook.xml Et une série de fichiers html sera générée. Si vous créez un seul fichier html (donc en passant par html/docbook.xsl), vous devez rediriger la sortie vers le fichier de destination: xsltproc mon_fichier_transform.xsl mon_fichier_docbook.xml > ma_sortie.html

Pour transformer un fichier fo en fichier pdf, un des moyens existants est PassiveTeX. Pour cela il faut tout d'abord installer TeX, et je conseille sous Windows la distribution MikTeX, qu'on peut trouver ici: . En plus de l'installation de base, il faudra installer les packages xmltex et passivetex. Vérifiez ensuite la version de passivetex que vous avez, parce que chez moi les versions antérieures à la 32 de fotex.xmt avaient quelques problèmes. Pour connaître le numéro de version, allez voir le début du fichier C:\texmf\tex\xmltex\passivetex\fotex.xmt (en supposant que mixTeX soit installé dans C:\texmf). Vous devriez avoir quelque chose comme ça: % $Id: docbook.xml,v 1.1.1.1 2003/06/19 12:53:31 daixiwen Exp $, $Date: 2003/06/19 12:53:31 $ Ce qui est important c'est le numéro après le #. S'il est inférieur à 32, il faudrait mettre passivetex à jour. Malheureusement MikTeX n'évolue pas aussi rapidement que PassiveTeX, donc il faudra peut-être faire la mise à jour manuellement. Téléchargez la dernière version de PassiveTeX sur ce site: , et décomprimez l'archive pour remplacer le contenu du répertoire passivetex (normalement C:\texmf\tex\xmltex\passivetex).

Tout d'abord il faut utiliser les fichiers xsl pour créer un fo à partir de votre document DocBook. Pour cela je conseille d'utiliser votre propre xsl, comme dans l'exemple en début de chapitre. Il est intéressent de mettre le paramètre passivetex.extensions à 1, pour avoir les signets et les liens hypertexte dans le pdf produit. Ensuite, appliquez la transformation avec xsltproc: xsltproc mon_fichier_transform.xsl mon_fichier_docbook.xml > ma_sortie.fo Ensuite utilisez TeX pour produire le PDF: pdfxmltex ma_sortie.fo Il faudra exécuter deux fois cette commande pour que le PDF soit complet, avec les signets et les liens hypertexte correctement placés. Le résultat sera placé dans un fichier PDF qui a le même nom que le fichier fo d'origine (donc ici ma_sortie.pdf).

Le sujet est tellement compliqué que je lui ai donné un chapitre entier!

Deux moyens de décrire des équations peuvent être utilisés. LateX est le format historique, assez simple à utiliser et lisible, mais il est peut-être destiné à disparaître devant MathML, qui est le nouveau standard XML pour décrire les équations. Cependant MathML a encore quelques défauts. Tout d'abord pour les documents HTML MathML n'est reconnu que par les browsers Amaya et Mozilla, ce qui limite un peu l'audience. Des plug-ins existent pour Internet Explorer mais sont soit expérimentaux soit payants. De plus il n'existe pas d'éditeurs MathML complets et peu chers. Éditer du MathML à la main est vraiment trop compliqué. C'est pourquoi je pense que pour l'instant il vaut mieux utiliser des équations au format LateX.

Pour utiliser des équations au format LateX, il faut préciser dans les balises inlinemediaobject ou mediaobject deux formes pour l'équation: un fichier image et un texte au format TeX. Par exemple voici le code pour mettre cette équation: E=mc^2 <equation> <title>Loi de la relativité générale</title> <alt role="tex">E=mc^2</alt> <graphic fileref="emc2.gif"/> </equation> L'attribut role="tex" précise que l'équation est au format LateX. On utilisera la même méthode pour les équations en ligne.

Vu que c'est LateX qui va produire le fichier PDF, il n'y aura pas de problèmes avec les équations. Il faut juste penser à mettre les paramètres passivetex.extensions à 1 et tex.math.in.alt à "latex" dans votre fichier xsl. (Voir l'exemple du chapitre précédent).

Le seul moyen que j'ai trouvé pour faire une sortie HTML propre c'est l'utilitaire dvi2bitmap, mais sous Windows c'est très compliqué à utiliser parce qu'il ne fait pas partie du kit MikTeX et qu'il n'est pas du tout fait pour fonctionner sous Windows! Si quelqu'un à une méthode plus simple je suis preneur...

Vous aurez besoin des sources de dvi2bitmap, qu'on peut trouver ici: . Pour le compiler, il faut installer le kit Cygwin () avec les modules make et gcc. Ensuite pour compiler dvi2bitmap ouvrez une fenêtre shell Cygwin, allez dans le répertoire des sources de dvi2bitmap, et tapez: configure --without-kpathsea --disable-mktexpf --enable-maketexpk=makepk --enable-gif puis make Ceci va créer un exécutable dvi2bitmap que vous pouvez déplacer dans le dossier /usr/bin de Cygwin. Enfin vous devez ajouter cette ligne dans votre profil Cygwin (le fichier .profile dans votre répertoire home): export DVI2BITMAP_PK_PATH="/cygdrive/c/localtexmf/fonts/pk/ibmvga/public/cm A condition que votre répertoire local pour tex soit C:\localtexmf bien sûr.

Vous devez obligatoirement passer par le fichier xsl chunk.xsl, et plus par docbook.xsl. Il faut préciser en plus dans votre fichier xsl les deux paramètres passivetex.extensions à 1 et tex.math.in.alt à "latex". Ensuite vous créez vos documents comme d'habitude avec xsltproc, et vous verrez un fichier supplémentaire qui a été créé, tex-math-equations.tex. Exécutez ces deux commandes, sous Cygwin: latex tex-math-equations.tex dvi2bitmap tex-math-equations.dvi Et ceci va créer toutes vos équations sous forme d'images pour vos pages html.

Il y a encore un problème qui me gène beaucoup, et que je ne sais toujours pas comment résoudre: dvi2bitmap et MikTeX n'utilisant pas la même convention pour nommer les fichiers de police, ce qui fait que dvi2bitmap n'arrive pas à trouver les polices qu'il a demandé de générer. Donc au premier lancement de dvi2bitmap, vous aurez un message d'erreur disant qu'il ne trouve pas la police. Le problème vient en fait que MikTeX place les polices générées dans un répertoire pour chaque résolution, alors que dvi2bitmap s'attend à avoir toutes les résolutions au même endroit, avec la résolution dans le nom du fichier. Par exemple ce qui est pour MikTeX /cygdrive/c/localtexmf/fonts/pk/ibmvga/public/cm/100dpi/cmr10.pk sera pour dvi2bitmap /cygdrive/c/fonts/pk/ibmvga/public/cm/cmr10.110pk. La rustine temporaire que j'ai trouvée pour mettre tout le monde d'accord est de créer des liens symboliques entre les anciens et les nouveaux noms. Avec Cygwin placez-vous dans le répertoire /cygdrive/c/fonts/pk/ibmvga/public/cm et tapez les commandes suivantes: ln -s /cygdrive/c/fonts/pk/ibmvga/public/cm/100dpi/cmr10.pk cmr10.110pk ln -s /cygdrive/c/fonts/pk/ibmvga/public/cm/100dpi/cmmi10.pk cmmi10.110pk ln -s /cygdrive/c/fonts/pk/ibmvga/public/cm/100dpi/cmr7.pk cmr7.110pk Ensuite si vous relancez dvi2bitmap ça devrait marcher. S'il a besoin d'autres polices il faudra faire la même manipulation.

Tous les logiciels cités ci-dessus sont également disponibles pour FreeBSD. En voici la liste et quelques notes sur l'installation et l'utilisation.

Il faudra tout d'abord la machine java de Sun. Sun n'a pas compilé sa machine java pour FreeBSD, mais on peut installer la version linux et utiliser la couche de compatibilité de FreeBSD. Pour cela, il faut d'abord télécharger le kit Java 1.4 SDK pour linux, ici: , puis mettre le fichier téléchargé dans le répertoire /usr/ports/distfiles. Ensuite tapez dans un terminal en tant que root: cd /usr/ports/java/linux-sun-jdk14 make make install make clean ln -s /usr/local/bin/javavm /usr/local/bin/java Je ne sais pas pourquoi le port java ne place pas directement un exécutable java, mais en créant le lien comme indiqué en dernière ligne ça marche. Ensuite il faut télécharger XXE ici: et décomprimer l'archive dans un répertoire, de préférence dans la hiérarchie /usr/local. (/usr/local/apps/xxe par exemple). On pourra lancer XXE en utilisant le script xxe présent dans le répertoire principal de l'application.

On peut également installer xsltproc, toujours en exécutant en tant que root: cd /usr/ports/textproc/libxslt make make install make clean Les mêmes commandes xsltproc que sous Windows peuvent être utilisées. Pour utiliser un catalogue, il faut comme sous Windows déclarer une variable globale XML_CATALOG_FILES.

Les archives de passivetex et xmltex n'ont pas de numéros de version, et les installations automatiques des ports correspondants sur les BSD ne marcheront que s'ils correspondent exactement à la version disponible au moment de l'installation sur le site de TEI. Donc vous pouvez tenter l'installation automatique, et si ça ne marche pas, faire l'installation manuelle décrite dans le paragraphe suivant. Pour installer teTeX, xmltex et passivetex, exécutez en tant que root: cd /usr/ports/print/passivetex make make install make clean

Tout d'abord on va installer teTeX. Exécutez en tant que root: cd /usr/ports/print/teTeX make make install make clean Ensuite il faut télécharger les archives de xmltex et passivetex sur le site de TEI, ici: . Créer un dossier /usr/local/texmf/tex/xmltex et décomprimer les archives base (xmltex) et passivetex dedans. Ensuite il y a quelques actions a faire pour créer les fichiers de format et les exécutables correspondants: cd /usr/local/share/texmf/web2c texconfig rehash tex -ini -progname=xmltex "&latex" xmltex.ini pdftex -ini -progname=pdfxmltex "&pdflatex" pdfxmltex.ini texconfig rehash ln -s /usr/local/bin/tex /usr/local/bin/xmltex ln -s /usr/local/bin/pdftex /usr/local/bin/pdfxmltex

Il se peut que lors du traitement d'un fichier fo TeX se plaigne de ne pas avoir assez de mémoire. Par exemple avec un message d'erreur comme ceci: ! TeX capacity exceeded, sorry [save size=8000]. <to be read again> Dans ce cas il faut augmenter le buffer correspondant dans le fichier /usr/local/share/texmf/web2c/texmf.cnf. Ici TeX dit que c'est le buffer save qui est trop petit, il faut donc augmenter les variables save_size et save_size.context. Il y a aussi les variables hash_extra pour la table hash, etc... Voici la liste des variables que j'ai modifiées et leur nouvelle valeur: main_memory.context = 3000000 main_memory = 1500000 hash_extra.context = 25000 hash_extra = 25000 pool_size.context = 1500000 pool_size = 1000000 string_vacancies.context = 90000 string_vacancies = 50000 max_strings.context = 200000 max_strings = 60000 save_size.context = 20000 save_size = 16000 Attention, après avoir modifié certaines valeurs (main_memory surtout), il faut regénérer les fichiers de format pour qu'elles soient prises en compte. Pour les formats de base (LaTeX...) on peut faire: fmtutil --all Et pour les formats créés vous-même (xmltex et pdfmltex) il suffit de retaper les commandes de création (). Quand vous créez un fichier .pdf, TeX crée aussi un fichier .log avec des messages sur ce qu'il a fait. A la fin de ce fichier, il indique la taille des différents buffers et quelle partie a été utilisée. Ceci peut permettre de vérifier que les changements ont bien été pris en compte, et de prévoir s'il y aura un risque de saturation d'un des tampons mémoire.

dvi2bitmap ne sera indispensable que si vous voulez insérer des équations au format TeX et que vous voulez une sortie HTML. Pour cela il faut d'abord charger les sources sur le site . Ensuite en tant que root, on va décomprimer l'archive et installer le programme. Allez dans le répertoire dans lequel l'archive a été décomprimée, et tapez: ./configure make --enable-gif --enable-png make test mv dvi2bitmap /usr/local/bin La commande make test va vous donner entre autres le chemin vers les polices que dvi2bitmap utilise. Ensuite s'il ne les trouve pas tout seul, il faudra mettre ce chemin dans la variable d'environnement DVI2BITMAP_PK_PATH.

J'ai rencontré quelques soucis en utilisant cette méthode, que je vais tenter de résumer ici.

Comme indiqué en section , j'ai rencontré des problèmes de taille de tampons mémoire. L'explication et la résolution se trouvent dans la section Unix parce que je n'ai pas rencontré ce problème avec la version Windows et donc je ne peux pas la garantir pour Windows non plus.

PassiveTeX souffre encore de quelques bugs, qui devraient être résolus dans les versions suivantes. La version de mars 2003 a encore quelques problèmes avec les entêtes et pieds de page générés par les xsl docbook. Je donnerai plus de détails ici quand ils seront résolus.

Certains éléments DocBook ne sont pas ou mal gérés par les xsl (par exemple les bibliographies). Dans ce cas il faut tout simplement ajouter ses propres templates et donc faire un peu de xsl:fo. Après la publication de ma thèse je donnerai ici quelques templates que j'ai créés afin de montrer comment faire.

Voilà j'espère que ceci vous aidera à faire du DocBook sur votre ordinateur. Certaines choses doivent encore être améliorées (je ne suis pas du tout satisfait du bricolage à la ficelle et au scotch pour dvi2bitmap sous Windows par exemple) mais ceci permet déjà d'écrire de nombreux documents et de les exporter. Tout commentaire ou suggestion est bien sûr le bienvenu! Envoyez-les à these@becoz.org.