Il est pricipalement composé de chapitres (chapter), de sections (sect1,sect2,sect3, etc ...) et de paragraphes (para).

Par exemple si l'on veut créer deux chapitres avec deux sous-sections dans le second chapitre, on obtiendra le document suivant :

<book lang="fr">
<chapter id="chapitre1">
	<title>chapitre 1</title>
	<para>Paragraphe 1 du chapitre 1</para>
	<para>Paragraphe 2 du chapitre 1</para>
</chapter>

<chapter id="chapitre2">
	<title>chapitre 2</title>
	<sect1>
		<title>Titre de la section</title>
		<para>Paragraphe 1 de la section 1 du chapitre 2</para>
		<para>Paragraphe 2 de la section 1 du chapitre 2</para>
	</sect1>
	<sect1>
		<title>Titre de la section</title>
		<sect2>
			<title>Titre de la sous-section</title>
			<para>Paragraphe 1 de la section 2 du chapitre 2</para>
		</sect2>
	</setc1>
</chapter>
</book>

Le document article est un sous ensemble du document book. On ne trouvera donc pas d'élément chapter, par contre on retrouve sect1 et sect2 ainsi que para. Il suffit donc de se reporter au paragraphe précédent pour avoir plus d'informations. Je vous conseille tout de même d'utiliser book dès que le document fait plus de 2 ou 3 pages.

Cette balise permet de mettre du texte en valeur. Par exemple, dans ce cas, il à été mis en italique, mais il aurait pu être mis en gras, en script, .... tout cela dépend de la feuille de style.

Il existe principalement deux sortes de lien hypertexte : les liens internes au document ou les liens externes.

Pour un lien externe (vers une URL), on utilise la balise ulink. Cette balise ressemble comme deux gouttes d'eau à la balise a href="" du HTML. Par exemple, pour un lien vers la page d'acueil du Mirabellug on peut faire ainsi :

<ulink url="http://www.mirabellug.org/">le site du mirabellug</ulink>

Pour les liens internes, il faut définir un nom pour l'entité cible (un id) et ensuite faire le lien en faisant une réference à cet id. En pratique, si je veux faire un lien vers un exemple (ou n'importe quelle autre entité Docbook), je doit le définir de la manière suivante :

<example id="example-xref1">

Pour pouvoir ensuite faire un lien vers cet entité, il suffira de faire :

<example id="example-xref1">
[...]
<para>
	Vous pouvez revoir l'<xref linkend="example-xref1" />
</para>

On remarque que le texte du lien est géré par défaut par l'outil de conversion et dépend de la cible. Si la cible possède un attribut xreflabel, la valeur de cet attribut est utilisée comme texte du lien.

<example id="example-xref2" xreflabel="exemple d'utilisation de xreflabel">
[...]
<para>
	Vous pouvez revoir l'<xref linkend="example-xref2" />
</para>

On peut enfin utiliser la balise link, qui est un peu une combinaison des deux précédantes.

<para>
	Vous pouvez revoir l'<link linkend="example-xref2">exemple numéro 2 </link>.
</para>

La balise example est utilisée pour donner des exemples, ceux-ci seront alors automatiquement numérotés. Une contrainte cependant : vous êtes obligé de définir un titre juste après avec la balise title et au moins un élément de contenu (comme un paragraphe). Le titre sera également utilisé pour générer la table des exemples en dessous de la table des matières.

<example>
	<title>Un exemple</title>
	<para>Le texte de l'exemple</para>
</example>

Cela donnera donc :

Elle sert à pouvoir inclure une commande dans le code.

Par exemple : la commande ls permet de lister le contenu d'un répertoire.

Cette balise est utilisée pour représenter les noms de fichier ou de répertoires. La sortie donne quelque chose comme ca : /etc/passwd.

Pour préciser qu'il s'agit d'un répertoire, on peut utiliser filename class="directory".

Cette balise est utilisée pour représenter les variables d'environement comme par exemple SGML_CATALOG_FILES.

La balise screen est utilisée pour représenter une interraction avec un shell, en dehors des interfaces graphiques. La balise prompt sert à afficher le prompt, la balise userinput les entrées de l'utilisateur et la balise computeroutput le résultat de la commande. Voici un exemple simple d'utilisation de ces balises :

<screen><prompt>[furax@localtux]$ </prompt><userinput> rpm -qa | grep sgml</userinput>
<computeroutput>sgml-common-0.2-4mdk
docbook-dtd41-sgml-1.0-3mdk
sgml-tools-1.0.9-19mdk
</computeroutput></screen>

[furax@localtux]$  rpm -qa | grep sgml
sgml-common-0.2-4mdk
docbook-dtd41-sgml-1.0-3mdk
sgml-tools-1.0.9-19mdk

On utilise souvent aussi à l'intérieur la balise programlisting pour décrire du code source. Par exemple, dans ce document j'utilise très souvent cette balise.

<programlisting>
int main(int argc, char *argv[])
{
	printf("hello world\n");
	exit(-1);
}
</programlisting>

Attention, si votre code contient des balises intérprétables pas le processeur XML, il faudra protégé votre code.

Vous pouvez échapé les < et > : en utilisant respectivement les entités &lt; et &gt;.

Une autre solution est d'utiliser la construction <![CDATA[ ... ]]> :

<programlisting><![CDATA[
<code><xml><bidon>
]]</programlisting>

<code><xml><bidon>

Cette balise permet de faire une liste d'élements précedés par un petit cercle pour énumérer des éléments par exemple. Chaque élément doit être encadré par la balise listitem

<itemizedlist>
	<listitem>
		<para>Premier élément de la liste</para>
	</listitem>
	<listitem>
		<para>Deuxième élément de la liste</para>
	</listitem>				
</itemizedlist>

Le résultat produit est le suivant :

Cette balise ressemble un peu à la précédente et va permettre de décrire une liste d'évènements ordonnés. Attention, il semble qu'il ne faille pas être déjà à l'interieur d'une balise para pour l'utiliser. Chaque étape de cette procédure sera encadrée par la balise step.

Par exemple si l'on veut illustrer la compilation et l'installation de gcompte :

<procedure>
	<step>
		<para>Décompresser l'archive :
<screen>
<prompt>[furax@localtux]$ </prompt><userinput> tar -zxvf gcompte-0.3.8.tar.gz</userinput>
</screen>
		</para>
	</step>
	<step>
		<para>Puis on lance <command>configure</command> et on compile le programme :
<screen>
<prompt>[furax@localtux]$ </prompt><userinput>cd gcompte-0.3.8</userinput>
<prompt>[furax@localtux]$ </prompt><userinput>./configure</userinput>
<prompt>[furax@localtux]$ </prompt><userinput>make</userinput>
</screen>
		</para>
	</step>
	<step>
		<para>Ensuite on installe le programme :
<screen>
<prompt>[furax@localtux]$ </prompt><userinput>su</userinput>
<computeroutput>Password: </computeroutput><userinput>secure_pass</userinput>
<prompt>[root@localtux]# </prompt><userinput>make install</userinput>
</screen>
		</para>
	</step>
</procedure>

Ce qui va donner le résultat suivant :