DocBook est de montrer comment construire le contenu d’un document conformément aux spécifications de cet outil. Les trois premiers articles de cette série ayant montré la manière de générer les formats HTML et PDF d’un document DocBook, on verra dans cet article comment créer le contenu lui même. Cet article fait partie d’une série qui traite de l’utilisation de DocBook et qu’il convient de lire dans l’ordre indiqué:
- Installation et utilisation de base
- Utilisation avancée et amélioration de la présentation en HTML
- Utilisation avancée et amélioration de la présentation en PDF
- Cet article: Créer le contenu du document
Présentation
Le fichier du contenu DocBook est un document au format XML qui correspond à la DTD DocBook. Qui dit format XML, dit une hiérarchie d’éléments XML structurée en arbre. Ces éléments sont délimités par des balises XML et la structure doit correspondre exactement à ce qui est défini par la DTD. La DTD (Document type definition) étant un ensemble de règles qui définissent le contenu du document et sa structure. Un tel document est dit valide et bien formé.<racine param1="..." param2="..."> <niveau1a> ...... </niveau1a> <niveau1b> <niveau2a> ...... <niveau3a> ...... </niveau3a> <niveau3b param1="..."> ..... </niveau3b> <niveau3c> ...... </niveau3c> </niveau2a> <niveau2b> ...... </niveau2b> </niveau1b> </racine>Dans cet exemple l’élément « racine » est la racine de l’arbre qui constitue le document. Cet arbre contient deux éléments de niveau 1:
- « niveau1a”: élément final qui ne contient que des données (matérialisées par 6 points) et aucun élément.
- « niveau1b »: contient deux éléments:
- « niveau2a »: contient trois éléments:
- des données et aussi « niveau3a », « niveau3b » et « niveau3c » qui sont des éléments finaux.
- « niveau2b »: élément final.
- « niveau2a »: contient trois éléments:
L’en-tête et l’élément racine
Un canevas vide d’un document DocBook doit ressembler à ce qui suit:<?xml version="1.0" encoding="utf-8"?> <!DOCTYPE article PUBLIC "-//OASIS//DTD docbook XML V5.0b5//EN" "http://www.oasis-open.org/docbook/xml/5.0b5/dtd/docbook.dtd"> <article xmlns='http://docbook.org/ns/docbook' version='5.0' xml:lang='fr'> </article>
- La première ligne est la déclaration de la nature XML du document et de l’encodage de son contenu. Dans l’exemple on utilise « UTF-8 » dont l’usage systématique est fortement conseillé.
- La deuxième ligne référence la DTD utilisée par le document. le tag de cette déclaration doit correspondre au nom de l’élément racine. Dans l’exemple c’est « article » qui est utilisé.
- La troisième et la quatrième lignes sont les balises d’ouverture et de fermeture de l’élément racine. L’ensemble du contenu du document doit se trouver entre ces deux balises. Les paramètres de cet élément sont:
- xmlns: la référence du namespace DocBook, utiliser l’URL indiquée.
- version: la version de DocBook, actuellement la dernière version est la 5.0
- xml:lang : Positionne la langue du document. On utilise un code ISO 639-1 à deux lettres pour définir ce paramètre. Il détermine principalement la langue des termes introduits automatiquement par DocBook dans le contenu, comme: « Table des matières » ou « Chapitre ». Il détermine également l’orientation du texte pour les langues qui s’écrivent de droite à gauche comme l’Arabe ou le Persan.
Informations à propos du document
C’est l’élément articleinfo (pour un livre il faudra utiliser bookinfo) qui contient ces informations. Il s’agit du titre, des auteurs, des contributeurs, de la date de publication, du résumé et des mots-clé. Dans la pratique, et ceci est valable pour tous les éléments DocBook, on choisit seulement les rubriques estimées utiles pour le document, aucune n’étant obligatoire. Concrètement pour notre exemple, il faudra insérer dans le canevas vide ce qui suit:<articleinfo> <title>Comment débuter avec DocBook</title> <authorgroup> <author> <firstname>Meddeb</firstname> <surname>Abdelhamid</surname> <affiliation> <address><email>a@meddeb.net</email></address> </affiliation> </author> <author> <firstname>Dupond</firstname> <surname>Nathalie</surname> </author> </authorgroup> <othercredit> <firstname>Durand</firstname> <surname>Michel</surname> <contrib>Illustration</contrib> </othercredit> <pubdate>25/02/2018</pubdate> <abstract> <para>Présente de manière simplifiée la création du contenu d'un document DocBook.</para> <para>Texte integral à consulter <ulink url="http://tutoriels.meddeb.net/docbook-installation-utilisation-de-base">sur ce le blog de l'un des auteurs</ulink>.</para> </abstract> <keywordset> <keyword>DocBook</keyword> <keyword>Contenu</keyword> </keywordset> </articleinfo>Cela donne le résultat suivant en PDF:
Le corps du document
Le corps d’un document DocBook est constitué d’une succession de sections: élément « section ». Chaque section peut contenir un nombre quelconque de sous-sections qui ne sont en réalité, elles-mêmes, que des sections. Une sous-section est donc une section fille contenue dans une section mère. La profondeur d’imbrication ainsi constituée pouvant être quelconque. Par ailleurs, une section (ou sous-section) est composée d’un nombre quelconque de paragraphes: élément « para ». L’exemple suivant montre un contenu avec deux sections, dont l’une d’entre elles possède plusieurs sous-sections.<section>
<title>Titre de la première section</title>
<para>
Le corps d'un document DocBook est constitué d'une succession de sections: élément « section ».
La section suivante sera une section qui possède plusieurs sous-sections.
</para>
</section>
<section>
<title>Titre de la deuxième section</title>
<para>
Chaque section peut contenir un nombre quelconque de sous-sections qui ne sont en réalité, elles-mêmes, que des sections. Une sous-section est donc une section fille contenue dans une section mère.
</para>
<section>
<title>Titre de la sous-section de niveau 1</title>
<para>
Chaque section peut contenir un nombre quelconque de sous-sections qui ne sont en réalité, elles-mêmes, que des sections. Une sous-section est donc une section fille contenue dans une section mère.
</para>
<section>
<title>Titre de la sous-section de niveau 2</title>
<para>
La profondeur d'imbrication ainsi constituée pouvant être quelconque.
</para>
</section>
</section>
</section>
Ce contenu donne le résultat suivant en PDF:
Citer un code informatique
Pour citer un code informatique dans un document, on utilise l’élément programlisting. L’exemple suivant illustre cette utilisation:<programlisting>
#include <stdio.h>
#include <stdlib.h>
int main(int argc, char *argv[])
{
printf("Hello world!");
}
</programlisting>
Ce contenu donne le résultat suivant en PDF:
Insérer une citation
Pour insérer une citation, on utilise l’élément quote.<title>Le logiciel libre</title> <para> <quote lang="en">Steve Jobs, le pionnier qui a rendu la notion de prison informatique appréciée, est mort. Son invention était de priver les crétins de leur liberté.</quote> </para> <para> Richard Stallman, 6 octobre 2011. </para>Ce contenu donne en PDF:
Insérer une note de bas de page
Pour ajouter une notre de bas de page, on utilise l’élément footnote.<title>Outils de saisie du contenu DocBook</title> <para> Pour saisir le contenu d'un document au format DocBook, on peut utiliser l'éditeur de texte Emacs <footnote> <para>Le mode nXML d'emacs permet la validation du contenu en fonction de la DTD et aussi la complétion en cours de saisie des balises DocBook</para> </footnote> qui est un outil puissant et souple. Il est particulièrement adapaté à ce type de tâche. </para>Ce contenu donne en PDF:
Noter la numérotation automatique de la note de bas de page et l’insertion du contenu de l’élément footnote en fin de la page.]]>