Cet article ne peut se substituer à un bon livre sur docbook, surtout que celui d'O'reilly est disponible gratuitement sur internet (http://www.docbook.org pour plus d'informations). Mais comme le code précédent n'est rien d'autre que du docbook, sous-ensemble de SGML, je vais vous en présenter quelques morceaux pour les besoins de base.
La première chose que vous pouvez constater est que ce document est organisé en trois parties. La première commence ligne 7 et finit ligne 54. Ce sont les informations générales, dont le titre, le nom de l'auteur... La seconde partie est très courte : c'est la ligne 56 sur laquelle nous ne reviendrons pas : la balise <lt;toc> ne sert à rien d'autre qu'à mettre une table des matières (Table Of Contents). La troisième démarre ligne 58 et finit ligne 66.
Dans ce noeud, la balise <authorgroup> définit les auteurs, <copyright> le copyright du document, et <legalnotice> la licence du document. La première est la plus compliquée, et un exemple un peu plus complet se substituera mieux à toute explication :
1 <authorgroup> 2 <author> 3 <firstname>prénom de l'auteur principal de la documentation</firstname> 4 <surname>NOM de l'auteur principal de la documentation</surname> 5 <affiliation> 6 <address> 7 <email>adresse électronique de l'auteur principal de la documentation</email> 8 </address> 9 </affiliation> 10 </author> 11 <othercredit> 12 <firstname>prénom d'un contributeur éventuel</firstname> 13 <surname>NOM d'un contributeur éventuel</surname> 14 <affiliation> 15 <address> 16 <email>adresse électronique d'un contributeur éventuel</email> 17 </address> 18 </affiliation> 19 <contrib>Description de sa contribution</contrib> 20 </othercredit> 21 <othercredit> 22 <firstname>prénom d'un contributeur éventuel</firstname> 23 <surname>NOM d'un contributeur éventuel</surname> 24 <affiliation> 25 <address> 26 <email>adresse électronique d'un contributeur éventuel</email> 27 </address> 28 </affiliation> 29 <contrib>Description de sa contribution</contrib> 30 </othercredit> 31 </authorgroup>
Vous pouvez mettre autant d'auteurs et de contributeurs que vous le souhaitez. Ici, il n'y a qu'un auteur, mais deux contributeurs.
Pour le copyright et la licence, l'exemple plus haut était clair. Remarquez que le texte est contenu dans des paragraphes, délimités par des balises <para>, balises qu'on retrouve plus bas pour le contenu du document et ses nombreux paragraphes.
Un document peut contenir un certain nombre de chapitres, les uns à la suite des autres. Il est toujours préférable de nommer chaque chapitre avec le tag id de la balise <chapter>. Et le noeud suivant est le titre du chapitre, dans la balise <title>. Puis commencent au choix les paragraphes ou les sections.
Il est possible de diviser un chapitre en sections de niveau 1, elles-mêmes divisées en sous-sections de niveau 2, et on va ainsi jusqu'au niveau 5 inclus. Chaque section contient en premier noeud un titre. Les noeuds suivants sont, au choix, des paragraphes avec un tag <para> ou des sous-sections <sect?>.
Voici quelques tags utiles supplémentaires :
-
<emphasis>: accentue le texte. Le résultat est généralement des caractères gras. -
<programlisting>: permet d'inclure du code qui sera reproduit tel quel -
<xref linkend='identifiant'>: permet de faire un lien hypertexte. En SGML, pas besoin de refermer ce tag. En XML, n'oubliez pas de le refermer, par exemple ainsi :<xref linkend='compilation-ch' />
Pour créer une liste, voici un exemple parlant :
1 <itemizedlist> 2 <listitem><para>Premier item</para></listitem> 3 <listitem><para>Deuxième item</para></listitem> 4 <listitem><para>Troisième item</para></listitem> 5 <listitem><para>Et ainsi de suite</para></listitem> 6 </itemizedlist>
Pour un tableau, je vous recommande la documentation de docbook et l'exemple en ligne sur http://www.docbook.org. Mais voici tout de même un exemple illustratif :
1 <table> 2 <title>Menu de la semaine</title> 3 <tgroup cols=<emphasis>"7"</emphasis>> 4 <tbody> 5 <row> 6 <entry>Lundi</entry> 7 <entry>Mardi</entry> 8 <entry>Mercredi</entry> 9 <entry>Jeudi</entry> 10 <entry>Vendredi</entry> 11 <entry>Samedi</entry> 12 <entry>Dimanche</entry> 13 </row> 14 <row> 15 <entry>des patates</entry> 16 <entry>des patates (!?)</entry> 17 <entry>des patates (encore)</entry> 18 <entry>des patates (c'est comme hier)</entry> 19 <entry>des patates (commence a y en avoir marre ! )</entry> 20 <entry>des patates (vivement la semaine prochaine !!! )</entry> 21 <entry>des patates au beurre (miam)</entry> 22 </row> 23 </tbody> 24 </tgroup> 25 </table>
Vous pouvez visualiser ce que donnent la liste précédente et le tableau précédent sur la figure 1 tel qu'un navitateur à base de gecko (galeon ici) les représentent.
