Format DocBook

Qu'est ce que c'est?

DocBook est une redéfinition du XML. Le XML est un langage à balises qui permet le stockage et le transfert d'information Unicode. DocBook précise le but du langage XML, il part du principe que les données sont de type plutôt documentation technique. C'est le but originel de DocBook, mais il se prête potentiellement à un usage plus diversifié.

Cette citation du Guide pratique: comprendre DocBook résume bien les deux principales qualités de DocBook:

• DocBook offre deux possibilités qui le rendent vraiment intéressant. La première est la production multi-formats et la seconde la réalisation de bases de documents interrogeables.

Cela signifie que DocBook n'est pas un langage de présentation comme le HTML. C'est un langage de sens et de structure des documents. Il permet une très grande liberté dans le choix d'une présentation, choix qui peut être amélioré, redéfini au fil du temps. Il permet aussi de rendre le texte plus intelligible par un moteur de recherche.

Si l'on prend par exemple la phrase «Cube est une œuvre révolutionnaire», un balisage possible sera:

<citetitle>Cube<citetitle> est une œuvre <emphasis>révolutionnaire</emphasis>

Que permet ce balisage?

1. la balise <emphasis> permet la première qualité de DocBook: choisir une apparence pour un texte balisé (on choisira pour cette balise en général de le mettre en italique)

2. Un engin de recherche «comprendra» que Cube est un titre (de film en l'occurrence), et non un cube mathématique ou de glace.

Il est vrai qu'aujourd'hui nous utilisons plus la première qualité de DocBook que la seconde, mais la seconde qualité reste présente et donnera peut être plus tard lieu à des usages intéressants.

Apprendre DocBook

Avant de commencer la traduction d'un article, il faut avoir un savoir fonctionnel de DocBook. Concrètement, un article DocBook se compose d'un certain nombre de balises qui définissent ses composantes immuables (en-tête, biographie de l'auteur...) et d'autres balises qui changent selon le contenu. Il est préférable d'avoir à l'esprit les balises les plus importantes afin de produire un code DocBook correct.

Nous vous recommandons de vous former quelques heures avec les documents suivants:

• Crash-course to DocBook, un guide rapide mais qui donne un bon aperçu général.

• DocBook 5: The Definitive Guide ce guide est exhaustif et il est inutile de tout lire, cependant il est utile comme référence des balises, en liaison avec notre tableau DocBook.

• Le petit guide du traducteur de Traduc explique très bien les concepts du DocBook.

• Nous vous proposons certains articles de la Gazette préformatés en DocBook: http://ftp.traduc.org/projets/gazette-linux/a-traduire/ par un acteur de la Gazette, Frédéric Marchal <fmarchal AT perso DOT be>. Si vous souhaitez traduire l'un de ces articles, le code DocBook est déjà préparé pour vous. Il est intéressant de regarder le code, car il est fait selon les règles de la Gazette.

Enfin, nous avons à la Gazette notre propre ligne directrice concernant le DocBook. Notre emploi du DocBook ne devrait pas dans les faits dépasser l'usage d'une centaine de balises recommandées. Ces balises sont décrites dans ce tableau. Nous vous demandons de bien le lire et de vous y référer lors de l'élaboration de votre article.

Outils DocBook

Un document DocBook n'est pas lisible tel quel mais il peut être converti dans de nombreux formats. Cependant, seul le format HTML nous intéresse pour le moment. Voyons comment produire des fichiers HTML.

Installation des outils

La conversion du DocBook en HTML nécessite quelques outils qui doivent être présents sur votre ordinateur:

1. Un ensemble de règles pour traduire le DocBook en HTML. Nous utilisons les feuilles de style DocBook XSL de Norman Walsh. Ces règles sont disponibles dans le paquet docbook-xsl sous Debian ou docbook-xsl-stylesheets sous Gentoo.

2. Un moteur capable d'appliquer ces règles. Nous recommandons xsltproc disponible dans un paquet du même nom sous Debian et dans libxslt sous Gentoo.

3. Un outil pour vérifier la validité du document DocBook que vous avez préparé. Utilisez xmllint qui se trouve dans le paquet docbook-xsl-stylesheets sous Debian et dans libxml2 sous Gentoo.

4. Une couche supplémentaire pour étoffer la présentation minimaliste par défaut des feuilles de style XSL.

Installez les outils 1 à 3 sur votre ordinateur en utilisant la procédure habituelle pour votre distribution.

Téléchargez les fichiers qui se trouvent dans le répertoire http://ftp.traduc.org/projets/gazette-linux/outils-docbook/ et copiez les dans le répertoire où vous comptez stocker les articles que vous traduirez.

Il y a trois fichiers: gazette.xsl, gazette.css et Makefile.

Utilisation des outils

Supposons que vous avez préparé l'article lg000-A.xml et que vous voulez contempler l'apparence de votre œuvre en HTML. Pour cela, confirmez d'abord que le document DocBook est correctement formaté avec la commande

xmllint --nonet --valid --noout lg000-A.xml

Si des erreurs sont rapportées, corrigez les avant de passer à l'étape suivante.

Si le document est correct, convertissez le avec la commande

xsltproc --path /chemin/vers/docbook/xhtml/ gazette.xsl lg000-A.xml > lg000-A.html

Remplacez le /chemin/vers/docbook/xhtml/ par le chemin où la feuille de style XSL xhtml/docbook.xsl a été installée. Sous Debian, il s'agit de /usr/share/sgml/docbook/stylesheet/xsl/nwalsh/xhtml/. Sous Gentoo, il faut utiliser /usr/share/sgml/docbook/xsl-stylesheets/xhtml.

Le fichier lg000-A.html ainsi produit peut être ouvert dans n'importe quel navigateur.

Pour en savoir plus sur le fonctionnement de cet outil et sur l'utilisation du Makefile, consultez la page décrivant un peu plus en détail l'outil DocBook.

Comme alternative au DocBook existe le HTML et le wiki. Revenir au tutorial Gazette.