Cours DocBook accelere

3.2. Structure d'un fichier DocBook

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

book - Livre
article - Article
refentry - Équivalent d'une page de manuel
chapter - Chapitre d'un livre ou d'un article
sect1 ... sect5 - Sections et sous-sections d'un chapitre
title - Texte d'en-tête ou titre d'un élément orienté-bloc
para - Paragraphe

Exemple 3-1. Chapitres et sections


<?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 :

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

Un article sera structuré de la façon suivante :


    article
      meta information
      sect1
      sect1
        sect2
      sect1
      ...