6. Trucs et astuces pour DocBook

6.1. Inclure des images

Contrairement à LinuxDoc, DocBook permet d'inclure des images dans votre HOWTO. Voici un exemple :

<figure> <title>LyX screen shot</title>
  <mediaobject>
    <imageobject>
      <imagedata fileref="lyx_screenshot.eps" format="eps">
    </imageobject>
    <imageobject>
      <imagedata fileref="lyx_screenshot.jpg" format="jpg">
    </imageobject>
    <textobject>
      <phrase> Screen shot of the LyX document 
                     processing program
      </phrase>
    </textobject>
  </mediaobject>
</figure>

Il est préférable d'utiliser cette technique plutôt que la balise <graphic> pour deux raisons. Premièrement, la balise <graphic> ne sera plus disponible avec DocBook 5.0. Il faudra utiliser <mediaobject>. Donc, autant utiliser dès maintenant la bonne méthode. Deuxièmement, <mediaobject> permet de définir plusieurs types d'objets suivant le format dans lequel sera converti le document. Dans cet exemple, le premier <imageobject> est un fichier PostScript encapsulé (EPS) à utiliser pour les sorties basées sur TeX, comme DVI, PS et PDF. Le second <imageobject> est une image JPEG principalement utilisée pour HTML. La balise <textobject> ne sera utilisée que si le format ne supporte pas les images (TXT). On peut comparer ce dernier cas à la balise <alt> de HTML.

6.2. Nom des fichiers HTML séparés

Par défaut, quand les fichiers HTML sont générés, le processeur SGML donne des noms arbitraires aux différents fichiers. Cela peut être gênant pour les personnes voulant indexer une des pages pour pouvoir facilement en voir les changements, ou même pour vous, pour savoir ce que contient chaque fichier. Quelque soit votre raison, voici comment indiquer les noms à utiliser :

Dans votre première balise <article> (qui devrait être la seule), ajoutez un paramètre id et appelez-le index. Cela devrait vous donner ceci :

<article id="index">

Ne modifiez pas la première balise <sect1> puisqu'elle correspond généralement à une introduction et que vous voulez certainement qu'elle apparaisse sur la première page. Pour les autres balises <sect>, ajoutez un paramètre id avec comme valeur le nom voulu. Ces noms ne doivent contenir que des caractères alphanumériques et être suffisamment courts pour être compréhensibles.

<sect1 id="tips">

6.3. Utiliser ldp.dsl

Le LDP utilise son propre fichier DSSSL, qui ajoute quelques fonctions dont un fond de page blanc et la table des matières que vous voyez au début des HOWTO. Vous trouverez la version la plus récente de ce fichier à l'adresse http://metalab.unc.edu/gferg/ldp/ldp.dsl.

Une fois que vous disposez du fichier, vous devrez en éditer les premières lignes pour modifier le chemin vers les fichiers DSSSL DocBook. Mon exemple utilise les outils Cygnus.

Placez le fichier ldp.dsl dans /usr/lib/sgml/stylesheets et ouvrez-le avec l'éditeur de texte de votre choix. Vous devriez voir quelque chose comme ceci :

<!DOCTYPE style-sheet PUBLIC "-//James Clark//DTD DSSSL Style
Sheet//EN" [ <!ENTITY % html "IGNORE"> <![%html;[ <!ENTITY %
print "IGNORE"> <!ENTITY docbook.dsl SYSTEM "docbook.dsl" CDATA dsssl> ]]> <!ENTITY % print "INCLUDE">
<![%print;[ <!ENTITY docbook.dsl SYSTEM "docbook.dsl" CDATA dsssl> ]]> ]>

Si vous utilisez un autre DSSSL, changez les chemins pour les faire correspondre avec les répertoires html et print de votre DSSSL.

Une fois cela effectué, vous pouvez générer des fichiers HTML :

bash$ mkdir HOWTO-HOWTO ; cd HOWTO-HOWTO 
bash$ jade -t sgml -ihtml -d \
  /usr/lib/sgml/stylesheets/ldp.dsl\#html \
  ../HOWTO-HOWTO.sgml

La première commande crée un nouveau répertoire où placer les fichiers. La seconde (l'appel à Jade) génère un fichier HTML pour chaque section de votre document. Si vous préférez générer des fichiers RTF, vous pouvez utiliser cette commande :

bash$ jade -t rtf -d /usr/lib/sgml/stylesheets/ldp.dsl \
../HOWTO-HOWTO.sgml