DocBook 5.1 : assemblage de documents et sujets

DocBook 5.1 : assemblage de documents et sujets
pour le langage de balisage sémantique pour la documentation technique

DocBook sert à écrire des documents, comme des livres (d’où son nom), mais principalement de la documentation pour des projets informatiques. Ses objectifs sont donc similaires à ceux de Markdown ou reStructuredText, mais avec une structure et de la sémantique : DocBook est un vocabulaire XML qui définit une pléthore de balises pour capturer le sens du texte. Ainsi, une section est clairement délimitée par un début et une fin (et non implicitement, avec le titre suivant) ; DocBook ne permet pas de mettre du texte en italique, car il peut distinguer entre une mise en évidence (le cas le plus fréquent), un mot dans une langue étrangère (ce qui peut aider un traducteur) ou un titre de livre (afin de générer un lien vers ce livre). Ce format est par exemple utilisé pour la documentation de RedHat.

La version 5.1 du schéma propose deux grandes évolutions. La première facilite la création de documentation modulaire, obtenue en assemblant des documents et en définissant des liens entre eux. Ainsi, si une entreprise vend plusieurs produits très similaires, elle pourra définir un ensemble de documents qui couvre l’entièreté des fonctionnalités de toutes ces variantes ; ensuite, selon le produit, elle pourra en assembler un sous-ensemble.

Le profilage vient à la rescousse si quelques éléments d’un document doivent évoluer d’un produit à l’autre : toutes les variantes peuvent être définies dans un même fichier, simplement marquées comme étant spécifiques à un produit ou l’autre.

La deuxième nouveauté majeure est l’apparition de la notion de sujet. Jusqu’à la version 5.0, toute la hiérarchie d’une documentation DocBook était nommée comme dans un livre : des sections, des chapitres, des livres, des groupes de livres ; les articles étaient prévus pour des documents seuls ; par exemple, il est impossible de définir une section au niveau d’un livre (cela n’aurait pas de sens), mais juste dans un chapitre (ou un article). Avec l’avènement des assemblages, ces notions n’avaient plus beaucoup d’intérêt. Les sujets peuvent s’imbriquer les uns dans les autres sans restriction.

Voir la norme OASIS DocBook 5.1. Tutoriel sur l'assemblage et les sujets.