3.2. Structure d'un fichier DocBook

Les balises concernées dans cette section sont énumérées ci-dessous.

<?xml version="1.0" encoding="UTF-8" ?>
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN">
 
<book id="hello-world" lang="en">
 
<bookinfo>
<title>Hello, world</title>
</bookinfo>
 
<chapter id="introduction">
<title>Introduction</title>
 
<para>Ceci est l'introduction. Elle a deux sections</para>
 
<sect1 id="about-this-book">
<title>À propos de ce livre</title>

<para>C'est mon premier fichier DocBook</para>

</sect1>

<sect1 id="work-in-progress">
<title>Attention</title>

<para>Ceci est encore en construction</para>

</sect1>

</chapter>
</book>

L'exemple ci-dessus présente un squelette des balises de structure. La première ligne est la déclaration de DTD qui indique quelle DTD utiliser pour compiler ce document (nommément DocBook 4.2). Cette information sera décrite plus en détail dans la section Document Type Declaration.

Ensuite vient le modèle de contenu, qui est <book> ici. Vous pouvez utiliser <article>, qui est plus léger que <book> ou <refentry> qui est l'équivalent des pages de manuel UNIX.

Notez l'usage de l'attribut lang dans la balise <book>. L'attribut langage devrait toujours être utilisé pour rendre plus aisé de déterminer dans quelle langue le document a été écrit.

Après la balise <book> vient la meta information pour le document qui est encapsulée dans le repère <bookinfo>. Cette information sera décrite en détail dans la section Meta Information.

Ensuite viennent les chapitres de votre livre, qui contiennent une ou plusieurs balises de section (<sect1> - <sect5>). Les attributs (non numériques) ID pour <chapter> et <sect> des balises sont nécessaires pour deux raisons :

• Désigner toutes les sections de votre document vous permet de plus facilement faire des références croisées de ce document avec des hyperliens.

• jade utilise les ID des chapitres pour nommer les fichiers de sortie, ainsi si vous ne préciser pas les ID pour tous vos chapitres, les noms de fichiers seront différents chaque fois que les documents seront mis à jour, ce qui gaspille de l'espace dans le CVS.

Les chapitres et les sections doivent contenir au moins un <title> et une balise <para> vide. Les endroits où certains éléments doivent, ou ne doivent pas, ou peuvent apparaître est défini par la DTD DocBook et présenté en détail par le Guide de Référence.

Le contenu dans DocBook est inséré dans la balise <para> qui est très similaire à la balise <p> du HTML et du LinuxDoc sauf qu'elle doit toujours avoir un repère de fermeture </para>. Chaque fois qu'il y a un saut de ligne (comme dans une liste) le texte devra être inséré entre les balises <para>.

Résumons ce que nous avons vu. Un livre sera structuré de la façon suivante :

    book
      meta information
      chapter
        sect1
          sect2
        sect1
      chapter
        sect1
      appendix
        sect1
      appendix
        sect1
        ...
      glossary

    article
      meta information
      sect1
      sect1
        sect2
      sect1
      ...