Ce sont pour moi les deux gros avantages de DocBook:
Enfin un vrai langage structuré pour écrire de la documentation. Tous les "concurrents", markdown et compagnie, sont en fait plus proches de HTML, très orientés formatage du texte. DocBook permet vraiment de gérer de grosses bases de documentation et de faire du vrai hypertexte (non seulement des liens, mais aussi de la recherche, des indexs, etc), et de vraiment séparer le rendu du contenu.
Il utilise XML, avec tous les outils qui vont autour. En particulier, XSLT avec des stylesheets pour générer à peu près tout et n'importe quoi et qui sont facilement personnalisables.
Et aussi les deux gros défauts:
- DocBook fait trop de choses. Il y a plusieurs centaines de balises, ce qui peut le rendre assez compliqué à manipuler quand on part de rien (si on fait des changements dans des documents existants, je pense que ça se passe mieux)
- Il utilise XML, qui n'est pas la syntaxe la plus facile et confortable pour les humains. Et mettre en place la toolchain n'est pas toujours simple. DocBook vers HTML, ça va, mais DocBook vers PDF, il faut passer par LaTeX ou fop, qui sont tous les deux assez "usine à gaz". Mais l'idée de fop est pas mal (c'est un genre de concurrent à postscript, mais en XML).
Bref, avec les bons outils, ça marche bien une fois que c'est mis en place.
Et pour le "pas très connu": je crois que gtkdoc repose aussi sur docbook. En fait il est partout, mais il marche tellement bien que ça se voit pas!
[^] # Re: Sphinx
Posté par pulkomandy (site web personnel, Mastodon) . En réponse au journal DocBook ou l'art d'écrire de la documentation. Évalué à 7.
Ce sont pour moi les deux gros avantages de DocBook:
Et aussi les deux gros défauts:
- DocBook fait trop de choses. Il y a plusieurs centaines de balises, ce qui peut le rendre assez compliqué à manipuler quand on part de rien (si on fait des changements dans des documents existants, je pense que ça se passe mieux)
- Il utilise XML, qui n'est pas la syntaxe la plus facile et confortable pour les humains. Et mettre en place la toolchain n'est pas toujours simple. DocBook vers HTML, ça va, mais DocBook vers PDF, il faut passer par LaTeX ou fop, qui sont tous les deux assez "usine à gaz". Mais l'idée de fop est pas mal (c'est un genre de concurrent à postscript, mais en XML).
Bref, avec les bons outils, ça marche bien une fois que c'est mis en place.
Et pour le "pas très connu": je crois que gtkdoc repose aussi sur docbook. En fait il est partout, mais il marche tellement bien que ça se voit pas!