Le format Docbook est un des plus utilisés
pour la documentation technique, notamment dans
la secteur informatique. La très grande
majorité des grands logiciels
libres utilisent Docbook. Ce format est très riche, avec
plusieurs centaines d'éléments possibles. Malgré cette richesse, on a
parfois besoin d'ajouter des élements ou bien d'effectuer d'autres
adaptations locales à une organisation ou un projet. Comment faire
avec Docbook ?
Les avantages de Docbook sont évidents : format ouvert, indépendant de tout vendeur,
exprimé sous forme de schéma XML pour profiter
des outils XML existants et pouvoir être traité par des outils divers
comme les VCS (contrairement aux formats
binaires), Docbook s'est largement imposé. Mais chaque projet ou
chaque organisation ressent parfois le besoin
d'adapter le format standard et cet article
expose la façon de le faire, pour le Docbook fondé sur les
DTD (jusqu'à la version 4 incluse ; ensuite, à
partir de la version 5 - publiée en 2008, Docbook
utilise un langage de schéma bien plus perfectionné,
RelaxNG, qui change nettement les choses).
Bien sûr, Docbook est un format ouvert, on peut tout simplement
prendre les sources du schéma et les éditer. Mais, en procédant ainsi,
on sort vraiment de Docbook et on aura du mal, par exemple, à intégrer
les modifications futures. Il vaut donc mieux étendre Docbook de la
manière « prévue pour ».
Pour prendre un exemple concret, on veut citer souvent, dans son
document écrit en Docbook, les RFC. XML n'offrant hélas pas de macros, la méthode correcte est
d'ajouter un élément<rfc>. Pour cela, on écrit une DTD qui
définit cet élément :
]]>
Ici, l'élément est défini comme n'ayant pas de contenu
(EMPTY) et prenant un attribut obligatoire,
num, le numéro du RFC. Cela permet d'écrire
<rfc num="5514"/> (mais pas
<rfc>IPv6 over social networks</rfc>,
puisque dans ce cas, num manque et le contenu
n'est pas vide).
Il reste à dire à Docbook que cet élément est acceptable et où on
peut le trouver. Pour faciliter cela, Docbook est réalisé de manière
modulaire et beaucoup de termes DTD ont été définis comme vide, leur
définition permettant de les remplir éventuellement avec des éléments
locaux. C'est le cas du terme local.para.char.mix
qui indique quels éléments supplémentaires peuvent apparaître dans un
paragraphe (<para>). Par défaut, il est
vide, remplissons-le avec notre nouvel élément :
]]>
Désormais, comme local.para.char.mix est
ajouté à la définition des éléments acceptables dans un
<para>, <rfc> est
acceptable (la barre verticale signifie OU BIEN).
Le document doit ensuite indiquer qu'il utilise, non pas le Docbook
standard mais la version étendue. Si l'en-tête avec la version
standard ressemble à :
...
]]>
celui d'un document utilisant notre Docbook adapté à nos besoins
sera :
%dtd_custom;
]>
...
]]>
Maintenant, on peut écrire des documents complets correspondant au schéma
« amélioré » par exemple :
Ceci est un exemple de document Docbook avec une référence à un
(Naming Rights in IETF
Protocols).
]]>
et ils sont validables (ici avec xmllint) :
% xmllint --noout --valid example.db
%
Maintenant, comment les traiter, par exemple pour une transformation
en HTML afin de les servir sur le
Web ? Essayons d'abord avec
XSLT. Les programmes standard ne connaissent
évidemment que les éléments officiels de Docbook et pas notre
addition. Mais XSLT étant modulaire, il est très facile de rajouter un
traitement pour nous :
http://www.ietf.org/rfc/rfc.txtRFC (RFC signifie Request For
Comments. Ce sont les textes fondamentaux de
l'Internet. Toutes les normes Internet sont des RFC, l'inverse
n'est pas forcément vrai. Tous les RFC sont
librement disponibles en ligne sur le serveur de l'IETF, l'organisme
qui les édite. Plus de détails sont accessibles sur le serveur de l'éditeur des RFC.)
]]>
Ce gabarit XSLT traite tout élément nommé
<rfc> et produit de l'HTML avec un lien
vers le serveur Web de l'IETF et, si l'élément
<rfc> est le premier du document (not(preceding::rfc)), un petit
texte explicatif.
Pour les traditionnalistes qui préfèrent DSSSL, une version très simplifiée du code XSLT
ci-dessus (elle est prévue pour l'impression uniquement, sans lien
hypertexte) est :
Un exemple plus complexe vient lorsqu'on essaie d'utiliser
XInclude avec Docbook, par exemple pour inclure une bibliographie. La DTD
complète pour faire cela est :
]]>
Et un éditeur sensible à la syntaxe comme psgml
peut alors éditer le document Docbook contenant les
<xi:include> sans problème.
La documentation de référence sur les adaptations locales de
Docbook est DocBook: The Definitive Guide.