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