Introduction à Docbook

Antoine Calando

AllianceMCA

22 Août 2003


Table of Contents

Qu'est ce que DocBook?
1. Les différents éditeurs XML/Docbook disponibles
Les éditeurs complets
Morphon XML Editor
XXE (XMLmind XML Editor)
oXygen
epcEdit
Jaxe
Lyx
Xeena
Exchanger XML Editor
TurboXML
Collaborative Markup Editor
Les éditeurs simples ou en développement
Xerlin
Conglomerate
Qemacs
JXMLpad
Les éditeurs non testés
Emac
GeToX
Lucid' XML Editor
Xed
xmlPro
Visual XML
Peter's XML Editor
Cooktop
ElfData
xmlspy
Thot Book / Thot Editor
2. La structure d'un document DocBook
Les balises XML
L'entête
La hiérarchie des éléments
Les éléments courants
Les éléments racines book et article
Titres, sections et paragraphes
Meta-informations
Élements inline courants
Références croisées
Listes
Tableaux
Images
Termes et données informatiques
Autres éléments blocs
Élements non traités
Les entités et autres subtilités XML
Entités générales internes
Entités générales externes
Caractères spéciaux
La documentation officielle
3. Convertir du DocBook vers un autre format
Valider un document DocBook
Convertir vers XHTML (1 page)
Convertir vers XHTML (plusieurs pages)
Convertir vers PDF
4. Quelques liens sur DocBook et XML
Sites DocBook officiels
Sites XML officiels
Autres sites sur DocBook

Qu'est ce que DocBook?

DocBook est un langage permettant l'écriture de n'importe quel type de document, bien qu'il s'agisse en général de documents techniques. Il a été créé en 1991 par les sociétés Hal Computer Systems et O'Reilly.

À la différence d'autres formats comme Word, Postscript ou le PDF, il n'est pas conçu pour spécifier la forme sous laquelle le document va être présenté, mais uniquement pour spécifier sa structure. Si on désire lire un document DocBook présenté de manière agréable, il faudra obligatoirement passer par une feuille de style (CSS) spécifiant l'apparence de chaque structure DocBook, ou encore le convertir vers un autre format

Il est dérivé des langages XML et SGML, c'est à dire qu'il existe deux définitions de DocBook, selon qu'on utilise comme langage de base XML ou SGML. Ces deux définitions sont cependant pratiquement identiques, XML pouvant être considéré comme une amélioration de SGML. Ces définitions sont implémentées sous forme de DTD (Document Type Definition) qui vont contenir grosso modo la liste des balises utilisables et la manière dont elles s'imbriquent les unes dans les autres.

Son principal avantage est d'être un langage très fortement structuré avec de nombreuses balises et des règles d'imbrications strictes. Il est facilement convertible vers d'autres formats (HTML, PDF, TeX...). Il est de plus très répandu, et il est donc possible de trouver beaucoup de documentation dessus, ainsi que des outils pour l'éditer, le valider, le convertir...

Son point faible est aussi d'être très structuré (!), ce qui le rend assez rebutant à écrire au premier abord : il est difficile de savoir quelles sont les éléments qui conviennent au contenu que l'on veut écrire, si ces éléments peuvent s'imbriquer dans celui du niveau supérieur, si il y a des éléments obligatoires au niveau inférieur, si ils ont un ordre à respecter... heureusement, il existe des éditeurs permettant de guider l'utilisateur lors de la rédaction, et parvenir à un document valide devient assez facile même pour un débutant. On peut cependant remarquer un certain nombre d'incohérences dans sa version actuelle (V4.2) ; il faut espérer qu'elles seront corrigées dans les prochaines versions.

Voici un example de source DocBook :

<section>
   <title>Les éditeurs complets</title>
   <section>
      <title><application>Morphon XML Editor</application></title>
      <simplelist type="vert">
         <member>Licence : gratuite</member>
         <member>Systèmes : JVM (
            <systemitem class="osname" moreinfo="none">Windows</systemitem>,
            <systemitem class="osname" moreinfo="none">Linux</systemitem>,
            <systemitem class="osname" moreinfo="none">MacOS</systemitem>...)
         </member>
         <member>Version : 3.1.2</member>
      </simplelist>
      <para>Cet éditeur est l'un des meilleurs disponibles, et il présente
         l'avantage d'être distribé gratuitement. Il permet d'éditer le document
         en mode WYSIWYG, avec balises visibles (simples ou encadrant leur
         contenu), en mode source (pas d'auto-complètement cependant).
      </para>
  (...)

Chapter 1. Les différents éditeurs XML/Docbook disponibles

Les éditeurs complets

Morphon XML Editor

Licence : gratuite
Systèmes : JVM (Windows, Linux, MacOS...)
Langage : Java
Version : 3.1.2

Cet éditeur est l'un des meilleurs disponibles, et il présente l'avantage d'être distribué gratuitement. Il permet d'éditer le document en mode WYSIWYG, avec balises visibles (simples ou encadrant leur contenu), en mode source (pas d'auto-complètement cependant).

Il est possible de sélectionner un mot dans une liste importante en tapant ses premières lettres, ce qui facilite grandement l'écriture lors de l'insertion d'éléments par des raccourcis clavier. L'insertion d'entités est par contre plutôt fastidieuse.

Il est possible d'éditer les tableaux et d'afficher les images JPEG et GIF lors de l'édition.

Un éditeur de page de style (CSS) est aussi disponible, ainsi qu'un fichier CSS pour DocBook ; ce dernier nécessite cependant quelques modifications pour être véritablement utilisable, comme par exemple pour permettre l'affichage des JPEG.

Un correcteur orthographique est disponible, mais seul un dictionnaire américain est fourni. On peut trouver un dictionnaire français là : http://www.macromedia.com/support/dictionaries/

Important

Sous Linux, il est important de mettre la variable d'environnement LC_ALL à fr_FR pour disposer des accents français (nécessaire avec tout programme utilisant Java 1.4.2). Sous TCshell, faire :

setenv LC_ALL fr_FR

Sous bash :

export LC_ALL=fr_FR

Lien : http://www.morphon.com/

Morphon XML Editor

XXE (XMLmind XML Editor)

Licence : commerciale et gratuite (fonctionnalités restreintes)
Systèmes : JVM (Windows, Linux, MacOS...)
Langage : Java
Version : 2.4

Il s'agit là aussi d'un des meilleurs éditeurs disponible. Édition possible en mode WYSIWYG et arbre simultanément.

Correcteur orthographique.

Interface très pratique.

Lien : http://www.xmlmind.com/xmleditor/index.html

XXE

oXygen

Licence : commerciale, évaluation gratuite pendant 30 jours
Systèmes : JVM (Windows, Linux, MacOS...)
Langage : Java
Version : 2.0.3

Cet éditeur est spécialisé dans le mode source où il offre une possibilité d'auto-complètement des balises au fur et à mesure qu'on les tape. Il existe aussi un mode arbre, mais qui est malheureusement affiché dans une fenêtre différente.

Configuration de la conversion du document XML vers un autre format intégré à l'interface.

Correcteur orthographique intégré.

Lien : http://www.oxygenxml.com/index.html

oXygen

epcEdit

Licence : commerciale, évaluation gratuite pendant 60 jours
Systèmes : Windows, Linux, Sun Solaris
Systèmes : Windows, Linux, Solaris
Langage : Tcl/Tk
Version : 1.2.4

Le mode d'édition principale est avec balises simples. Il est possible d'éditer le source avec peu de fonctionnalités.

Ne gère pas les URL du type file://localhost/...!!!

Lien : http://www.epcedit.com/

epcEdit

Jaxe

Licence : GPL
Systèmes : JVM (Windows, Linux, MacOS...)
Langage : Java
1.7

Petit éditeur, simple mais complet, avec la liste des balises possibles accessible facilement. Mode d'édition unique avec balises simples ou sur une ligne.

Aucun raccourci clavier! Argl!

Rendu HTML accessible depuis l'interface.

Correcteur orthographique.

Lien : http://jaxe.sourceforge.net/Jaxe.html

Jaxe

Lyx

Licence : GPL
Systèmes : Unix-like
Langage : C++ / Qt ou Xforms
Version : 1.3.2

Lyx est un éditeur WYSIWYG conçu initialement pour fonctionner avec LaTeX. Il est capable dans ses dernières versions d'exporter un fichier au format DocBook, mais la rédaction du document se fait selon la structure propre à Lyx et non selon celle d'un document DocBook. Il n'est d'ailleurs pas possible d'ouvrir directement un fichier au format DocBook.

Lien http://www.lyx.org/

Lyx

Xeena

Licence : Commerciale, évaluation gratuite (illimitée)
Systèmes : JVM (Windows, Linux, MacOS...)
Langage : Java
Version : 1.2EA

Unique mode d'édition par arbre.

Interface sous Linux peu esthétique.

Impossible de changer de DTD sans relancer l'application.

Lien : http://www.alphaworks.ibm.com/tech/xeenal

Xeena

Exchanger XML Editor

Licence : Commerciale, évaluation gratuite pendant 30 jours
Systèmes : JVM (Windows, Linux, MacOS...)
Langage : Java
Version : 1.0

Éditeur permettant la rédaction en mode source avec auto-complètement, ainsi qu'en mode arbre.

Gestion de projet.

Lien : http://www.cladonia.com/products.htm.

Exchanger XML Editor

TurboXML

Licence : Commerciale, évaluation gratuite pendant 30 jours
Systèmes : JVM (Windows, Linux, MacOS...)
Langage : Java
Version : 2.3.1

Cet éditeur propose la rédaction de document sous forme d'arbre ou en mode source basique.

Trouve des erreurs dans le DTD DocBook officiel!

Un éditeur de Schema/DTD est aussi intégré

Lien : http://www.tibco.com/solutions/products/extensibility/turbo_xml.jsp

TurboXML

Collaborative Markup Editor

Licence : Commerciale, évaluation gratuite pendant 30 jours.
Systèmes : JVM (Windows, Linux, MacOS...)
Langage : Java
Version : 1.1.3

Cet éditeur, bien que présenté pour la rédaction en XML, présente plutôt des fonctionnalités dignes d'un bon éditeur classique... mais sans rien apporter de particulier pour l'édition du DocBook, à part la coloration syntaxique. Le mode source est le seul mode d'édition proposé, et il n'y a pas d'auto-complètement des balises, ni de boîtes de dialogues.

Il possède cependant des fonctions originales pour dialoguer d'un éditeur à un autre dans un réseau.

Lien : http://www.topologi.com/products/tme/

Collaborative Markup Editor

Les éditeurs simples ou en développement

Xerlin

Licence : libre
Systèmes : JVM (Windows, Linux, MacOS...)
Langage : Java
Version : 1.2

Cet éditeur, dont la dernière version stable date de juin 2002, est plutôt limité. Il ne permet que l'édition en mode arbre, et n'est pas vraiment conçu pour être utilisé avec DocBook et ses centaines de balises.

D'après sa documentation, il serait plutôt étudié, grâce à une API adequate, pour pouvoir utiliser des plugins rendant l'édition plus facile ou plus spécifique aux besoins de l'utilisateurs. Le nombre de plugins disponible semble cependant assez limité...

Lien : http://www.xerlin.org/

Xerlin

Conglomerate

Licence : GPL
Systèmes : Unix-like
Langage : C / Gnome2
Version : 0.5.4

Enfin un éditeur XML sous Linux écrit en C... mais toujours en beta version, et malheureusement inutilisable à cause de ses plantages fréquents...

Il propose un mode d'édition assez esthétique, avec des balises visibles encadrant leur contenu

Lien : http://www.conglomerate.org

Conglomerate

Qemacs

Licence : LGPL
Systèmes : Unix-like
Langage : C
Version : 0.3.1

Cet éditeur possède l'interface et les principales fonctionnalités d'Emacs, tout en restant très petit. Il possède d'autres fonctionnalités intéressantes, comme par example l'édition simultanée en mode source ou en mode WYSIWYG. Il ne se limite pas à DocBook et est aussi conçu pour d'autres langages.

Il manque cependant encore de maturité et ne propose pas de fonctions spécifiques à DocBook comme l'auto-complètement, la validation, la conversion...

Lien : http://qemacs.org/

Qemacs

JXMLpad

Licence : Shareware, évaluation gratuite.
Systèmes : JVM (Windows, Linux, MacOS...)
Langage : Java
Version : 1.9.2

Ce petit éditeur est en fait un composant Java qu'il est possible d'intégrer dans d'autres applications. Il propose l'édition en mode source avec colorisation syntaxique et une vue sous forme d'arbre.

Lien : http://www.japisoft.com/xmlpad/

Les éditeurs non testés

Emac

Licence : GPL
Systèmes : Windows, Linux, MacOS et bien d'autres...
Langage : C
Version : 21.3

Je ne présenterais pas cet éditeur... Sachez juste qu'il existe des packages lui permettant de gérer le DocBook, comme PSGML ou DocBook IDE.

Lien Emacs : http://www.gnu.org/software/emacs/emacs.html

Lien PSGML : http://www.lysator.liu.se/~lenst/about_psgml/

Lien DocBook IDE : http://nwalsh.com/emacs/docbookide/

GeToX

Licence : GPL
Systèmes : Unix-like
Langage : C / GTK
Version : 0.1.1

Éditeur en développement (depuis un moment d'ailleurs), que je n'ai pas réussi à compiler.

Lien : http://idx-getox.idealx.org/

Lucid' XML Editor

Licence : gratuite
Systèmes : Serveur Web Tomcat
Langage : Java / Javascript / Java Server Pages

Cet éditeur est une application web tournant en partie sur le serveur, en partie chez le client sous forme de Javascript. Il faut cependant le serveur adéquat pour l'installer...

Lien : http://www.lucid-it.com/en/tech-zone/editor/

Xed

Licence : Gratuite
Systèmes : Unix-like, Windows
Langage : C

Impossible de le compiler sous Linux, d'autre part les fonctionnalités semblent très pauvres et le projet abandonné...

Lien : http://www.cogsci.ed.ac.uk/~ht/xed.html

xmlPro

Licence : Commerciale, évaluation limitée gratuite
Systèmes : JVM (Windows, Linux, MacOS...)
Langage : Java
Version : 2.0

La version d'évaluation plantant au démarrage, on ne saura pas ce que vaut cet éditeur qui n'a pas l'air bien différent des autres...

Lien : http://www.vervet.com/xmlpro.html

Visual XML

Licence : Gratuite
Systèmes : JVM (Windows, Linux, MacOS...)
Langage : Java

Développement figé depuis décembre 1999, d'autre part ne fonctionne qu'avec JDK1.1.8.

Lien : http://www.cogsci.ed.ac.uk/~ht/xed.html

Peter's XML Editor

Licence : Gratuite
Systèmes : Windows

Lien : http://www.iol.ie/~pxe/index.html

Cooktop

Licence : Gratuite
Systèmes : Windows

Lien : http://xml.cooktop.com

ElfData

Licence : Commerciale, évaluation gratuite pendant 16 jours d'utilisation.
Systèmes : MacOS

Lien : http://www.elfdata.com/xmleditor/

xmlspy

Licence : Commerciale, évaluation gratuite pendant 30 jours
Systèmes : Windows, Linux avec Wine, MacOS avec Virtual PC

Lien : http://www.xmlspy.com/

Thot Book / Thot Editor

Licence : Libre
Systèmes : Unix-like

Projet en phase initiale, consistant à utiliser Thot Editor ou la Thot Lib pour éditer du DocBook.

Lien Thot Editor : http://opera.inrialpes.fr/Thot/index.html

Lien Thot Book : http://www.nongnu.org/thotbook/

Chapter 2. La structure d'un document DocBook

Les balises XML

La structure du format DocBook XML repose uniquement sur l'utilisation de balises XML. Même si ces balises peuvent être invisibles ou affiché selon un mode particulier dans certains éditeurs, il est franchement conseillé de connaître leur format.

Voici une description sommaire des différents types de balise rencontrés dans DocBook :

  • Élement elem contenant le texte abcdef :

    <elem> abcdef </elem> 
  • Élement vide :

    <elem></elem>
    <element/>
  • Élement possédant deux attributs :

    <element attribut1="valeur1" attribut2="valeur2"> texte </element>
  • Commentaire :

    <!-- a b c d e f -->
  • Instruction XML (déclaration du type de document, définition d'une entité...) :

    <!instruction param1 param2>
  • Instruction de traitement (processing instruction) destinée à l'application :

    <?instruction param1="value1" param2="value2"?>

L'entête

Avec un éditeur spécialisé pour DocBook, l'entête du document sera généralement automatiquement générée. Il est tout de même intéressant de savoir ce qui s'y trouve, afin de mieux comprendre DocBook.

Les premières lignes de ce document DocBook sont les suivantes :

<?xml version="1.0" encoding="UTF-8"?>
<?xml-stylesheet href="file://localhost/home/antoine/doc/dtd/docbook.css" type="text/css"?>
<!DOCTYPE article SYSTEM "file://localhost/home/antoine/doc/dtd/docbookx.dtd">

La première ligne, obligatoire, est le prologue. Elle indique que le fichier est au format XML 1.0, et que l'encodage se fait en Unicode.

La seconde ligne (une instruction de traitement) indique la page de style à utiliser avec ce document, c'est-à-dire comment afficher le document. Cette ligne est optionnelle et servira par exemple à l'éditeur à personnaliser l'affichage du document en mode WYSIWYG.

La troisième ligne est propre au format DocBook, c'est la déclaration du type de document. Elle indique l'élément racine du document (ici article) ainsi que le DTD à utiliser, sous forme d'URL et précédé du mot-clé SYSTEM.

Le DTD peut aussi être défini de manière publique :

<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"  "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">

L'URL du DTD est alors censée se trouver dans un fichier catalogue et correspondre à l'entrée "-//OASIS//DTD DocBook XML V4.2//EN". Cependant, et à la différence du DocBook SGML, une URL du DTD doit quand même être indiquée (ici "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd").

L'entête est ensuite suivie du contenu du document, qui doit commencer par l'élément racine précisé dans l'entête :

<article>
  <title>Introduction à DocBook</title>
  <section>
    ...
</article>

La hiérarchie des éléments

Les éléments décrits ici sont les plus importants pour la structure d'un document. La liste simplifiée de ces éléments est la suivante :

  1. <set> : ensemble de un ou plusieurs livres,

  2. <book> : livre, type de document le plus fréquent,

  3. <part> : partie d'un livre,

  4. composants : <chapter> (chapitre d'un livre), <article> (utilisé habituellement comme élément racine) ou <reference> (utilisé pour des pages de référence, dans le style manpage),

  5. <section> : élément pouvant s'imbriquer plusieurs fois, définissant ainsi des sous-sections,

  6. blocs : éléments apparaissant sous forme de blocs séparés les uns des autres, et prenant toute la largeur de la page: <para>, <xxxxlist>, <table>, <mediaobject>...

  7. inline : éléments incorporés dans un bloc de texte, comme <emphasis> utilisé au début de cette ligne.

Cette liste offre un aperçu de la structure d'un document DocBook, mais elle n'est ni exhaustive ni imposée. Il existe d'autre éléments pouvant par exemple faire partie d'un <book> (<toc>, <preface>, <index>...). Il n'est aussi pas obligatoire d'inclure tous les éléments listés : un <article> peut contenir un <para> sans <section> entre, de même, on peut rédiger un document dont l'élément racine est <reference>. Il existe cependant de nombreuses contraintes... pour les connaître, le mieux est de se référer à la documentation officielle.

Les éléments courants

Les éléments racines <book> et <article>

Ces éléments vont contenir l'ensemble du document. Il s'agit des éléments racines les plus usuels et choisir l'un ou l'autre va dépendre de la taille du document et de ce qu'il doit contenir.

<article> est le plus simple : il ne pourra pas contenir de composants comme une préface ou des chapitres. Il contient généralement un <title>, puis il doit obligatoirement contenir au moins une section ou un élément bloc comme <para>, <table>, <mediaobject>... cependant l'ordre des éléments importe : un paragraphe peut précéder une section, l'inverse n'étant pas vrai! Un <article> peut aussi contenir des composants comme <appendix>, <toc> (table of content) ou <bibliography>, mais ils obéissent à des règles assez strictes.

<article>
   <title>L'article de la mort (qui tue)</title>
   <para>Rentrons dans le vif  du sujet!</para>
   <section>
      ...
   </section>
</article>

L'élément <book>, en plus d'un <title>, peut contenir les composants : <toc>, <lot>, <preface>, <chapter>, <appendix>, <glossary>, <bibliography>, <index> qui peuvent aussi être regroupés en parties (<part>).

<book>
   <title>Livre Ognerie</title>
   <toc/>
   <preface>
      <title>Introduction</title>
      <para> Blablabla... </para>
   </preface>
   <part>
      <title> 1ère partie </title>
      <chapter>
         <title>Chapitre eurie</title>
         <para> Et patati et patata... </para>
      </chapter>
   </part>
   <index>
      ...
   </index>
</book>

Un autre élément racine ou composant pouvant se révéler utile est <reference>, qui contient un ensemble de pages de référence (comme les manpage sous unix).

Titres, sections et paragraphes

L'élément <title> est utilisé, comme nous venons de le voir, pour les <book> et <article>, mais aussi pour les composants et les éléments blocs qui en exigent fréquemment un. Certains éléments peuvent en être dispensés, à condition de commencer par <informal>, comme <informaltable>.

Il peut être suivi des éléments <subtitle> et <titleabbrev>.

Les sections se trouvent généralement dans les <article> ou les <chapter>. Elles existent sous la forme recursive <section> ou absolue <sect1>, <sect2>... Il existe aussi <simplesect> qui est le dernier niveau d'imbrication de section, ainsi que <bridgehead> qui est une fausse section sans contenu.

Les paragraphes (<para>) sont les éléments bloc les plus utilisés. Ils existent aussi sous la forme <formalpara> et contiennent un <title> et un <para> normal, ainsi que sous la forme <simpara>, où ils ne peuvent pas contenir d'éléments bloc.

Meta-informations

Tous les éléments <book>, divisions, composants, sections et bloc possèdent un élément optionel de meta-informations où peuvent être placer différentes informations (auteur, version, copyright...) qui n'apparaiteront pas forcement dans le document final. En voici quelques uns (la liste est longue!) : <bookinfo>, <articleinfo>, <sectioninfo>, <blockinfo> (ce dernier correspond à n'importe quel élément bloc).

Les informations les plus courantes sont les suivantes (j'ai indiqué la manière dont elles s'imbriquent les unes dans les autres par des retraits par rapport au début de la ligne) :

<title>              titre du document
<author>             nom de l'auteur
   <honorific> (M., Mme, Dr), <firstname>, <surname>, <lineage> (Junior, Senior...), <othername>
   affiliation   l'organisation auquelle appartient un individu
      <jobtitle>     la profession au sein de l'organisation
      <orgname>      le nom de l'organisation
      <orgdiv>       le nom d'une division
   <address>         l'adresse d'un individu
      <street>, <pob> (boîte postale), <postcode>, <citystate>, <country>, <phone>, <fax>, <email>, <otheraddr>
<copyright>          copyright, avec année(s) et détenteur
   <year>, <holder>
<date>               date de publication ou de révision
<releaseinfo>        informations sur la distribution actuelle
<revhistory>         historique des révisions
   <revision>        entrée décrivant une révision
      <revnumber>    numéro de révision
      <revremark>    commentaire associé
<legalnotice>        informations légales
<keywordset>         ensemble de mots-clefs correspondants au document
   <keyword>         entrée correspondant à un mot-clef

Élements inline courants

<abbrev>          abréviation
<acronym>         acronyme (abréviation se prononçant comme un mot normal)
<citetitle>       titre d'une oeuvre
<emphasis>        italique
<foreignphrase>   expression étrangère
<personname>      nom d'une personne
<replaceable>     partie à remplacer par l'utilisateur (comme <sectn> à la place de <sect1>, <sect2>...)
<quote>           citation
<subscript>       indice (example)
<superscript>     exposant (example)
<markup>          expression à représenter tel quel
<productname>     nom d'un produit
<trademark>       marque déposée

Certains éléments inline cités dans la section Méta-informations peuvent aussi servir dans un bloc normal comme <address> ou <email>. De plus, la section Termes informatiques traite de tous les éléments ayant trait à l'informatique.

Références croisées

Liens hypertexte

<anchor>     définie une cible pour un lien
<xref>       lien interne avec texte généré par la cible (attribut xrefname)
<link>       lien interne
<ulink>      lien externe grâce à une URL
<olink>      lien généré par <modspec>
<modespec>   définit un lien à générer pour <olink>

Notes de bas de page

<footnote>      note de bas de page
<footnoteref>   référence vers une note          

Callout

Les callouts permettent d'associer une annotation à une marque dans un bloc particulier (image, listing...). Le principe est le même que pour une note de bas de page dans du texte ordinaire.

<area>                  <areaset>            <areaspec>              <callout> 
<calloutlist>           <co>                 <coref>                 <screenco>
<programlistingco>      <mediaobjectco>      <imageobjectco>

Listes

<simplelist>         liste simple, peut être définie horizontale ou verticale grâce à l'attribut type,
   <member>          entrée, contient directement le texte,

<itemizedlist>       liste avec puce,
   <listitem>        entrée, doit contenir un élément bloc comme <para,>

<orderedlist>        liste ordonnée,
   <listitem>        entrée (cf. au dessus),

<variablelist>       liste dont chaque entrée associe un terme à une description,
   <varlistentry>    entrée,
      <term>         terme à décrire,
      <listitem>     description (cf. au dessus),
   
<segmentedlist>      liste comprenant plusieurs titres, et dont chaque entrée possède une sous-entrée pour chaque titre,
   <segtitle>        titre, contient directement le texte,
   <seglistitem>     entrée, (doit contenir autant de <seg> qu'il y a de <segtitle> en début de liste),
      <seg>          sous-entrée, contient le texte directement.

Tableaux

DocBook utilise les tableaux de type CALS de XML, qui offrent beaucoup de possibilités. Là encore, il est conseillé de se reporter à la documentation officielle pour leur utilisation exacte (notamment la liste des attributs et les exemples).

<informaltable>           tableau sans titre
<table>                   tableau avec titre
   <tgroup>               contient le tableau et spécifie le nombre de colonnes dans l'attribut cols
      <spanspec>          associe un nom à un étalement sur plusieurs colonnes (optionnel)
      <colspec>           formate une colonne (optionnel)
      <thead>             première(s) rangée(s) du tableau, généralement l'en-tête (optionnel)
      <tfoot>             dernière(s) rangée(s) du tableau (optionnel)
      <tbody>             corps du tableau, contient les rangées sans formatage particulier
         <row>            contient une rangée
            <entry>       cellule du tableau (pouvant s'étaler sur plusieurs colonnes ou rangées)
            <entrytbl>    cellule contenant un sous tableau

Images

Il est possible grâce à l'élément <mediaobject> d'insérer dans un document des images, des vidéos ou du son. On ne s'intéressera ici qu'aux images ; il est possible de donner une description textuelle de l'objet, dans le cas où l'image ne peut s'afficher.

<mediaobject>         insère un objet en mode bloc
<inlinemediaobject>   insère un objet en mode inline (permet de l'inclure dans un <ulink>)
   <caption>          titre de l'objet
   <imageobject>      image correspondant à l'objet
      <imagedata>     fichier ou entité contenant l'image

   <textobject>       texte correspondant à l'objet, contient <textdata> ou un autre élément bloc (comme <para>)
      <textdata>      fichier ou entité contenant le texte

On précise les noms de fichiers ou d'entités dans l'élément <imagedata> (ainsi que <textdata>) grâce aux attributs fileref ou entityref (voir section sur les entités). La taille de l'objet peut être est spécifiée à différents niveaux :

viewport area : contient l'image et le cadre ; définie par width et depth ; l'image peut être centrée grâce à align et valign
content area : taille de l'image dans le document ; définie par contentwidth et contentdepth, ou encore par size (pourcentage par rapport à la taille réelle) et scalefit (1 si l'image ne doit pas être déformée)
taille réelle de l'image : taille spécifiée par le fichier original, utilisée par défaut.

On peut aussi préciser le format de l'image avec format ; cela permet de proposer plusieurs formats et de laisser l'application traitant le document choisir celui qu'elle préfère.

Note

Les éléments <graphic> et <graphicco> permettent aussi d'insérer des images, mais ceux ci seront bientôt abandonnés (à partir de la version 5 de DocBook).

Termes et données informatiques

DocBook est particulièrement bien pourvu pour la documentation informatique. Il possède un très grand nombre d'éléments identifiant le type de données et de termes. Voici la liste des éléments blocs :

<screen>              texte sur un écran, reproduit le contenu tel quel (existe aussi avec callouts),
<programlisting>      listing, reproduit le contenu tel quel (existe aussi avec callouts),
<synopsis>            décrit la syntaxe d'une commande ou fonction (beaucoup d'éléments associés : se référer à la doc!),
   <lineannotation>   ligne de commentaire pour un des 3 éléments in extenso ci dessus,

<screenshot>          copie d'écran, contient un <mediaobject>,

Les éléments inline étant très nombreux, la liste suivante n'est pas exhaustive :

<computeroutput>   texte généré par l'ordinateur,
<userinput>        texte tapé par 'utilisateur,

<application>      nom d'un logiciel,
<command>          nom d'un executable,
<filename>         nom d'un fichier
<systemitem>       terme relatif à un système (comme le nom d'un OS ou d'une ressource),
<hardware>         composant hardware
<sgmltag>          balise SGML ou XML,
<constant>         nom d'une constante,
<errortext>        message d'erreur,
<envar>            variable d'environnement,
<variable>         variable
<prompt>           invite au début d'une ligne de commande,
<property>         propriété,
<guibutton>        nom d'un bouton dans une GUI (interface graphique utilisateur),
<guimenu>          nom d'un menu dans une GUI,
<guimenuitem>      nom d'une entrée dans un menu,
   <accel>         lettre raccourci clavier dans un menu (comme F dans Fichier,)
<shortcut>         raccourci clavier
   <keycombo>      combinaison de touches
      <keycap>     nom d'une touche

Autres éléments blocs

<literallayout>       texte reproduit in extenso (tel quel/verbatim)
   <lineannotation>   commentaire
<example>             exemple avec un titre
<informalexample>     exemple sans titre
<figure>              figure avec un titre pouvant être flottante (attribut <float> à 1)
<informalfigure>      figure sans titre pouvant être flottante
<blockquote>          citation
   <attribution>      auteur d'une citation
<abstract>            résumé
<highlights>          point principaux
<caution>, <important>  admonitions
<warning>, <note>, <tip>
<remark>

<qandaset>            ensemble de questions/réponses
   <qandadiv>         titre d'une division de l'ensemble
   <qandaentry>       entrée comprenant une question et (optionnel) une ou plusieurs réponses
      <question>      question (le "Q :" par défaut peut être changer par <label>)
      <answer>        réponse (le "A :" par défaut peut être changé par <label>)
         <label>      change le label d'une question ou réponse

<sidebar>             bloc séparé du reste du texte normal du document

<procedure>           description d'une procédure, d'un algorithme
   <step>             étape dans la procédure
      <substeps>      sous-étape

Élements non traités

DocBook possède encore plusieurs familles d'éléments intéressantes qui ne seront pas détaillées ici. Il s'agit d'éléments permettant l'écriture de bibliographies (élément racine : <bibliography>), de glossaires (<glossary>), de tables des matières (<toc>, souvent générées automatiquement), d'index (<index>), de pages de référence (<reference>) et des modules EBNF, HTML Form, SVG et MathML.

Les entités et autres subtilités XML

Entités générales internes

Il s'agit de mot-clés permettant par exemple de remplacer une expression souvent employée. Elles sont définies ainsi en début de document (à la fin du tag DOCTYPE, entre crochets) : <!ENTITY entité "expression"> puis elles sont instanciées par &entité;.

<?xml version="1.0" encoding="..."?>
<!DOCTYPE book PUBLIC "..." "..." [
<!ENTITY bz "bizarre">
]>
<book>
...
<para>
- Oui, vous regardez votre couteau et vous dîtes &bz;,&bz;. Alors je croyais que ...
</para><para>
- Moi, j'ai dit &bz;, &bz;, comme c'est étrange ! Pourquoi aurais je dit &bz;, &bz; ?
</para><para>
- Je vous assure mon cher cousin, que vous avez dit &bz;, &bz;.
</para><para>
- Moi, j'ai dit &bz;,  comme c'est &bz; !" 
</para>
...

Entités générales externes

Elles permettent d'inclure un fichier externe dans le document.

<?xml version="1.0" encoding="..."?>
<!DOCTYPE book PUBLIC "..." "..." [
<!ENTITY chap1 SYSTEM "/home/antoine/doc/a_la_banane.xml">
<!ENTITY chap2 SYSTEM "/home/antoine/doc/au_raisin.xml">
]>
<book>
   <title>Les tartes aux fruits</title>
   &chap1;
   &chap2;
</book>

Il est possible d'inclure des fichiers binaires, à condition de préciser leur type dans la définition (NDATA suivi du type) et de les inclure uniquement en tant qu'attributs.

<?xml version="1.0" encoding="..."?>
<!DOCTYPE article PUBLIC "..." "..." [
<!ENTITY graphic SYSTEM "/path/to/file.png" NDATA PNG>
]>
<article>
...
<imagedata entityref="graphic"/>

Caractères spéciaux

Il s'agit en fait d'entités : "&amp;" donnera "&". En voici une petite liste :

    half  ½          num  #         copy  ©        laquo  «
      lt  <          amp  &          reg  ®        raquo  »
      gt  >          ast  *        trade  ™         para  ¶
  dollar  $       commat  @        micro  µ       hellip  …

La documentation officielle

On peut trouver les différentes versions de la documentations sur le site officiel :

Version 1.0.3 (Docbook 3.1) : http://www.oasis-open.org/docbook/documentation/reference/html/docbook.html

Version 2.0.8 (DocBook 4.2) : http://docbook.org/tdg/en/html/docbook.html

Version 2.0.8 non-expansée : http://docbook.org/tdg/en/html/docbook-x.html (dans cette version les listes d'élément dans les synopsis sont remplacée par les noms de groupes d'éléments).

Les sections "Content Model" obéissent à une syntaxe particulière. Voici la liste des mots clés et caractères utilisés :

    EMPTY        l'élément est obligatoirement vide
   #PCDATA     correspond à n'importe quelle chaîne de caractère
         ,            sépare deux éléments pouvant se suivre (dans le même ordre!)
         |            sépare deux éléments s'excluant mutuellement (xor)
        ?            ajouté à un élément pouvant apparaître 0 ou 1 fois
        *            ajouté à un élément pouvant apparaître 0 fois ou plus
        +           ajouté à un élément pouvant apparaître 1 fois ou plus

Chapter 3. Convertir du DocBook vers un autre format

Valider un document DocBook

La validation se fait avec xmllint. Cette opération est cependant effectuée par la plupart des éditeurs dédiés à XML ou DocBook.

xmllint --valid --noout in.xml

Convertir vers XHTML (1 page)

La conversion se fait grâce à un processeur XSLT (eXtensible Stylesheet Language Transformation) auquel on précise la feuille de style (fichier XSL) à utiliser. Il existe des feuilles de style standard pour DocBook sur le site du DocBook Open Repository Project.

xsltproc /usr/share/sgml/docbook-xsl-1.60.1/xhtml/docbook.xsl in.xml > out.xhtml

Convertir vers XHTML (plusieurs pages)

Il suffit de spécifier la feuille de style adéquate (chunk.xsl au lieu de docbook.xsl) :

xsltproc /usr/share/sgml/docbook-xsl-1.60.1/xhtml/chunk.xsl in.xml > out.xhtml

Convertir vers PDF

Pour la conversion vers le PDF, nous devons passer par le format intermédiaire FO (Formatting Object) :

xsltproc /usr/share/sgml/docbook-xsl-1.60.1/fo/docbook.xsl in.xml > out.fo

Puis la conversion vers le PDF peut se faire soit avec Fop (application Java) :

java org.apache.fop.apps.Fop in.fo out.pdf

...soit avec pdfxmltex :

pdfxmltex in.fo

Chapter 4. Quelques liens sur DocBook et XML

Sites DocBook officiels

La page officiel DocBook : http://www.oasis-open.org/docbook/

La documentation officielle : http://docbook.org/

La FAQ : http://www.dpawson.co.uk/docbook/

Le DocBook Open Repository Project : http://docbook.sourceforge.net/

La liste de diffusion DocBook : http://lists.oasis-open.org/archives/docbook/

La liste de diffusion Applications DocBook : http://lists.oasis-open.org/archives/docbook-apps/

Sites XML officiels

La recommandation W3C XML : http://www.w3.org/TR/REC-xml

La recommandation W3C XSL : http://www.w3.org/TR/xsl/

La recommandation W3C XSLT : http://www.w3.org/TR/xslt

Autres sites sur DocBook

Une référence des éléments (incomplet) : http://www.dpawson.co.uk/docbook/qrefhtml.html

Une référence en PDF sur 1 page (très compacte!): http://www.dpawson.co.uk/docbook/docbookref.pdf

The DocBook Wiki : http://docbook.org/wiki/

Une liste de tutoriaux : http://docbook.org/wiki/moin.cgi/DocBookTutorials

...dont un assez complet en anglais : http://supportweb.cs.bham.ac.uk/documentation/tutorials/docsystem/build/tutorials/docbooksys/docbooksyshome.html

...un autre sympa en français, pour Windows et Linux : http://www.mirabellug.org/docs/docbook/

Un manuel détaillé en français (incomplet) : http://feloy.free.fr/dbmanual/index.html

...et sa version en DVI et INFO : http://savannah.gnu.org/projects/dbmanual/