Créer une documentation en XML

Publié le 24 novembre 2022 par Andrew Owen (4 minutes)

Si votre documentation a atteint les limites de ce qui est possible en Markdown, et que vous préférez ne pas revenir au HTML, il est temps d’envisager la rédaction en XML. Et non, je ne parle pas d’utiliser Microsoft Word et d’enregistrer au format .DOCX. Quel que soit le schéma que vous choisissez (DITA, DocBook, XHTML ou autre), vous bénéficierez des avantages du single sourcing et du structured authoring, ce qui vous fera gagner du temps et de l’argent, surtout si votre documentation est traduite dans d’autres langues.

En 1993, Jean-Yves Belmonte, Olivier Ishacian et Hussein Shafie ont créé Pixware SARL. L’un de ses premiers clients est Renault Sport, qui a besoin d’un logiciel de télémétrie moteur et de banc d’essai. En 2001, ils ont créé une division XML qui, en 2017, est devenue XMLmind Software. Il existe de nombreux éditeurs XML, et j’ai utilisé la plupart des plus connus. Mais l’éditeur XML de XMLmind (XXE) est mon préféré, car lorsqu’il est sorti, c’était le seul qui s’adressait aux rédacteurs plutôt qu’aux développeurs. Avec un éditeur graphique WYSIWYG, vous avez rarement à toucher une balise XML.

J’ai écrit précédemment pourquoi vous devriez considérer DocBook pour vos besoins de documentation (bien que XXE prenne en charge d’autres schémas). Lors de ma participation au projet Mega 65, je n’ai pas réussi à convaincre l’équipe, qui a opté pour LaTeX à la place. Il utilise sa propre forme de balisage à la place de XML, mais il prend en charge la rédaction structurée. Son principal atout est qu’il utilise le système de composition TeX, que Donald Knuth a créé pour composer des formules mathématiques complexes lorsqu’il écrivait “The Art of Computer Programming”.

Mais comparée à DocBook, la chaîne d’outils LaTeX est un casse-tête à utiliser. Et vous pouvez réaliser des formules complexes aussi facilement dans DocBook que dans TeX en utilisant MathML. L’autre raison de la popularité de LaTeX est sa licence de logiciel libre. Mais devinez quoi, XXE est disponible gratuitement pour une utilisation personnelle et open source. Et il est écrit en Java (avec des paquets macOS et Windows pré-intégrés), de sorte qu’il fonctionnera sur n’importe quel système supportant Java 8 ou une version supérieure.

Dans le cadre de la licence, l’utilisation personnelle désigne tout document dont vous êtes le seul détenteur des droits d’auteur. Vous pouvez également utiliser librement XXE Personal Edition si vous créez ou modifiez des documents:

• Pour les logiciels publiés sous une licence open source telle que définie par l’Open Source Initiative.
• Dans le domaine public ou sous licence Creative Commons ou une licence équivalente.
• Appartenant à une organisation non gouvernementale à but non lucratif.
• Au sein d’un établissement d’enseignement dans le but de l’utiliser comme outil d’enseignement.

Si vous n’entrez dans aucune de ces catégories, vous pouvez l’utiliser à titre d’essai pour n’importe quel usage pendant 30 jours. La version commerciale comprend un outil XSL-FO (XML stylesheet formatting objects) pour convertir la source en sorties telles que Microsoft Word. Mais il existe des alternatives gratuites telles que Apache FOP. Personnellement, j’utilise ASCIIdoctor fopub, qui est basé sur Apache FOP. Il dispose d’une feuille de style par défaut pour le PDF qui est facile à modifier.

Je ne veux pas faire une plongée profonde dans la puissance du XML, mais je vais mentionner quelques outils utiles tirés de mon article précédent sur DocBook:

• XPath vous permet de naviguer dans l’arbre d’un document XML et de sélectionner les nœuds qui correspondent à un ensemble donné de critères.
• XPointer est comme XPath pour les médias.
• XInclude vous permet d’assembler un document XML à partir d’autres documents XML, y compris des traductions ou du texte standard.

Et mon dernier argument en faveur de la rédaction XML est que, avant que nous n’utilisions tous Git, tous les systèmes de contrôle de source que j’ai utilisés détruisaient les documents, mais semblaient capables de gérer XML. Il existe d’excellents systèmes de gestion de contenu. Mais si vous disposez de ressources limitées, vous pouvez facilement gérer des documents XML dans un dépôt de code normal.