Introduction à DocBook sous Linux

Parce qu\’il n\’y a pas que le LaTeX pour écrire de bons documents, je vais vous présenter rapidement les bases de DocBook 5.0. Mais d\’abord, qu\’est-ce que DocBook?

DocBook

DocBook peut se résumer dans un premier temps à un schéma XML définissant un standard de création de documents (concrètement un DTD, un XSD, …). Il offre un grand nombre de balises pour écrire un document. C\’est un \ »format\ » très utilisé pour les documentations de projets open-source par exemple. Par abus de langage, nous parlerons de \ »fichier DocBook\ » durant le reste de cet article pour parler d\’un fichier XML écrit en suivant le schéma DocBook.

Du fait qu\’il soit standardisé, un même fichier DocBook peut servir de base à plein de rendu différents (HTML, PDF, …).

Enfin, à la base de DocBook, il y a le célèbre éditeur d\’ouvrages consacrés à l\’informatique : O\’Reilly (qui a malheureusement mis la clé sous la porte…).

Créer son premier document

Nous allons donc créer notre premier document à base de DocBook. Pour commencer, il faut installer le paquet suivant :

$ sudo apt-get install docbook-xsl-ns

Ce paquet ajoute des fichiers XSL qui sont des feuilles de style pour document XML. Elles permettent, à partir d\’un fichier basé sur DocBook, de lui appliquer un style pour un rendu spécifique. C\’est en quelque sorte le même principe que le CSS appliqué au HTML.

Dans un premier temps, nous allons écrire un fichier XML, essai.xml, basé sur le schéma DocBook.

<?xml version=\"1.0\" encoding=\"UTF-8\"?>
 <article version=\"5.0\" xmlns=\"http://docbook.org/ns/docbook\">
   <title>Premier document DocBook</title>
   <articleinfo>
     <author>
       <firstname>John</firstname>
       <surname>Doe</surname>
     </author>
     <copyright>
       <year>2010</year>
       <holder>One More Blog</holder>
     </copyright>
   </articleinfo>
   <sect1>
      <title>Section de premier niveau</title>
      <para>
        Ce texte est dans un paragraphe.
      </para>
      <itemizedlist>
        <listitem>
          premier item d\'une liste;
        </listitem>
        <listitem>
          et le second item.
        </listitem>
      </itemizedlist>
   </sect1>
 </article>

Les noms des balises font que le code est très compréhensible et, du coup, rapide à intégrer. Ce petit morceau de code n\’est qu\’un aperçu minime de ce qu\’il est possible de faire avec DocBook. Bref, nous allons maintenant appliquer à ce fichier un style afin de créer un rendu. En HTML d\’abord, puis en PDF.

$ xsltproc -o essai.html /usr/share/xml/docbook/stylesheet/docbook-xsl-ns/xhtml/docbook.xsl essai.xml

La syntaxe est très simple. On spécifie le nom du fichier en sortie grâce à l\’option -o. On donne ensuite une feuille de style XSL et le fichier XML en entrée. Le résultat est le suivant :

Un peu comme en LaTeX, tout est géré. Une table des matières est générée en fonction des sections et sous-sections avec les liens qui vont bien. Des id et class sont ajoutés à toutes les balises HTML de façon à éventuellement rajouter une feuille de style, …

Nous allons maintenant, à partir du même code XML, générer une version PDF de ce DocBook. Cependant, cela nécessite l\’installation de quelques outils supplémentaires. Dans un premier temps, nous allons ajouter les feuilles de styles prévue pour le PDF :

$ sudo apt-get install docbook-xsl-doc-pdf

Il nous faut ensuite récupérer l\’utilitaire FOP (Formatting Objects Processor). Il s\’agit d\’un programme écrit en Java qui permet de générer entre autres des fichiers PDF à partir de XML et XSD. Cet utilitaire est présent dans les dépôts d\’Ubuntu – et des autres distributions j\’imagine – mais dans sa version 0.95. Or, est sortie depuis quelques mois une version 1.0 plus aboutie. Nous allons donc récupérer cette version et y ajouter une librairie, Offo, qui gère les découpages de mot (hyphenation ou trait d\’union si fin de ligne) et qui évitera des erreurs lors de la génération du document.

$ wget http://apache.crihan.fr/dist//xmlgraphics/fop/binaries/fop-1.0-bin.tar.gz
$ tar -xvzf fop-1.0-bin.tar.gz
$ cd fop-1.0/
$ wget http://freefr.dl.sourceforge.net/project/offo/offo-hyphenation/1.2/offo-hyphenation-fop-stable_v1.2.zip
$ unzip offo-hyphenation-fop-stable_v1.2.zip
$ cp offo-hyphenation-fop-stable/fop-hyph.jar lib/

Lançons maintenant la création de notre document PDF :

$ ./fop -xml ../essai.xml -xsl /usr/share/xml/docbook/stylesheet/docbook-xsl-ns/fo/docbook.xsl -pdf ../essai.pdf

Là encore c\’est très simple. L\’option -xml doit être suivie du fichier DocBook, l\’option -xsl d\’une feuille de style spécifique au PDF et enfin la dernière option défini le fichier en sortie. Le résultat est très satisfaisant :

Ce n\’est là qu\’un tout petit aperçu de ce qu\’il est possible de faire avec DocBook. Comme pour LaTeX, il existe plusieurs classes (ici nous avons testé la classe article) pour différents usages. Je vous laisse fouiller un peu et trouver votre bonheur dans la documentation. Je vous propose quelques sites intéressants qui d\’une part m\’ont aidé à écrire ce premier article sur le sujet et qui d\’autre part proposent de la documentation de qualité pour approfondir tout ça :

• Site officiel de DocBook
• Une présentation rapide de DocBook
• Documentation sur le site d\’Ubuntu
• Guide complet de DocBook
• Un listing de tutoriels disponibles sur le sujet