Documenter un projet

Tout le monde le dit, la documentation est une phase primordiale d’un projet, libre ou non. Cependant, la documentation est aussi un apprentissage difficile, et la pléthore d’options disponible n’améliore pas les choses pour le débutant.

Ainsi, on peut commenter son code de différente manière avec des options spécifiques à javadoc, phpdoc, doxygen ou d’autres encore; écrire les manuels en LaTeX, Texinfo, DocBook, opendocument et un tas d’autres.

Je ne m’étends pas sur le commentaire du code, étant donné que ça dépend beaucoup du langage. Par contre, l’écriture de manuels est encore plus cruciale que la documentation de l’API, et là les options sont légions et certaines peu documentées.

Je suis un fervent utilisateur de Texinfo, qui est un ensemble de macros pour TeX, transformant celui-ci en un outil dédié à la documentation informatique plutôt que scientifique. Texinfo a une syntaxe assez simple avec les commandes qui vont bien pour documenter du code et des logiciels.

Mais Texinfo est un outil ancien avec une documentation solide, mais qui manque d’options de sortie pour les formats à la mode, comme l’ePub. À contrario, DocBook est un système plus récent et basé sur XML et XSLT dont le but est justement de permettre la compilation vers quasiment tous les formats qui vont bien, de MAN aux ePubs et PDF.

Seulement voilà, écrire et lire des sources pour Texinfo est assez pratique, la syntaxe étant conçue pour rester lisible. Ce n’est malheureusement pas le cas de DocBook, qui adopte le très verbeux XML, rendant la lecture bien plus ardue.

Dans mes récents projets, je me suis donc essayé au DocBook, voulant bénéficier des sorties ePub etc. Mais force m’est de constater le faible avancement de ma documentation, dûe à la courbe d’apprentissage et la difficulté de lecture. Je me suis donc mis à la recherche d’un convertisseur Texinfo vers DocBook, ce qui me permettra ensuite de bénéficier de tous les formats de sortie de DocBook, tout en gardant une syntaxe lisible. Quelle ne fut donc pas ma joie (et surprise) de constater que Texinfo peut déjà sortir du DocBook, lequel peut ensuite être converti en ePub ou n’importe quoi d’autre. Il suffit pour cela d’utiliser la ligne de commande suivante:

makeinfo --docbook

DocBook connait aussi Texinfo, et j’ai donc essayé de convertir mon travail avec la commande:

docbook2texi

Malheureusement, cela n’a pas fonctionné. Je me suis retrouvé face à une miriade d’insultes de la part du parseur ou convertisseur XSLT de docbook. Heureusement je n’avais pas encore tapé beaucoup de pages et j’ai donc pu faire la conversion à la main. Un peu décevant malgré tout.

Plus besoin d’écrire et lire de l’XML affreux, et j’ai ainsi pu retrouver mes habitudes. L’inconvénient étant bien sûr une chaine de compilation plus longue pour certains formats, mais un bon Makefile permet de résoudre ça efficacement.