Créer des documents PDF avec DocBook

ArticleCategory: [Choose a category for your article]

Applications

AuthorImage:[Here we need a little image form you]

[Photo of the Author]

TranslationInfo:[Author and translation history]

original in en Egon Willighagen 

en to fr Georges Tarbouriech 

AboutTheAuthor:[A small biography about the author]

Egon a rejoint l'équipe Hollandaise de LF en 1999 et il est devenu le deuxième éditeur au début de cette année. Il est étudiant en chimie à l'Université de Nijmegen. Il joue au basket et aime la randonnée.

Abstract:[Here you write a little summary]

Cet article décrit comment utiliser DocBook pour créer des documents PDF et traite des outils dont vous aurez besoin pour éditer ces documents et les traduire au format PDF. Cet article nomme les outils nécessaires mais n'indique pas comment les installer, il est par conséquent destiné à des utilisateurs expérimentés de Linux.

La première partie de l'article mettra l'accent sur le format des documents DocBook. J'essaierai ensuite de présenter les outils de conversion au format PDF pour permettre leur lecture par l'intermédiaire d'Acrobat.

ArticleIllustration:[This is the title picture for your article]

[Illustration]

ArticleBody:

Qu'est-ce que DocBook?

DocBook [1] est une application SGML développée pour baliser des documents, comme le HTML le fait pour les documents du web. Par opposition au HTML, DocBook ne fournit pas d'information concernant la mise en page du document. C'est la raison pour laquelle les documents DocBook doivent être convertis dans d'autres formats avant de pouvoir les visualiser. La conversion vers d'autres formats se réalise à partir d'outils qui appliquent une feuille de style donnée au document DocBook.


 
Figure 1: Conversion de DocBook vers PDF par l'intermédiaire d'une feuille de style


Plus loin dans cet article nous verrons quelle feuille de style utiliser pour cette conversion et quels outils permettent d'appliquer la feuille de style au document DocBook. Etudions d'abord la manière d'amalgamer ces documents.

Ecrire un article

DocBook est capable de baliser deux sortes de documents: les articles et les livres. Bien qu'ils soient équivalents, j'utiliserai comme exemple le balisage d'un article. D'abord quelques principes de base concernant DocBook.

DocBook est par définition une application SGML, comme le HTML. Mais il existe aussi une version XML de DocBook. La version XML est plus stricte, mais plus facile à lire et donc plus facile à apprendre. Puisque le XML est également une application SGML, tous les outils SGML peuvent être utilisés. Les différences les plus marquantes entre le SGML et le XML sont les suivantes (et elles s'appliquent à toutes les applications XML):

Cela signifie que vous ne pouvez pas utiliser <BR> comme en HTML, mais que vous devez utiliser <BR></BR>. La seconde contrainte signifie que vous ne pouvez pas écrire <B><A HREF="une_url">cliquez ici</B></A> mais que vous devez encapsuler correctement les composantes: <B><A HREF="une_url">cliquez ici</A></B>.

Maintenant que nous avons terminé avec ces formalités importantes, nous pouvons commencer à écrire des articles dans DocBook.

    <?xml version="1.0"?>
    <article>
      <title>Ecrire des articles dans DocBook</title>
      <artheader>
        <abstract>
      Cet article décrit comment utiliser DocBook pour créer des documents PDF
      et traite des outils dont vous aurez besoin pour éditer ces documents et les traduire 
      au format PDF
        </abstract>
        <author>
          <firstname>Egon</firstname>
          <surname>Willighagen</surname>
        </author>
        <date></date>
      </artheader>
    </article>


Je pourrais dire que ce n'est pas difficile. Nous avons commencé un article contenant un titre, un bref résumé, la date à laquelle il a été écrit et le nom de l'auteur.

L'étape suivante consiste à ajouter des paragraphes à l'article en utilisant des balises de paragraphe:

    <?xml version="1.0"?>
    <article>
      <title>Ecrire des articles dans DocBook</title>
      <artheader>
        ... Les titres de paragraphe ...
      </artheader>
  
      <section>
        <title>Introduction</title>
      </section>

      ... autres paragraphes ...

    </article>


Nous avons ajouté un paragraphe d' Introduction à l'article. D'autres balises de paragraphe peuvent être utilisées pour définir des Résultats, une Conclusion ou tout autre paragraphe.

Ajouter du texte et d'autres éléments

Tout texte est contenu dans des balises para, comparables aux balises p du HTML:

    <section>
      <title>Introduction</title>
      <para>
    DocBook est une application SGML développée pour baliser 
    des documents, comme le HTML le fait pour les documents du web.
      </para>
    </section>


Mais en dehors du texte, de nombreuses autres balises sont disponibles. Dans ce qui suit nous allons voir comment des éléments tels que des exemples, des listes, des images et autres peuvent être insérés dans l'article.

Ajouter des exemples

Des exemples peuvent être ajoutés à l'aide de la balise exemple, comme dans ce qui suit où un programme exemple est fourni:

<example>
  <title>Programme Perl qui convertit un document XML en une page HTML.</title>
  <programlisting>
    #!/usr/bin/perl -w
    use diagnostics;
    use strict;
    use XML::XSLT;

    my $XSLTparser = XML::XSLT->new();
    $XSLTparser->open_project ("file.xml", "stylesheet.xsl", "FILE", "FILE");
    $XSLTparser->process_project;
    $XSLTparser->print_result();    
  </programlisting>
</example>
Mais cela pourrait contenir aussi du texte, des images ou autre chose.

Ajouter des listes

Comme le HTML DocBook peut aussi contenir des listes. Les listes sont définies par la balise itemizedlist qui peut comporter plusieurs éléments:

<itemizedlist>
  <listitem>
    <para>un élément</para>
  </listitem>
  <listitem>
    <para>un autre élément</para>
  </listitem>
  <listitem>
    <para>encore un élément</para>
  </listitem>
</itemizedlist>
Remarquez qu'ici aussi le texte est contenu dans des balises para. Le texte doit toujours se trouver à l'intérieur de ces balises!

Les listes peuvent également être classées. Dans ce cas vous pouvez utiliser la balise orderedlist à la place de la balise itemizedlist. En ajoutant un paramètre de numérotation (ex. <orderedlist numeration="Arabic">) vous pouvez définir le type de nombre.

Ajouter des images

Vous pouvez mettre des images dans l'article:

<mediaobject>
<imageobject>
<imagedata fileref="une_image.gif" format="gif"/>
</imageobject>
<textobject>
  <para>
    Si vous n'utilisiez pas <productname>Lynx</productname>
    vous pourriez voir une image.
  </para>
</textobject>
</mediaobject>
Vous pouvez voir qu'à côté de l'image nous trouvons aussi un texte. En fait, j'aurais pu ajouter aussi une vidéo. La feuille de style qui convertit le document DocBook en PDF choisirait alors la meilleure solution, qui serait certainement l'image.

Remarquez aussi que le mot Lynx est entre des balises. C'est une fonctionnalité propre aux langages balisés dans lesquels la mise en page est séparée de l'information. L'article signale simplement que Lynx est un produit et que son nom est Lynx. La feuille de style indique ensuite que le nom du produit doit être affiché de manière spécifique, en italique par exemple. Dans le paragraphe suivant nous allons voir d'autres balises pour les mots.

Balises de mots

Comme montré dans l'image exemple ci-dessus, les mots eux-mêmes peuvent avoir des balises. Dans le tableau ci-dessous vous trouverez certaines balises spécifiques aux mots:

Balise Description
abbrev Une abrévation, particulièrement si elle est suivie par un point.
Exemple:
<para><abbrev>ex.</abbrev> signifie par exemple.</para>
acronym Un acronyme
Exemple:
<para><acronym>DSM</acronym> (chemical company) signifie "De StaatsMijnen" (=Les Mines d'Etat).</para>
email Quelques adresses email
Exemple:
<para>Mon email est <email>egon.w@linuxfocus.org</email></para>
keyword Un des mots-clé de l'article
Exemple:
<para>A mon humble avis <keyword>la chimie</keyword> est très importante.</para>
Beaucoup d'autres balises sont listées dans un tableau de Référence [2].

Maintenant que les balises de DocBook ont été présentées dans cette courte introduction, il est temps de continuer et de commencer à créer un document PDF.

Convertir le document en PDF

Une fois que nous avons des documents DocBook nous pouvons les convertir en différents formats. A côté de l'évident PDF, nous pouvons convertir le document en un site web, un document PostScript, un fichier source Tex ou en RTF (Rich Text Format) document qui peut être lu par WordPerfect, Word, StarWriter et d'autres traitements de texte. Mais dans cet article nous ne nous intéressons qu'à la conversion en document PDF.

Les documents DocBook peuvent être écrits avec un éditeur tel que Vi ou Nedit. L'idéal c'est Emacs: Norman Walsh a écrit un mode majeur d'Emacs pour docbook [3] qui ajoute des fonctionnalités utiles, telles que compléter des noms de balises ou insérer des modèles complets de balises.
En plus de créer votre propre article de test, vous pouvez télécharger ma version qui contient les exemples de cet article.

Comme expliqué au début de cet article nous avons besoin d'une feuille de style et d'un outil l'utilisant pour convertir l'article DocBook au format PDF. La feuille de style ne convertit pas directement le DocBook en PDF, il existe une étape TeX intermédiaire. La feuille de style que nous utilisons vient des "Norman Walsh's Modular DocBook Stylesheets" qui [4] sont écrites en DSSSL.

Pour utiliser ces feuilles de style DSSSL pour des conversions nous avons besoin d'un processeur DSSSL. Le processeur que j'utilise s'appelle Jade [5] et a été développé par James Clark (il a cessé le support pour cet outil). Il est remplacé par OpenJade [6], mais je ne l'ai pas encore utilisé.

Notez que des "packages" du Modular Stylesheets, Jade et JadeTex (voir ci-dessous) sont disponibles pour toutes les distributions qui les utilisent (comme RedHat, Suse, Corel ou Debian)! Vérifiez donc la source de votre distribution (CD ou site web) avant!


Sur mon système Debian les Walsh's Modular Stylesheets pour la conversion vers PDF sont installés dans /usr/lib/sgml/stylesheets/dsssl/docbook/nwalsh/print/ ce qui est obtenu par le paramètre "-d" pour Jade. L'option "-t" demande à Jade d'utiliser TeX:

egonw@localhost> ls -al
total 3
-rw-r--r--    1 egonw    egonw        2887 Apr  8 22:06 docbook_article.xml
egonw@localhost> jade -t tex -d /usr/lib/sgml/stylesheets/dsssl/docbook/nwalsh/print/docbook.dsl docbook_article.xml
egonw@localhost> ls -al
total 21
-rw-r--r--    1 egonw    egonw        2887 Apr  8 22:06 docbook_article.xml
-rw-r--r--    1 egonw    egonw       17701 Apr  8 22:29 docbook_article.tex
Comme vous pouvez le voir, Jade génère un fichier TeX. Ce fichier TeX peut alors être converti en PDF par l'outil pdfjadetex contenu dans le "package" JadeTeX [7]:
egonw@localhost> ls -al
total 21
-rw-r--r--    1 egonw    egonw        2887 Apr  8 22:06 docbook_article.xml
-rw-r--r--    1 egonw    egonw       17701 Apr  8 22:29 docbook_article.tex
egonw@localhost> pdfjadetex docbook_article.tex
Ceci produit un docbook_article.pdf. Remarquez l'ajout de différents éléments de mise en page tels que le titre de l'article en haut de chaque page et l'utilisation d'une police différente pour le listing du programme. Quand j'ai commencé à travailler avec DocBook j'ai passé le plus clair de mon temps à chercher les combinaisons que je pouvais obtenir. Cet article ne montre qu'une combinaison.

Remarques de conclusion

Le langage DocBook XML est très vaste. Il en est de même pour les moyens de conversion vers d'autres formats Cet article ne présente qu'une très brève introduction. Vos questions peuvent être posées dans la page de discussion pour cet article. D'autres informations peuvent être trouvées dans les références [8] et [9]. Cette dernière est d'ailleurs entièrement écrite en DocBook!

Des fonctionnalités avancées non couvertes par cet article mais disponibles dans DocBook sont les suivantes:

Peut-être des sujets pour un futur article.

Références

1. DocBook website
2. Quick Reference: DocBook Elements
3. Emacs major mode for DocBook
4. The Modular DocBook Stylesheets
5. Jade
6. OpenJade
7. JadeTeX
8. Norman Walsh's DocBook site
9. DocBook: The Definate Guide on SGML variant