Comprendre DocBook (Guide pratique)

  Version franaise du guide pratique DocBook Demystification HOWTO

  Eric Raymond

   <esr CHEZ thyrsus POINT com>

  Raphal Semeteys

   Adaptation franaise <raphael POINT semeteys CHEZ wanadoo POINT fr>

  Jean-Philippe Gurard

   Relecture de la version franaise <fevrier CHEZ tigreraye POINT org>

  Jean-Philippe Gurard

   Prparation de la publication de la v.f. <fevrier CHEZ tigreraye POINT
   org>

   Version : 1.3.fr.1.2

   11 juin 2008

   +------------------------------------------------------------------------+
   | Historique des versions                                                |
   |------------------------------------------------------------------------|
   | Version 1.3.fr.1.2           | 2008-06-11          | JPG               |
   |------------------------------------------------------------------------|
   | Correction d'une petite coquille. Merci Joris Rehm de nous l'avoir     |
   | signal. Remplacement d'un lien obsolte vers le livre  XML en        |
   | concentr  (qui n'est plus dit) par un lien vers sa version         |
   | originale.                                                             |
   |------------------------------------------------------------------------|
   | Version 1.3.fr.1.1           | 2007-04-26          | JPG               |
   |------------------------------------------------------------------------|
   | Modification du titre franais.                                        |
   |------------------------------------------------------------------------|
   | Version 1.3.fr.1.0           | 2006-01-07          | RSS, JPG          |
   |------------------------------------------------------------------------|
   | Adaptation franaise initiale.                                         |
   |------------------------------------------------------------------------|
   | Version 1.3                  | 2004-02-27          | ESR               |
   |------------------------------------------------------------------------|
   | Ajout de pointeurs vers deux diteurs. Add pointers to two editors.    |
   |------------------------------------------------------------------------|
   | Version 1.2                  | 2003-02-17          | ESR               |
   |------------------------------------------------------------------------|
   | Dplacement des rfrences  SGML aprs que celui-ci ait t prsent. |
   | Reorder to defer references to SGML until after it has been            |
   | introduced.                                                            |
   |------------------------------------------------------------------------|
   | Version 1.1                  | 2002-10-01          | ESR               |
   |------------------------------------------------------------------------|
   | Correction d'une erreur faite par inadvertance sur la position de la   |
   | FSF. Ajout d'un pointeur vers la FAQ DocBook. Correct inadvertent      |
   | misrepresentation of FSF's position. Added pointer to the DocBook FAQ. |
   |------------------------------------------------------------------------|
   | Version 1.0                  | 2002-09-20          | ESR               |
   |------------------------------------------------------------------------|
   | Version initiale. Initial version.                                     |
   +------------------------------------------------------------------------+

   Rsum

   Ce guide pratique tente de dissiper le brouillard et le mystre entourant
   le systme de balisage DocBook et les outils associs. Il est destin aux
   auteurs de documentations techniques pour les projets libres sous Linux,
   mais devrait galement tre utile  la rdaction d'autres types de
   documents sur d'autres systmes Unix.

   --------------------------------------------------------------------------

   Table des matires

   1. Introduction

   2. Pourquoi s'intresser  DocBook ?

   3. Balisage structurel : prambule

   4. Dfinitions de types de documents (DTD)

   5. Autres DTD

   6. La chane logicielle DocBook

   7. Quels sont les projets et les acteurs ?

   8. Outils de migration

   9. Outils d'dition

   10. Trucs et astuces

   11. Pratiques et standards apparents

   12. SGML et les outils SGML

                12.1. DocBook SGML

                12.2. Outils SGML

                12.3. Pourquoi le SGML DocBook est mort

                12.4. SGML-Tools

   13. Rfrences

1. Introduction

   Bon nombre de grands projets libres sont en train de converger vers
   l'utilisation du format DocBook comme format standard de documentation --
   des projets comme le noyau Linux, GNOME, KDE, Samba et le Projet de
   documentation Linux (LDP). Les dfenseurs du balisage structurel bas sur
   XML (par opposition au style plus ancien de balisage de prsentation
   illustr par troff, Tex et Texinfo) semblent avoir gagn la bataille
   thorique. Il est possible de produire un balisage de prsentation 
   partir d'un balisage structurel, mais l'inverse est trs difficile.

   Nanmoins, une grande confusion entoure DocBook et les programmes qui
   l'accompagnent. Ses adeptes parlent un argot dense et intimidant, mme
   selon les canons de l'informatique, utilisant  tout va des sigles sans
   rapport vident avec ce qui doit tre fait pour crire du texte balis et
   produire du HTML ou du Postscript. Les standards et les documents
   techniques sur XML sont notoirement obscurs.

   Ce guide va tenter de clarifier les principaux mystres existants autour
   de DocBook et de son utilisation pour les documents relatifs aux logiciels
   libres -- qu'il s'agisse de documentations techniques ou politiques. Notre
   objectif est de vous permettre de comprendre non seulement ce que vous
   devez faire pour fabriquer des documents, mais aussi pourquoi le processus
   est si complexe -- et comment on peut s'attendre  voir cela changer au
   fur et mesure de la disponibilit de nouveaux outils DocBook.

2. Pourquoi s'intresser  DocBook ?

   DocBook offre deux possibilits qui le rendent vraiment intressant. La
   premire est la production multi-formats et la seconde la ralisation de
   bases de documents interrogeables.

   La production multi-formats est la possibilit la plus simple et la plus
   proche de la ralisation ; il s'agit de la capacit  crire un document
   dans un format matre unique, qui puisse tre utilis pour produire
   diffrents formats d'affichage (en particulier du HTML pour la
   visualisation en ligne et du Postscript pour des impressions de haute
   qualit). Cette capacit est dsormais assez bien mise en uvre.

   Le terme base de documents interrogeable est une manire condense
   d'expliquer que DocBook puisse nous aider  aller vers un monde o
   l'ensemble de la documentation prsente sur votre systme d'exploitation
   libre constituera une base de donnes hypertexte, indexe et interrogeable
   de textes enrichis (plutt que d'tre parpille dans des formats varis
   en de multiples endroits comme c'est le cas aujourd'hui).

   Idalement, lorsque vous installerez un logiciel sur votre machine, il
   enregistrera sa documentation DocBook dans le catalogue de votre systme.
   Celui-ci produira automatiquement du HTML correctement index et
   interconnect au HTML contenu dans le reste de votre catalogue. La
   documentation du nouveau paquet sera alors disponible via un navigateur.
   Des recherches pourront tre raliss sur l'ensemble de la documentation
   via une interface ressemblant  un bon moteur de recherche.

   Le HTML en tant que tel n'est pas un format suffisamment riche pour nous
   rapprocher de ce monde. Pour ne citer qu'une seule de ses lacunes, le HTML
   ne permet pas de dclarer explicitement des entres d'index. DocBook
   possde la richesse smantique permettant la ralisation de bases de
   documents structures. C'est la raison fondamentale de son adoption par de
   si nombreux projets.

   DocBook a les inconvnients de ses avantages. Certains le trouvent trop
   lourd et verbeux pour pouvoir rellement constituer un format de
   composition confortable. Ce qui ne posera pas de problme, tant que les
   formats qu'ils affectionnent (comme le format POD de Perl ou le Texinfo
   GNU) disposent de moteurs permettant de produire du DocBook, tout le monde
   sera satisfait. Peu importe que tout le monde crive au format DocBook ou
   pas. Du moment que DocBook devient le format commun d'change de
   documents, nous resterons capables de raliser des bases de documents
   interrogeables unifies.

3. Balisage structurel : prambule

   Les anciens langages de mise en forme tels que Tex, Texinfo ou Troff
   permettaient de raliser un balisage de prsentation. Les instructions que
   vous donniez  ces systmes concernaient l'apparence et la disposition
   physique du texte (par exemple, des modifications de la fonte ou de
   l'indentation).

   Tant que votre objectif restait d'imprimer sur un seul support ou un seul
   type de priphrique d'affichage, le balisage de prsentation restait une
   bonne solution. Vous en atteignez les limites lorsque vous commencez 
   baliser un document en voulant (a) qu'il puisse tre mis en forme pour des
   dispositifs d'affichages trs diffrents (comme des imprimantes et le web)
   ou (b) raliser des recherches sur le document et l'indexer via sa
   structure logique (par exemple pour l'incorporer dans un systme
   hypertexte).

   Pour disposer de ces capacits, vous aurez besoin d'un systme de balisage
   structurel. Avec le balisage structurel, vous ne dcrirez pas l'apparence
   physique du document mais plutt les proprits logiques de ses
   diffrentes parties.

   Par exemple : dans un langage de balisage de prsentation, si vous dsirez
   accentuer un mot, vous indiquerez  l'outil de mise en forme de le mettre
   en caractres gras. Dans troff(1) cela ressemblera  ceci^[1] :

 Toutes vos base
 .B sont
 appartiennent  nous !

   Dans un langage de balisage structurel, vous indiquerez  l'outil de mise
   en forme de mettre le en relief :

 Toutes vos base <emphasis>sont</emphasis>
 appartiennent  nous !

   Le  <emphasis>  et le  </emphasis>  de la ligne prcdente sont
   appels des balises de marquage ou tout simplement des balises. Elles
   constituent les instructions de votre outil de mise en forme.

   Dans un langage de balisage structurel, l'apparence physique du document
   final sera contrle par l'application d'une feuille de style. C'est la
   feuille de style qui indiquera  l'outil de mise en forme de  reprsenter
   la mise en relief sous forme de caractres gras . Un des avantages des
   langages de balisage structurel est qu'en modifiant une feuille de style
   vous pourrez modifier de manire globale la prsentation du document (pour
   utiliser des polices de caractres diffrentes par exemple) sans avoir 
   modifier chaque occurrence, par exemple, de .B dans le document lui-mme.

4. Dfinitions de types de documents (DTD)

   [1][Note] Note
             Pour rester simple dans notre explication, cette section
             comporte certains raccourcis historiques qui seront corrigs
             dans une section ultrieure.

   DocBook est un langage de balisage structurel. Plus spcifiquement c'est
   un dialecte XML. Un document DocBook est un fichier XML qui utilise des
   balises XML pour dfinir sa structure.

   Afin d'appliquer une feuille de style  votre document et de lui donner
   une belle apparence, un outil de mise en forme aura besoin de savoir
   certaines choses sur la structure complte du document. Par exemple, il
   aura besoin de savoir qu'un livre est normalement constitu de parties
   liminaires, d'une suite de chapitres, puis de parties annexes afin de
   pouvoir mettre en forme correctement les en-ttes de chapitres. Afin qu'il
   puisse le savoir, vous devrez lui fournir une dfinition de type de
   document ou DTD. La DTD indique  l'outil de mise en forme les lments
   qui peuvent se trouver dans la structure du document ainsi que l'ordre
   dans lequel ils peuvent apparatre.

   Lorsqu'on dcrit DocBook comme une application de XML, on veut dire par l
   qu'il s'agit d'une DTD -- une DTD plutt consquente avec prs de 400
   balises.

   Derrire DocBook se cache un type de programme appel un analyseur de
   validation. Lorsque vous mettez en forme un document DocBook, la premire
   tape  franchir est de le passer au crible d'un analyseur de validation
   (qui est le premier composant de l'outil de mise en forme DocBook). Ce
   programme vrifie la validit de votre document par rapport  la DTD
   DocBook. Cela permet de s'assurer que vous n'tes en conflit avec aucune
   des rgles structurelles de la DTD (sinon le composant de l'outil de mise
   en forme en charge de l'application de la feuille de style pourrait s'y
   perdre).

   L'analyseur de validation va soit vous afficher des messages d'erreurs
   relatifs aux endroits o la structure du document est incorrecte, soit
   traduire le document en un flux d'vnements de mise en forme qui sera
   finalement combin avec votre feuille de style pour produire le rsultat
   mis en forme.

   Voici un schma du processus complet :

   La partie du schma comprise dans la zone en pointills est votre outil de
   mise en forme, autrement appele votre chane logicielle de mise en forme.
   Pour comprendre ce qui suit, en plus de l'entre vidente et visible de
   l'outil de mise en forme (le document source) vous devrez garder en tte
   les deux autres entres  caches  (DTD et feuille de style) de l'outil
   de mise en forme.

5. Autres DTD

   Un court dtour par les autres DTD vous aidera  distinguer les parties de
   la section prcdente qui sont spcifiques  DocBook de celles concernant
   tous les langages de balisage structurel.

   TEI [http://www.tei-c.org/] (Text Encoding Initiative) est une DTD
   consquente et labore, principalement utilise dans les milieux
   acadmiques pour la transcription informatique de textes littraires. La
   chane logicielle de TEI, fonctionnant sous Unix, utilise nombre d'outils
   utiliss par DocBook, mais avec des feuilles de style et (videmment) une
   DTD diffrentes.

   XHTML, la dernire version de HTML, est galement une utilisation d'XML
   dcrite par une DTD, ce qui explique l'air de famille existant entre les
   balises XHTML et DocBook. La chane logicielle XHTML est constitue de
   navigateurs web et d'un certain nombre d'utilitaires spcifiques
   d'impression.

   De nombreuses autres DTD XML sont maintenues afin de faciliter les
   changes d'informations structures dans des domaines aussi divers que
   l'informatique biologique ou la banque. Vous pouvez consulter la liste des
   rfrentiels [http://www.xml.com/pub/rg/DTD_Repositories] pour vous faire
   une ide de la varit des DTD existantes.

6. La chane logicielle DocBook

   Le moyen le plus simple de mettre en forme et de produire des documents
   XML DocBook est d'utiliser la chane logicielle xmlto. Elle est intgre 
   la distribution Red Hat et les utilisateurs de Debian peuvent la rcuprer
   via la commande apt-get install xmlto.

   Pour produire du XHTML  partir de vos sources DocBook, il vous faudra
   normalement faire quelque-chose comme ceci :

 bash$ xmlto xhtml foo.xml
 bash$ ls *.html
 ar01s02.html ar01s03.html ar01s04.html index.html

   Dans cet exemple, vous avez converti un document XML Docbook nomm foo.xml
   compos de trois sections principales en une page d'index et trois
   parties. Produire une seule page est tout aussi simple :

 bash$ xmlto xhtml-nochunks foo.xml
 bash$ ls *.html
 foo.html

   Enfin, voici comment produire du PostScript pour l'impression :

 bash$ xmlto ps foo.xml     # Production de PostScript
 bash$ ls *.ps
 foo.ps

   Certaines versions plus anciennes de xmlto peuvent tre plus bavardes en
   mettant de messages du type  Conversion en XHTML en cours  et ainsi de
   suite.

   Pour convertir vos documents en HTML ou en PostScript, vous devez disposer
   d'un moteur capable d'appliquer  la fois la DTD DocBook et une feuille de
   style adquate  votre document. Voici comment s'intgrent ensemble les
   outils libres utiliss  cette fin :

   Chane logicielle XML DocBook actuelle

   L'analyse du votre document et l'application de la feuille de style vont
   tre ralises par l'un des programmes suivants. Le plus courant est
   xsltproc, l'analyseur inclus dans la distribution Red Hat depuis la
   version 7.3. Les autres possibilits sont les programmes Java Saxon et
   Xalan.

   XHTML tant simplement une autre DTD XML, il est relativement ais de
   produire du XHTML de haute qualit  partir de DocBook. La conversion en
   HTML est ralise en appliquant une feuille de style plutt simple et
   c'est  peu prs tout. De mme RTF est simple  produire de cette manire
   et il est facile de produire un fichier de texte brut  partir d'XHTML ou
   de RTF.

   Le cas de l'impression est moins vident. Il est difficile de produire des
   impressions de haute qualit (ce qui correspond en pratique au format
   PDF^[2] d'Adobe, une version prte  l'emploi de PostScript). Pour le
   faire correctement, il est ncessaire de reproduire de manire
   algorithmique la finesse du jugement humain utilis par un typographe
   lorsqu'il passe du niveau du contenu  celui de la prsentation.

   Donc, premirement, une feuille de style traduit le balisage structurel
   DocBook en un autre langage XML -- FO (Formatting Objects). Le balisage FO
   est un vrai balisage de prsentation. Vous pouvez le considrer comme un
   quivalent fonctionnel de troff dans le monde XML. Il doit tre traduit en
   Postscript pour pouvoir tre intgr  un PDF.

   Dans la chane logicielle intgre  Red Hat, ce travail est pris en
   charge par un paquet de macros TeX appel PassiveTeX. Il traduit dans le
   langage TeX de Donald Knuth les objets de mise en formes produits par
   xsltproc. TeX a t un des tous premiers projets libres, un langage de
   mise en forme (au niveau de la prsentation) ancien mais puissant,
   apprci des mathmaticiens ( qui il fournit des fonctionnalits
   particulirement volues de description des notations mathmatiques). TeX
   est galement connu pour son efficacit dans les tches typographiques de
   base comme le crnage, le remplissage de lignes ou la csure. Le rsultat
   de l'excution de TeX, rcupr dans un format appel DVI (DeVice
   Independent), est ensuite transform en PDF.

   Si vous trouvez que cet enchanement de XML vers des macros TeX vers DVI
   vers PDF ressemble  une usine  gaz, vous n'avez pas tort. a grince, a
   siffle et a comporte d'horribles verrues. Les fontes constituent un
   problme important du fait qu'XML, TeX et PDF possdent des modles trs
   diffrents d'utilisation des fontes. En outre, la gestion de
   l'internationalisation et des paramtres rgionaux est un vrai cauchemar.
   La seule chose qui justifie cet enchanement est que cela fonctionne.

   La solution lgante sera FOP, un traducteur FO vers PostScript dvelopp
   par le projet Apache. Avec FOP, le problme de l'internationalisation est,
   s'il n'est pas rsolu, bien circonscrit : les outils XML manient l'Unicode
   de bout en bout. La correspondance entre glyphes et fonte est galement un
   problme relevant strictement de FOP. Le seul problme de cette approche
   est que cela ne fonctionne pas -- du moins pour le moment. En date d'aot
   2002, FOP est en version alpha non finalise -- utilisable mais brut de
   dcoffrage et fonctionnellement incomplet.

   Voici  quoi ressemble la chane logicielle FOP :

   Future chane logicielle XML DocBook intgrant FOP

   FOP a des concurrents. Il existe un autre projet appel xsl-fo-proc qui
   vise le mme objectif que FOP, mais en C++ (et donc plus rapide et ne
   reposant pas sur l'environnement Java). En date d'aot 2002, xsl-fo-proc
   est aussi en version alpha non finalise, dans un tat assez proche de
   celui de FOP.

7. Quels sont les projets et les acteurs ?

   La DTD DocBook elle-mme est maintenue par le Comit technique DocBook
   (DocBook Technical Committee), dirig par Norman Walsh. Norm est le
   principal auteur des feuilles de style DocBook. Il a consacr depuis de
   nombreuses annes une grande quantit d'nergie et de talent aux problmes
   extrmement complexes qu'aborde DocBook. Il est autant respect dans la
   communaut DocBook que l'est Linus Torvalds dans le monde Linux.

   libxslt [http://xmlsoft.org/XSLT/] est une bibliothque C qui interprte
   XSLT et applique les feuilles de style aux documents XML. Elle comprend un
   utilitaire, xsltproc, qui peut tre utilis comme outil de mise en forme
   XML. Son code a t crit par Daniel Veillard sous les auspices du projet
   GNOME, mais ne requiert aucun code GNOME pour fonctionner. J'ai entendu
   dire qu'elle tait extraordinairement plus rapide que ses alternatives
   Java, ce qui n'est pas une affirmation trs surprenante.

   xmlto [http://cyberelk.net/tim/xmlto/] est l'interface utilisateur de la
   chane logicielle intgre  Red Hat. Elle est crite et maintenue par Tim
   Waugh.

   Saxon [http://saxon.sourceforge.net/] et Xalan
   [http://xml.apache.org/xalan-j/] sont des programmes Java qui interprtent
   XSLT. Saxon semble tre conu pour fonctionner sous Windows. Xalan fait
   partie du projet XML Apache et fonctionne directement sous Linux et BSD.
   Il est conu pour fonctionner avec FOP.

   FOP [http://xml.apache.org/fop/] traduit des objets de mise en forme XML
   (FO) en PDF. Il fait partie du projet XML Apache et est conu pour
   fonctionner avec Xalan.

8. Outils de migration

   Le deuxime plus gros problme de DocBook est l'effort ncessaire pour
   convertir les anciens balisages de prsentation en balisage DocBook. Les
   tres humains sont gnralement capables de convertir automatiquement la
   prsentation d'un document en une structure logique, parce qu'ils sont,
   par exemple, capables de distinguer selon le contexte les cas o
   l'italique est utilis comme moyen d'accentuation de ceux o il signifie
   autre chose, comme le fait que la phrase soit en langue trangre.

   D'une faon ou d'une autre, il est ncessaire rendre explicite ce type de
   distinctions lors de la conversion de documents vers le format DocBook.
   Parfois elles sont prsentes dans l'ancien balisage mais ce n'est en
   gnral pas le cas et l'information de structure manquante doit, soit tre
   dduite par une heuristique intelligente, soit tre ajoute par un tre
   humain.

   Voici un rsum de l'tat des outils de conversion  partir de divers
   autres formats :

   GNU Texinfo

           La Free Software Foundation s'est fix comme politique de
           permettre d'utiliser DocBook comme format d'change. Texinfo est
           suffisamment structur pour permettre une conversion automatique
           satisfaisante, et les versions 4.x de makeinfo proposent une
           option --docbook qui produit directement du format DocBook. Vous
           trouverez plus d'information sur la page du projet makeinfo
           [http://www.gnu.org/directory/texinfo.html].

   POD

           Il existe un module POD::DocBook
           [http://www.cpan.org/modules/by-module/Pod/] qui traduit le
           balisage POD (Plain Old Documentation) en DocBook. Il prtend
           traduire l'intgralit des balises POD sauf la balise italique
           L<>. La page de manuel prcise galement  Il n'est pas possible
           d'utiliser de listes imbriques pour une sortie en DocBook  et
           fait remarquer que le module a t intensivement test.

   LaTeX

           LaTeX est (essentiellement) un langage de macros de balisage
           structurel construit au-dessus de l'outil de mise en forme TeX. Il
           existe un projet appel TeX4ht
           [http://www.lrz-muenchen.de/services/software/sonstiges/tex4ht/mn.html]
           qui (selon l'auteur de PassiveTeX) est capable de produire du code
           DocBook  partir de LaTeX.

   Pages de manuels et balisages bases sur troff

           On considre gnralement qu'il s'agit du problme de conversion
           le plus important et le plus dsagrable. Et en effet le balisage
           de base de troff(1) possde un niveau de prsentation trop bas
           pour que des outils de conversions puissent apporter quelque aide
           que ce soit. Cependant la situation s'claircit significativement
           si l'on considre les traductions de documents crits avec des
           paquets de macros comme man(7). Ceux-ci sont suffisamment
           structurs pour permettre une traduction automatique.

           J'ai moi-mme crit un outil pour ce faire car je n'en trouv
           aucun capable de faire proprement le travail (et galement parce
           que le problme est intressant). Il s'appelle doclifter
           [http://www.catb.org/~esr//doclifter/]. Il convertit au format
           SGML ou XML DocBook les macros man(7), mdoc(7), ms(7) ou me(7).
           Consultez la documentation pour plus d'informations.

9. Outils d'dition

   Il nous manque actuellement est un bon diteur structurel libre pour les
   documents SGML et XML.

   Le projet Conglomerate [http://conglomerate.org/] vise spcifiquement 
   fournir un bon diteur DocBook. Dbut 2004, ce programme tait toujours en
   version alpha.

   Le projet MlView [http://www.freespiders.org/projects/gmlview/] est un
   diteur XML gnraliste. Dbut 2004, il n'tait pas assez document et
   semblait tre en version alpha.

   LyX [http://www.lyx.org/] est un diteur de texte graphique utilisant
   LaTeX pour l'impression et permettant l'dition structurelle du balisage
   LaTeX. Il existe un paquet LaTeX qui produit du DocBook et un guide
   [http://bgu.chez.tiscali.fr/doc/db4lyx/] qui dcrit comment crire du SGML
   et du XML en utilisant LyX.

   GeTox [http://idx-getox.idealx.org/], l'diteur XML de GNOME, vise les
   utilisateurs ayant un profil non technique. Malheureusement, ce logiciel
   est toujours en version alpha (depuis aot 2001) et est plus un prototype
   qu'un outil utilisable. En outre, l'quipe du projet ne semble pas trs
   active. Le site du projet n'a pas t mis  jour entre mai 2001 et janvier
   2006 (date de publication de la version franaise de ce guide).

   GNU TeXMacs [http://www.math.u-psud.fr/~anh/TeXmacs/TeXmacs.html] est un
   projet d'diteur adapt  la rdaction de documents techniques et
   mathmatiques, et permettant l'affichage de formules. La version 1.0 a t
   publie en avril 2002. Les dveloppeurs prvoient une compatibilit XML 
   l'avenir, mais celle-ci n'est pas encore ralise.

   ThotBook [http://www.freesoftware.fsf.org/thotbook/] est un projet
   d'diteur graphique pour DocBook bas sur la bote  outils Thot. Il est
   vraisemblablement moribond car la page web n'a pas t mise  jour entre
   novembre 2001 et fvrier 2006 (date de publication de la version franaise
   de ce guide).

   La plupart des gens continuent  crire directement les balises  la main
   dans vi ou emacs.

10. Trucs et astuces

   Il est possible de produire un index en incluant une balise <index/> vide
    l'endroit du document o vous voulez qu'il apparaisse. Gardez en mmoire
   que, dbut 2004, cette fonctionnalit tait toujours assez fruste. Elle ne
   fusionnait pas les intervalles et le rendu au format PostScript n'tait
   pas encore d'une qualit suffisante pour une utilisation srieuse.

   Cet espace est rserv  d'autres trucs et astuces.

11. Pratiques et standards apparents

   Les outils d'dition et de mise en forme du balisage DocBook sont en train
   d'merger, bien que lentement. Mais DocBook en soi est un moyen et non une
   fin. Nous aurons besoin d'autres standards en plus de DocBook pour
   atteindre l'objectif de bases de documents interrogeables que j'ai voqu
   au dbut de ce document. Les deux enjeux principaux sont le catalogage de
   document et les mta-donnes.

   Le projet Scrollkeeper [http://scrollkeeper.sourceforge.net/] a pour
   objectif de satisfaire ce besoin. Il fournit des points d'entres
   utilisables par les scripts d'installation et de dsinstallation de
   paquets pour enregistrer et dsenregistrer leurs documentations dans une
   base de donnes commune partage et interrogeable.

   Scrollkeeper utilise le format Open Metadata Format
   [http://www.ibiblio.org/osrt/omf/]. Il s'agit d'un standard d'indexation
   des documentations libres similaire  un systme de catalogue sur fiche de
   bibliothque. L'ide est d'offrir des fonctionnalits de recherches
   avances utilisant aussi bien les mta-donnes du catalogue que le texte
   de la documentation elle-mme.

12. SGML et les outils SGML

   Dans les sections prcdentes j'ai laiss de cot une bonne partie de
   l'historique de DocBook. XML a un grand frre, SGML ou Standard
   Generalized Markup Language.

   Jusqu'en mi-2002, aucune discussion au sujet de DocBook n'aurait t
   complte sans une longue excursion dans SGML, les diffrences entre SGML
   et XML et des descriptions dtailles de la chane logicielle SGML
   DocBook. La vie est dsormais plus simple. Une chane logicielle XML
   DocBook libre est disponible, elle fonctionne aussi bien que ne l'a jamais
   fait la chane SGML et est beaucoup plus facile  utiliser. Si vous ne
   pensez jamais avoir  traiter d'anciens documents SGML DocBook, vous
   pouvez sauter la suite de cette section.

  12.1. DocBook SGML

   DocBook tait  l'origine une application de SGML et il existait une
   chane logicielle DocBook base sur SGML, qui est dsormais moribonde. Il
   existe des diffrences mineures entre la DTD DocBook SGML et la DTD
   DocBook XML que nous pouvons ignorer ici. La seule qui soit visible par
   les utilisateurs est le fait que les balises SGML vides ne ncessitent pas
   d'avoir une barre oblique ajoute avant le > de fermeture (la barre
   oblique obligatoire signifie que les analyseurs XML peuvent tre beaucoup
   plus simples car ils n'ont pas  connatre la DTD pour savoir quelles
   balises d'ouverture ncessitent des balises de fermeture).

   Jusqu' la version 4.01 (avant XHTML), HTML tait une application de SGML.
   TEI tait  l'origine galement une application de SGML. Les quipes en
   charge de ces deux DTD sont passes  XML pour la mme raison que les
   dveloppeurs de DocBook -- c'est radicalement plus simple. SGML tait
   extrmement complexe et s'est donc avr impossible  grer. La
   spcification comportait 150 pages trs denses et il n'a jamais t
   vrifi qu'un logiciel l'ait entirement mis en uvre.

   Le schma de chane logicielle que j'ai donn plus tt tait simplifi car
   il montrait uniquement la chane XML. Voici la version historiquement
   correcte :

   La chane logicielle DSSSL servait  traiter le SGML DocBook. Dans cette
   chane, un document au format DocBook est trait par un des deux moteurs
   de feuilles de style (Jade ou OpenJade). Il est ainsi transform en
   balisage de macros TeX qui tait convertit en DVI par un paquet appel
   JadeTex pour tre finalement transform en PostScript.

  12.2. Outils SGML

   Le projet docbook-tools [http://sources.redhat.com/docbook-tools/] fournit
   des outils libres pour convertir du SGML DocBook en HTML, PostScript et
   dans d'autres formats. Ce paquet est intgr  la distribution Red Hat et
    d'autres distributions Linux. Il est maintenu par Mark Galassi.

   Jade [http://www.jclark.com/jade/] est un moteur utilis pour appliquer
   des feuilles de style DSSSL  des documents SGML. Il est maintenu par
   James Clark.

   OpenJade [http://openjade.sourceforge.net/] est un projet communautaire
   entrepris parce que ses crateurs pensaient que la maintenance de Jade
   ralise par James Clark n'tait pas satisfaisante. Les programmes de
   docbook-tools utilisent OpenJade.

   PassiveTeX [http://www.tei-c.org.uk/Software/passivetex/] est le paquet de
   macros LaTeX utilis par xmlto pour produire du DVI  partir du XML
   DocBook. JadeTex [http://jadetex.sourceforge.net/] est le paquet de macros
   LaTeX utilis par OpenJade pour produire du DVI  partir du SGML DocBook.

  12.3. Pourquoi le SGML DocBook est mort

   La chane logicielle DSSSL, si l'on considre les nouveaux dveloppements,
   est, en pratique, morte. La chane XSLT a atteint mi-2002 une qualit
   suffisante pour les environnements de production. Une version
   fonctionnelle de cette chane est intgre  la distribution Red Hat 7.3.
   C'est sur cette chane que les dveloppeurs DocBook concentrent la plupart
   de leurs efforts.

   La raison du passage  XML est triple. Premirement, SGML s'est avr tre
   trop compliqu  utiliser ; deuximement, DSSSL s'est avr trop compliqu
    appliquer et enfin des parties significatives de la chane DSSSL se sont
   avres tre fragiles et trop mal conues.

   Apparent  SGML, XML possde un nombre de fonctionnalits rduit, ce qui
   est suffisant dans la plupart des cas tout en simplifiant grandement sa
   comprhension et la mise en uvre d'analyseurs. Les outils de traitement
   SGML (comme les analyseurs de validation) doivent mettre en uvre bon
   nombre de fonctionnalits non utilises par DocBook et les autres systmes
   de balisage de textes. Le fait d'enlever ces fonctionnalits a rendu XML
   plus simple et les outils de traitement XML plus rapides.

   Le langage utilis pour dcrire les DTD SGML est suffisamment pineux et
   rbarbatif pour que l'criture de DTD SGML relve du domaine de la science
   occulte. Les DTD XML, d'un autre cot, peuvent tre dcrites comme un
   dialecte d'XML lui-mme. Un langage de DTD spar n'a donc pas lieu
   d'tre. Une description XML d'une DTD XML est appele un schma. L'usage
   du terme DTD lui-mme va probablement se perdre au fur et  mesure de la
   standardisation des schmas.

   Cependant la chane logicielle DSSSL est surtout morte  cause de DSSSL
   lui-mme : le langage de description des feuilles de style de SGML tait
   trop obscur pour la plupart des tres humains ce qui a rendu les feuilles
   de style trop difficiles  crire et  modifier^[3].

   Les dfenseurs d'XML aiment rsumer tous ces changements ainsi :  XML :
   a a bon got et c'est facile  digrer. 

  12.4. SGML-Tools

   SGML-Tools tait le nom d'une DTD utilise par le Projet de documentation
   Linux (LDP) [http://www.tldp.org], dveloppe il y a quelques annes alors
   que la chane logicielle DocBook n'existait pas. Le balisage de SGML-Tools
   tait plus simple mais aussi beaucoup moins souple que DocBook. La chane
   logicielle SGML-Tool d'origine (outil de mise en forme, DTD et feuilles de
   style) est morte depuis dj un certain temps mais son successeur, appel
   SGML-tools Lite [http://sourceforge.net/projects/sgmltools-lite/] est
   toujours mis  jour.

   Le Projet de documentation Linux a progressivement abandonn SGML-Tools au
   profit de DocBook, mais il est toujours possible que vous ayez  reprendre
   de vieux guides pratiques. Ils sont reconnaissables par leur entte
   d'identification  <!doctype linuxdoc system> . Si jamais cela vous
   arrive, convertissez cette chose au format XML DocBook et enterrez
   rapidement la vieille version.

13. Rfrences

   Une des choses qui compliquent l'apprentissage de DocBook est le fait que
   les sites sur le sujet ont tendance  submerger les dbutants de listes de
   standards du W3C, d'exercices volumineux sur la thologie du balisage et
   de terminologie abstraite.

    Take My Advice: Don't Learn XML
   [http://xml.oreilly.com/news/dontlearn_0701.html]  ( Suivez mon conseil,
   n'apprenez pas XML ) de Michael Smith sonde le monde d'XML depuis un
   angle similaire  celui de ce document.

    DocBook: The Definitive Guide  Norman Walsh est disponible en version
   papier [http://www.oreilly.com/catalog/docbook/] et sur le web
   [http://www.docbook.org/tdg/en/html/docbook.html]. C'est en fait la
   rfrence qui fait autorit mais c'est un dsastre en tant que document
   d'introduction ou d'apprentissage. Lisez plutt ceci :

    Writing Documentation Using DocBook: A Crash Course
   [http://opensource.bureau-cornavin.com/crash-course/] . C'est un
   excellent guide d'apprentissage.

   Il existe une excellente  FAQ DocBook (en anglais)
   [http://www.dpawson.co.uk/docbook/]  contenant de nombreuses informations
   sur la personnalisation du style du HTML produit. Il existe galement un
   wiki [http://docbook.org/wiki/moin.cgi] DocBook (en anglais).

   Si vous crivez pour le Projet de documentation Linux, lisez le  LDP
   Author Guide [http://www.linuxdoc.org/LDP/LDP-Author-Guide/index.html] .

   La meilleure introduction  SGML et XML, que j'ai personnellement lue
   d'une traite, est celle de David Megginson :  Structuring XML Documents
   [http://www.amazon.fr/exec/obidos/ASIN/0136422993/171-8635393-7110656] 
   (Prentice-Hall, ISBN : 0-13-642299-3).

   Au sujet d'XML, le livre en anglais  XML in a Nutshell
   [http://oreilly.com/catalog/9780596002923/]  de W. Scott Means et
   Elliotte  Rusty  Harold, est trs bien.

    XML guide de l'utilisateur
   [http://www.amazon.fr/exec/obidos/ASIN/274640088X/171-8635393-7110656] 
   semble tre un ouvrage de rfrence assez approfondi sur XML et les
   standards associs (dont notamment Formatting Objects).

   Enfin, le site  The XML Cover Pages [http://xml.coverpages.org/]  vous
   entranera dans la jungle des standards XML, si c'est vraiment ce que vous
   voulez.

   --------------

   ^[1] N.D.T. : les fautes sont volontaires. Pour comprendre cette
   rfrence, jetez un il  l'article Wikipdia correspondant
   [http://fr.wikipedia.org/wiki/All_your_base_are_belong_to_us].

   ^[2] PDF signifie Format Portable de Document -- Portable Document Format
   dans la langue de Shakespeare.

   ^[3] Il s'agissait d'un dialecte de Scheme. Votre humble auteur, adepte de
   LISP depuis des lustres, est pris d'effarement  l'ide que cela puisse en
   faire fuir certains

