Revisiter DocBook
Publié le 8 septembre 2022 par Andrew Owen (6 minutes)
La Darwin Information Typing Architecture (DITA) et DocBook sont deux cadres de rédaction basés sur XML. Je préfère de loin DocBook. L’article d’aujourd’hui est une mise à jour d’un article sur le sujet que j’ai initialement écrit pour le numéro du printemps 2011 de Communicator. J’avais peut-être raison, car en 2014, un groupe de spécialistes de la DITA a abandonné la consultation pour créer son propre système de gestion de contenu (CCMS) basé sur DocBook.
En tant que rédacteur technique, je n’ai jamais été un grand fan de la rédaction basée sur XML jusqu’à ce que je découvre XMLmind’s XML Editor. Il vous offre une vue WYSIWYG de votre texte, dispose de raccourcis clavier et vous n’avez que rarement besoin de vous préoccuper des balises. Il est écrit en Java et est gratuit pour une utilisation personnelle et open source. Il peut être utilisé pour DITA ou DocBook, mais l’utilisation de DITA est coûteuse en temps et en ressources ; DocBook, quant à lui, offre presque tous ses avantages sans les inconvénients.
La DITA a maintenant plus de 20 ans. Elle a été créée par IBM pour remplacer son propre langage de balisage de documents basé sur le SGML (Standard Generalized Markup Language). L’Organization for the Advancement of Structured Information Standards (OASIS) définit la DITA comme étant à la fois un ensemble de types de documents pour la création et l’organisation d’informations thématiques et un ensemble de mécanismes pour l’extension et la limitation des types de documents.
La partie Darwin, qui fait référence au naturaliste, représente l’idée d’héritage. Les éléments spécialisés héritent des propriétés des éléments de base. Ce concept est familier aux développeurs, et la DITA peut être considérée comme un système de rédaction orienté objet. La partie sur le typage de l’information fait référence à la rédaction basée sur les sujets. Vous disposez de trois types de sujets pour commencer: concept, tâche et référence. C’est à peu près tout.
La DITA est un cadre qui vous permet de construire une solution et si vous optez pour la DITA, vous devez vous attendre à passer de nombreux mois à construire un système avant de pouvoir commencer à l’utiliser pour rédiger des documents. Pour une entreprise comptant des dizaines de milliers d’employés et des centaines de rédacteurs qui ont besoin d’imposer une structure commune à leurs documents, c’est peut-être une bonne chose.
DocBook a maintenant plus de 30 ans. Il a vu le jour chez O’Reilly & Associates, les éditeurs des omniprésents livres d’informatique dont les couvertures sont ornées de gravures sur bois d’animaux. Il a été conçu pour documenter les systèmes informatiques, mais il est suffisamment souple pour traiter de n’importe quel sujet. Par exemple, un important éditeur britannique de livres utilise un système basé sur DocBook pour fournir des versions électroniques de ses titres imprimés les plus populaires, allant des livres de cuisine aux guides.
OASIS gère également la norme DocBook et explique son objectif de la manière suivante:
Presque tous les matériels et logiciels informatiques développés dans le monde ont besoin d’une certaine documentation. La plupart du temps, cette documentation présente une structure similaire et un large noyau d’idiomes communs. La communauté bénéficie d’un vocabulaire standard, ouvert et interchangeable pour rédiger cette documentation. DocBook a été conçu, et continuera à l’être, pour répondre à cette exigence.
Le SGML a été introduit pour résoudre un certain nombre de problèmes de documentation, mais sa principale caractéristique est la séparation du contenu et du style. Pour ce faire, il utilise des balises, des termes descriptifs entre crochets, qui entourent le texte brut. Ces balises sont interprétées par une application qui crée une version formatée du document. XML et HTML sont tous deux dérivés, au moins en partie, d’une version simplifiée de SGML. Mais contrairement au HTML, le XML doit être bien formé, c’est-à-dire que les balises d’ouverture doivent avoir des balises de fermeture correspondantes au bon endroit. Le XHTML était une tentative de rendre le HTML bien formé, mais il a perdu le concours de popularité au profit du HTML5.
Ce qu’il y a de bien avec XML, c’est que vous pouvez effectuer des transformations à l’aide de XSLT (un sujet que j’ai déjà abordé) pour produire d’autres documents XML, du HTML, du texte brut ou des feuilles de style eXtensible Stylesheet Language:Formatting Objects (XSL-FO). Les processeurs d’objets de formatage tels que Apache FOP ou RenderX peuvent créer un PDF à partir d’un fichier XSL-FO. J’utilise ASCIIdoctor FOP.
Si vous utilisez DocBook pour créer un document imprimé, vous aurez besoin d’une bonne feuille de style XML. Heureusement, DocBook fournit une bibliothèque de feuilles de style. L’édition des feuilles de style était autrefois une véritable plaie. Mais il existe maintenant des éditeurs graphiques de feuilles de style tels que Altova Stylevision et Arbortext Styler. Les solutions DocBook basées sur le cloud comprennent généralement un éditeur de feuilles de style.
Sans entrer dans une discussion approfondie sur le XML, je voudrais mentionner quelques outils qui peuvent être utiles pour le single-sourcing et la localisation:
Ces documents peuvent être utilisés pour prendre en charge les principales caractéristiques d’un système de documentation moderne (internationalisation, localisation et rédaction collaborative), la source étant contenue dans un référentiel unique. Dans mon expérience avec DITA, j’ai dû cloner le référentiel de documents principal pour chaque traduction. L’autre raison pour laquelle la DITA a été préférée au DocBook était la création basée sur les sujets, mais elle est prise en charge dans le DocBook 5 depuis plus de dix ans.
Si votre outil de documentation actuel répond à vos besoins, restez-y. Vous pouvez utiliser DITA pour le single-sourcing, mais vous devrez d’abord réimplémenter le riche jeu de balises de DocBook, puis créer les feuilles de style à partir d’un point de départ beaucoup plus rudimentaire. Si quelqu’un vous suggère d’adopter la DITA, vous devriez sérieusement envisager d’utiliser DocBook à la place. À moins que vous n’envisagiez de créer un système personnalisé dès le départ, DocBook vous permettra d’obtenir les mêmes résultats que DITA dans un délai plus court et à un coût nettement inférieur.
J’ai récemment vu un article de blog du responsable du marketing produit d’une société qui vend un éditeur de documents basé sur le XHTML que j’ai utilisé à l’occasion et qui a récemment fait l’acquisition d’un CCMS DITA. Pour des raisons juridiques, je vais supposer que vous savez de quelle société je parle, mais ce n’est pas vraiment important. En toute honnêteté, je pense que cet article est une véritable hache de guerre contre DocBook, qui tente de se faire passer pour une comparaison objective. Je me suis demandé si j’avais été juste envers DITA dans cet article, mais je pense que je l’ai été. J’ai utilisé des produits basés sur la DITA provenant de divers fournisseurs dans un certain nombre d’entreprises. Et à chaque fois, j’aurais préféré utiliser DocBook.