Création d'un document DocBook XML

Comme vu précédemment, un document DocBook est un document XML : il doit respecter les règles d’écritures propre au XML, soit un texte contenant des balises prédéfinies par le concepteur. Ainsi, un document DocBook permettra de représenter des données pérennes que les hommes et les machines pourront manipuler. Comme tout document XML, le document DocBook doit se conformer à la DTD, l’ensemble de règles portant sur les éléments et leurs attributs qui permet la validation du XML.

La création d’un document DocBook comprend deux étapes bien distinctes :

• L’écriture proprement dite du texte XML, en respectant la DTD de DocBook

• La transformation de ce texte en un format lisible tel que le PDF, HTML, etc.

Rédaction

Tout d’abord, rappelons qu’un document Docbook permet de porter l’attention strictement sur le contenu, et non pas sur la présentation. Les nombreux (>370) éléments ou balises qui composent la DTD DocBook sont séparés en deux catégories :

• Hiérarchie : éléments structurels

• Information : éléments qui contiennent les données elles-mêmes (le texte)

Les différentes balises de structures

Les éléments de hiérarchie ou de structure sont primordiaux puisqu’elles permettent de donner les valeurs de sémantique en établissant la structuration du document. Il faut donc au préalable s’interroger sur le sens que l’on souhaite donner au texte a moment de la rédaction.

Eléments racines

Tout d’abord, nous allons nous intéresser aux éléments racines, c’est-à-dire les éléments de structure qui se trouvent tout en haut de la hiérarchie et qui débutent une documentation au format DocBook. Ils sont au nombre de 3 :

Set (collection, recueil de livres, ensemble de livres) Book (élément de départ le plus commun constitué lui-même d’un titre, sous-titre et titre abrégé optionnels ; de méta-informations optionnelles et d’un nombre quelconque, dans un ordre quelconque d’éléments (Preface, Chapter, Appendix, Bibliography, Glossary, Index, etc.) Article (article composé de sections comme sous parties comme Introduction, Corps de l’article et Conclusion).

Eléments de structure

Ces balises de structure font suite aux balises racines.

<chapter>: Chapitre d’un livre ou d’un article

<sect1> ... <sect5> : Sections et sous-sections d’un chapitre. Une section doit contenir au moins une balise de type paragraphe.

<title> : Texte d’en-tête ou titre d’un élément orienté-bloc

<para> : Paragraphe

<blockquote> : Une citation dans le texte. Cette balise doit contenir au moins une balise de type paragraphe.

<Itemizedlist> : Une liste non numérotée. Elle doit contenir des éléments listitem.

<Orderedlist> : Une liste numérotée. Elle doit contenir des éléments listitem. L’attribut numeration permet de définir le type de numérotation : arabic, loweralpha, upperalpha, lowerroman, upperroman.

<Listitem> : Un élément de liste (numérotée ou non) qui doit contenir au moins un élément de type paragraphe.

Nous avons vu que set désigne les ensembles de livres, mais quels sont les points communs et les différences entre <book> et <article> ? Les deux éléments racines de hiérarchie devront comporter un titre <title>. La principale différence réside dans le fait que l’on peut insérer des chapitres et une préface dans un <book> et pas dans un <article>. Un <article> est donc plus léger qu'un <book>

En règle générale on utilisera pour un <book>
book
meta information
chapter
sect1
sect2
sect1
chapter
sect1
appendix
sect1
appendix
sect1 ...
glossary

et pour un <article>
article
meta information
sect1
sect1
sect2
sect1 ...

Atteindre le haut de la page

Eléments d’information

Voici quelques balises d’information :

<emphasis> permet de mettre en valeur un morceau du texte.
<example> permet de signaler un exemple. On peut y insérer un titre <title>
<ulink> permet de créer un lien hypertexte. L’attribut url permet de préciser l’adresse de destination.

Exemple :

<ulink url= « lien »>Canne à pêche </ulink>, aura pour effet de transformer le texte Canne à pêche en lien externe vers l’adresse lien.

On peut également créer des liens internes, c’est-à-dire des liens à l’intérieur du document. Cela permet de pointer par exemple un lien vers un autre paragraphe, une bibliographie etc. Les liens se formant au moment de la transformation du document DocBook, il faut donc que les indications fournies par l’auteur permettent à la transformation de les comprendre et de créer ces liens.

Les balises <link> et <id> permettent de créer des liens internes. Pour cela, on sélectionne l’élément vers lequel on souhaite pointer notre lien. On lui attribut une valeur id que l’on nomme. Il suffit ensuite d’entourer le mot pointant vers ce lien par les balises <link linkend= « nom de l’id »> texte </link>

Eléments d’avertissement

<warning>, <remark>, <caution>, <tip>, <important>, <note> sont des balises d’avertissement. Elles se comportent à peu près toutes de la même façon : Elle produisent en général automatiquement un titre (en français si vous l’avez précisé), hormis la balise <remark> Les balises <caution> et <warning> produisent en général automatiquement un cadre ; Elles nécessitent que leur contenu soit inclus dans un paragraphe, à l’exception de <remark>.

Il existe de nombreuses autres balises que l’on peut consulter sur le site web de Docbook. Voici un exemple de fichier XML contenant une DTD DocBook et reprenant certaines balises que nous avons vues :

Exemple :

01 <?xml version= « 1.0 » encoding= »UTF 8 »?>
02 <!DOCTYPE article PUBLIC « //OASIS//DTD DocBook XML V4.2//EN »
03 « ../docbook/dtd/docbookx.dtd »>
04 <article lang= »fr »>
05 <articleinfo>
06 <authorgroup>
07 <author>
08 <firstname>Hélène</firstname>
09 <surname>Béciri</surname>
10 </author>
11 </authorgroup>
12 <pubdate>Décembre 2008</pubdate>
13 <title> Leçon de pêche avec Hélène Béciri </title>
14 </articleinfo>
15
16 <!-- Contenu de l’article -->
17 <section>
18 <title>Une bonne canne à pêche</title>
19 <section>
20 <title>La mise de l’appât</title>
21 <!--contenu de la section Les Balises-->
22 </section>
23 <!--contenu de la section Les balises de structure-->
24 </section>
25 </article>

Cet exemple indique au programme que c’est un document XML version 1.0, utilisant un codage de caractère UTF 8. Nous précisons ensuite le type de document, dans la balise DOCTYPE et dans la balise où l’on indique l’attribut langage destiné à déterminer dans quelle langue le document a été écrit. On précise également la DTD que l’on a utilisé pour compiler ce document (nommément DocBook 4.2).
Il ne faut pas oublier de terminer le document par les balises fermées de </set>, </book> ou </article>.

L’élément <authorgroup> permet de définir le groupe d’auteur qui a rédigé la documentation. Chaque auteur doit être contenu dans une balise <author>. Il est possible d’ajouter une adresse email en plaçant l’élément <email> à l’intérieur. L’élément <pubdate> précise la date de publication du document. Le titre du document est signalé par la balise <titre>.  <!-- Contenu de l’article --> est un commentaire indiquant le début de l’article (et donc la fin des méta informations). S’ensuit l’article en question, divisé en sections que l’on peut nommer. Il n’est pas nécessaire de numéroter ces sections car les feuilles de styles XSL le font automatiquement lors de la transformation.

Atteindre le haut de la page

Les balises pour insérer des images

Il est possible d’insérer une image dans un document DocBook. Pour cela, on utilise l’élément <mediaobject> qui permet aux outils de transformation différentes de choisir l’élément (vidéo, image, texte) qui leur convient le plus.

Les balises servant à la création d’entités

Il est possible de partager son document DocBook en plusieurs entités afin d’avoir des petits documents plus faciles à manipuler.
Il suffit de déclarer les sous documents comme entité dans le document principal :

Exemple :

01 <?xml version= »1.0 » encoding= »ISO88591 »?>
02 <!DOCTYPE article PUBLIC « //
OASIS//DTD DocBook XML V4.2//EN”
03 « ../docbook/dtd/docbookx.dtd » [
04 <!ENTITY Leçon de pêche ave Hélène Béciri SYSTEM « Leçon de pêche avec Hélène Béciri.xml »>
05 <!ENTITY Leçon de pêche ave Pascal Cabaud SYSTEM « Leçon de pêche avec Pascal Cabaud.xml »>
06 ]>
07 <article class=”whitepaper” lang=”fr”>
08 <articleinfo>
09 <authorgroup>
10 <author>
11 <firstname>Hélène</firstname>
12 <surname>Béciri</surname>
13 </author>
14 </authorgroup>
15 <title>Leçon de pêche avec Hélène Béciri</title>
16 </articleinfo>
17 &presentation;
18
19 &environnement;
20 </article>
Un sous document pouvant s’écrire :
01 <?xml version= »1.0 » encoding= »ISO88591 »?>
02 <section>
03 <title>Leçon de pêche ave Pascal Cabaud</title>
04 <para>...</para>
05 </section>

Atteindre le haut de la page

Transformation

La transformation d’un document DocBook peut représenter une difficulté pour les novices qui débutent dans le XML. Ces difficultés, d’ordre technique (informatique) peuvent être rapidement résolue en ayant recours à l’un des nombreux logiciels de conversion proposés sur le marché.

Par exemple, nous pouvez utiliser ABC Amber XML Converter (compatible sur Windows), qui propose de convertir votre document XML en divers formats (PDF, HTML, RTF, TXT ANSI, TXT Unicode, DOC, etc.), rapidement et facilement, tout en proposant l’option d’intégrer vos feuilles de style XSL.

Sinon, pour les plus confirmés qui utilisent Linux, il est possible d’utiliser les programmes db2dvi, db2html, db2pdf, db2ps et db2rtf. Il suffit alors de taper la commande suivie du nom du document DocBook.

Les formats obtenus sont les suivants : 

Mais attention! Certes la DTD XML Docbook permet d'écrire des documents structurés ayant une forte valeur sémantique, mais une fois le document écrit, tous les formats dans lesquels vous souhaiterez transformer votre document ne seront pas en mesure de garder cette forte valeur sémantique.

Retourner à l'Historique	Atteindre le haut de la page	Voir les Sources