Sommaire

La racine

Méta-informations

Préface

Chapitre

Utilisation simple
Utilisation avec les entités

Types de documents

Docbook permet d'utiliser, entre autres, les racines suivantes :

set : ensemble de livres
book : livre
article : article
refentry : page de manuel
chapter : chapitre
...

La racine

Pour créer un livre, il suffit de prendre book comme racine :

Il est toutefois plus propre d'indiquer la langue :

et éventuellement RevisionFlag qui peut prendre les valeurs changed, added, deleted, off.

Méta-informations (optionnel)

Les méta-informations permettent de définir des informations sur l'ouvrage en question, des informations qui ne font pas partie du document en lui-même mais relatives à son existence et sa création. Toutes les méta-informations sont incluses dans la balise bookinfo. On trouve :

title : Texte d'un en-tête ou le titre d'un élément orienté-bloc
authorgroup : Information sur l'auteur
author : Auteur du document
authorinitials : Initiales ou autre identifiant pour l'auteur d'une révision ou d'un commentaire
firstname : Prénom
othername : Nom qui n'est pas un prénom, surnom ou nom de famille
surname : Nom de famille
keywordset : Ensemble de termes décrivant le contenu du document
keyword : Terme décrivant le contenu d'un document
releaseInfo : Information sur une version particulière du document
revhistory : Révisions d'un document
revision : Entrée dans revhistory, décrivant certaines révisions faites au texte
revnumber : Numéro d'une révision
revremark : Description d'une révision
abstract : Sommaire du document
date : Date de publication ou de révision du document

Par exemple :

On peut aussi ajouter un historique de modification

<bookinfo>

<title>Titre du livrek</title>
<date>15/06/2008</date>
<releaseinfo>1.00</releaseinfo>

<authorgroup>
<author>
<firstname>Prénom de l'auteur</firstname>
<othername>Autre nom de l'auteur</othername>
<surname>Nom de l'auteur</surname>
</author>
</authorgroup>

<revhistory>

<revision>
<revnumber>2.0</revnumber>
<date>05/06/2000</date>
<authorinitials>PN</authorinitials>
<revremark>Refonte complète</revremark>
</revision>

<revision>
<revnumber>1.1</revnumber>
<date>12/02/2000</date>
<authorinitials>PN</authorinitials>
<revremark>Réécriture du troisième chapitre</revremark>
</revision>

<revision>
<revnumber>1.0</revnumber>
<date>24/01/2000</date>
<authorinitials>PN</authorinitials>
<revremark>Version initale</revremark>
</revision>

</revhistory>

<abstract>
<para>
exemple de livre édité avec docbook
avec de nombreux autres exemples
</para>
</abstract>

<keywordset>
<keyword>docbook</keyword>
<keyword>exemples</keyword>
</keywordset>

</bookinfo>

Astuce

Pour se simplifier la vie, on pourra par exemple générer la partie d'historique des modifications à partir d'une extraction des informations CVS du dépôt utilisé pour le projet de documentation.

Ou encore, des informations sur la version diffusée courante peuvent être introduites par la balise releaseinfo. Cette balise pourra en particulier contenir un lien Internet sur la dernière version disponible :

Remarque

Notez l'utilisation d'un lien avec la balise ulink.

Préface (optionnel)

Un document pouvant posséder une préface, il existe pour cela la balise preface, utilisable comme suit :

<book lang="fr">

<preface>
<title>Préface</title>
<para>Ce livre contient deux chapitres.</para>
</preface>

[...]
</book>

Chapitre

Utilisation simple

Pour ajouter un chapitre, rien de plus simple que la balise chapter :

<book lang="fr">

<chapter>
<title>Premier chapitre</title>
<para>Premier paragraphe.</para>
<para>Deuxième paragraphe.</para>
[...]
</chapter>

<chapter>
[...]
</chapter>

[...]

</book>

Un chapitre pouvant contenir plusieurs sections, l'on peut ajouter la balise section qui permet de définir une sous-section par rapport à la section courante, utilisable à n'importe quel endroit du document.

Il existe aussi les balises sect1, sect2, sect3, sect4, sect5, qui définissent des sections de niveau 1, 2, 3, 4 et 5 mais il n'existe pas de niveaux supplémentaires.

<book lang="fr">

<chapter>

<title>Premier chapitre</title>
<para>Ce chapitre contient 2 sections.</para>

<sect1>
<title>Première section</title>
<para>Cette section contient deux sous-sections.</para>

<sect2>
<title>Première sous-section.</title>
<para>Premier paragraphe.</para>
<para>Deuxième paragraphe.</para>
</sect2>

<sect2>
<title>Deuxième sous-section.</title>
<para>Premier paragraphe.</para>
<para>Deuxième paragraphe.</para>
</sect2>

</sect1>

<sect1>
<title>Deuxième section</title>
<para>Cette section contient une sous-section.</para>

<sect2>
<title>Sous-section.</title>
<para>Premier paragraphe.</para>
<para>Deuxième paragraphe.</para>
</sect2>

</sect1>

[...]

</chapter>

<chapter>
[...]
</chapter>

[...]

</book>

Utilisation avec les entités

Il peut être utile d'alléger un document, surtout dans le cas d'un travail collaboratif. Par exemple, dans le cadre d'un projet, chaque personne ou chaque groupe travaille sur sa partie, contenue dans un chapitre et qu'il s'agit en définitive de tout rassembler sous book. Pour cela, on utilise des entités externes.

Il faut commencer par déclarer les entités externes

<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook V4.1//EN" [
<!ENTITY chapitre1 SYSTEM "chapitre1.xml">
<!ENTITY chapitre2 SYSTEM "chapitre2.xml">
]>

Puis utiliser les entités au moment adéquat. L'exemple précédent va donner :

<book>

<bookinfo>

<title>Titre du livrek</title>
<date>15/06/2008</date>
<releaseinfo>1.00</releaseinfo>

<authorgroup>
<author>
<firstname>Prénom de l'auteur</firstname>
<othername>Autre nom de l'auteur</othername>
<surname>Nom de l'auteur</surname>
</author>
</authorgroup>

<keywordset>
<keyword>docbook</keyword>
<keyword>exemples</keyword>
</keywordset>

</bookinfo>

&chapitre1;
&chapitre2;

[...]

</book>

Chaque chapitre contiendra alors les informations relatives à lui-même dont la structure sera conforme à la DTD, ayant pour racine chapter.

Rédaction d'un livre avec docbook