Docbook semble très utilisé pour les outils Linux (GNOME, Gimp, et plein d’autres). J’ai juste fait quelques essais pour l’instant, mais je suis un peu réticente à écrire directement en XML, même si c’est l’idéal pour séparer vraiment la forme du fond.

Mini-exemple

Un exemple de fichier doc.xml :

<?xml version="1.0" encoding="utf-8"?>
<book xmlns="http://docbook.org/ns/docbook"
      xmlns:xi="http://www.w3.org/2003/XInclude"
      version="5.0">
  <title>LE manuel</title>
  <xi:include href="start.xml">
    <xi:fallback>Désolé : cette partie est manquante !</xi:fallback>
  </xi:include>
</book>

et le fichier inclus start.xml :

<chapter xml:id="start"><title>Par où commencer</title>
<para>TODO: expliquer comment on fait !
</para>
</chapter>

Commandes

Validation

xmlstarlet val --err --xsd /usr/share/xml/docbook/schema/xsd/5.0/docbook.xsd doc.xml

mais ne semble pas gérer XInclude.

Génération HTML

xsltproc /usr/share/xml/docbook/stylesheet/docbook-xsl-ns/html/docbook.xsl doc.xml > doc.html

Attention, si on utilise XInclude, il faut ajouter l’option -xinclude à cette commande.

Génération PDF

xsltproc /usr/share/xml/docbook/stylesheet/docbook-xsl-ns/fo/docbook.xsl gui-doc.xml > book.fo
fop -fo book.fo -pdf book.pdf

Il semble qu’il existe aussi un outil dblatex pour générer su LaTeX, mais je n’ai pas essayé.

Documentation

Références :

le site officiel ;
LE livre : DocBook 5.1: The Definitive Guide, mais se concentre sur le format sans trop parler des outils ;
DocBook XSL: The Complete Guide : à l’air plus détaillé sur comment utiliser les outils ;

Docbook : pour produire de la documentation technique