DocBook

Un article de Agora2ia.


duckhead.png


Sommaire

Présentation

En une phrase

...


Plus précisément

Apparu en 1991, DocBook est initialement une DTD (relativement volumineuse) facilitant l'édition de documents au départ SGML, puis XML. Elle s'est depuis imposée comme standard, notamment dans le monde de l'édition, ce qui n'est pas étonent puisque DocBook a été initié par O'Reilly.


DocBook est une technologie, comme XML, et non un outil, comme Notepad ou UltraEdit.


On parlera de la DTD DocBook ou du Schéma DocBook pour identifier « la définition, la description de DocBook », le document contenant la liste des balises et comment elles s'agencent les unes par rapport aux autres.


Mais cette DTD n'a de sens si elle utilisée pour guider la création, contrôler l'édition d'un document, notre document, celui qui contient le texte, les informations que l'on souhaite formaliser ou diffuser : c'est ce que l'on appelle l'article, le fichier XML DocBook ou encore document DocBook.


Comme tout document XML, un document DocBook ne contient aucune information de mise en forme, mais uniquement des informations, du texte.

En effet, il s'agit d'un ensemble de balises telles que <book> <article> <author> <copyright> <section> <title> <para>...


Cette DTD, utilisée conjointement avec des outils adaptés, permet donc de s'assurer que l'on construit un document XML bien formé (voir l'article sur XML pour connaître la différence entre « valide » et « bien formé »).

J'ai dit « initialement une DTD », car depuis peu, le schéma XSD existe également.


Ce standard visant à prendre en compte l'ensemble des besoins en terme d'édition de document, du corpus en plusieurs volumes au simple article, il contient énormément d'éléments, rendant sa structure assez complexe. Afin de pouvoir répondre aux besoins élémentaires propres à la rédaction d'un simple article (qui est le document le plus souvent utilisé), une DTD plus simple est apparues plus récemment : Simplified DocBook. Elle s'adresse donc aux utilisateurs qui souhaitent tiré profit de DocBook sur un document restreint sans subir la complexité de DocBook.


Autour de ces deux pierres angulaires, existe un ensemble d'outils précieux (feuilles XSL, documents DSSSL, ...) qui permettent d'utiliser les documents XML DocBook créés afin de produire des documents finaux plus élaborés, tels que des pages HTML (pour de la consultation en ligne), des PDF (version complète, autonome, téléchargeable du document), des slides... C'est là une autre force de DocBook.


DocBook fourni donc :

  1. un standard qui guide et structure l'édition d'un document (gage de pérénité étant donné l'ampleur de DocBook et le travail fourni pour abouir à ce résultat : version 4.5 d'une norme établie par plusieurs industriels du secteur !)
  2. et aussi des outils qui permettent de mettre en oeuvre rapidement et simplement ce standard.


Comme nous l'avons dit, il existe une version de DocBook pour SGML et une pour XML : c'est cette deuxième version que nous allons aborder au cours de cet article.


Pourquoi utiliser DocBook ?

La principale caractéristique d'un document DocBook est d'être au format XML. Cela lui confère d'entré deux avantages majeurs :


  1. Tout d'abord, il est ainsi facile de valider sa structure de bas niveau (valide) et celle de haut niveau (bien formé).
  2. Ensuite, en terme de gestion de versions, il peut être intégré à un gestionnaire de version comme un fichier texte, ce qui rend facile l'audit et la comparaison entre deux versions.
  3. Autre avantage de DocBook, c'est l'ensemble des outils qui gravitent autour de lui, et qui permettent d'obtenir quasiment tous les formats de sortie : HTML, PDF, RTF, XML, texte brut... Et même des formats qui n'existent pas encore ! Ce qui fait de DocBook un format d'entré pertinent, qui tire à lui de nombreux autre outils.
  4. En tant que format XML, DocBook a cet avantage de disscoier le fond de la forme pour ne s'occuper que du fond. Cela permet à son auteur de concentrer ses éfforts et son attention sur le contenu, la transcription de son savoir, de sa compétence, et de reporter, voire déléguer la mise en page, éventuellement à une personne dont c'est la spécialité.

DocBook est ainsi une bonne solution pour des fiches (techniques ou commerciales), des documents de référence (guides techniques ou méthodologiques) ou des modèles (document de spécifications, de conduite de projet), qui sont autant de documents que l'on pourra aisément remettre en page selon la nouvelle charte graphique de la société, ou celle du client auxquels ils sont dédiés, mais aussi déclinés en différents formats de diffusion, selon les besoins et contraintes des clients.


Si l'on prend par exemple l'outil de construction de projet Maven, ce dernier possède son propre format XML (nommé XDOC) pour écrire la documentation du projet, qui est ensuite utilisé par Maven pour générer le site du projet mais aussi un PDF si besoin. Les créateurs de Maven ont privilégié ce format pour sa simplicité en regard de DocBook. Cependant, il existe un plugin dans Maven qui permet de générer du xdoc ) partir de DocBook.


Utilisation

Cas d'utilisation

Il serait présomptueux, voire maladroit, de dire ce qui nécéssite d'être documenté : cela dépend du client (système, compétence, exigences...), des contraintes et impératifs du projet, de la méthodologie. Aussi ce chapitre s'efforce uniquement d'identifier des cas d'utilisation où DocBook paraît indiqué.


Comme nous l'avons dit, le document XML DocBook est le fichier d'entré qui devra subir différentes transformations en fonction du format final souhaité.


Tout d'abord il devra être valider, afin de garantir qu'il est conforme à la DTD DocBook :

  • Soit via un validateur externe si votre éditeur à des fonctionnalités restreintes concernant XML
  • Soit via l'éditeur (au moment de l'édition) lorsqu'il est plus évolué.


Une fois le document DocBook valider, on peut l'utiliser et le transformer sans crainte.

  • Comme tout fichier XML on pourra l'utiliser "programmatiquement" via une API SAX et/ou DOM, pour par exemple extraire l'adresse mail de l'auteur afin de lui envoyer un mail. Etant donné que DocBook est orienté édition, cette utilisation restera le plus souvent marginale.
  • Très souvent, le fichier DocBook sera transformé soit en un fichier texte brut, soit en un autre fichier XML et notamment xHTML. Pour ce faire on utilise une feuille XSL qui, pour une balise du document DocBook (et son contenu), indique quel doit être le résultat à produire (balise(s) supprimée(s)/modifiée(s) et/ou contenu modifié/supprimé). Encore une fois, cette transformation pourra se faire :
    • soit via un moteur XSL externe, soit via celui d'un éditeur XML évolué,
    • en utilisant soit une des feuilles XSL qui accompagnent DocBook, soit une de votre cru.
  • Mais le plus souvent, le document DocBook aura pour vocation d'être publié au format PDF. Il faudra alors passer par un format XML intermédiaire, mais tout aussi standardisé : XML-FO. Cette transformation se fait également via une XSL, dite XSL-FO, comme celle accompagnant DocBook. On utilisera un moteur de transformation pour générer le PDF à partir du XML-FO. Dans les outils qui accompagnent DocBook, on trouve ainsi 2 XSL-FO, qui permettent de générer deux types de PDF : un format livre classique, l'autre au format présentation appelé slide.
  • La génération permet de produire des éléments déduits comme une table des matières, une table des figures ou un index.


Image:DocBook-output.gif Formats d'export à partir de DocBook


Technologies

Tout document DocBook étant structuré par une DTD ou un schéma XML XSD, on peut très bien utiliser n'importe quel éditeur XML offrant le support DTD ou XSD pour créer et éditer un document DocBook. Certains outils ont cependant intégré DocBook de façon plus approfondie.


Tout d'abord, comment obtenir le document DocBook :

  • Ca peut être le document d'entré, celui saisi et contenant le texte, les informations à formaliser, à diffuser.
  • Mais peut aussi être généré par un outil tiers, chargé par éxemple d'analyser le code. Plus généralement, il peut être un format intermédiaire. On peut avoir saisi le le texte sous un autre format, format qui a ensuite été exporté au format DocBook. Ca peut être depuis un éditeur de texte élaboré, un gestionnaire d'anomalies, un outil de suivi de temps ou encore des fichiers décrivant les spécifications de l'application sous forme de Cas d'utilisation dans un format XML « métier » dédié plus approprié, et transformé en DocBook pour être intégré à un document de référence unique.


Comme tout fichier XML, on peut transformer un document DocBook à l'aide de différents langages de transformations :


Outils

Etant donné la compléxité de DocBook, vous pourrez vous contenter d'un simple éditeur de texte pour débuter, faire quelques éxemples, voire travailler sur des documents simples. Mais la vocation de DocBook étant des documents plus conséquents, vous risquer d'avoir rapidement besoin d'éditeurs plus évolués, qui offrent au moins une coloration synthaxique, et au mieux la complétion automatique, voire contextuelle.


XlmSpy

XmlSpy permet de créer directement un document DocBook. En faisant "nouveau document", XmlSpy propose notamment de créer au choix un des documents DocBook standards. On obtient alors document vide avec les principales balises. XmlSpy offrant différentes vues à l'édition d'un document XML, il peut être très pratique pour l'édition de documents DocBook ; surtout que la version Home Edition, gratuite, offre tous ces services.

Avec la version 2005, il est possible de créer soit un article, soit un book, tout deux dans la version 4.2 de la DTD DocBook. En créant le document, on obtient un fichier XML qui tout d'abord est associé à la DTD, afin que XmlSpy puisse à tout instant valider le document. Ensuite, il y a quelques balises afin de ne pas partir avec un document vide. Une fois le document écrit on pourra transformé le document DocBook en un autre format de sortie (Menu:XSL/XQuery > XSL Transformation), comme par exemple du xHTML ou du HtmlHelp, soit grace aux feuilles XSLfournies avec XmlSpy (répertoire <XMLSPY_HOME>/Stylesheets/docbook/), soit avec sa propre feuille XSL. Il est également possible de transformer le document en XML:FO (Menu:XSL/XQuery > XSL:FO Transformation) : on pourra alors transformer ce fichier de sortie en un fichier PDF.

Voir la page XmlSpy pour plus d'informations.


Eclipse


Microsoft Office

  • Faisabilité ???


OpenOffice

La suite bureautique OpenOffice sauvegarde par défaut ses documents au format XML. Il est donc normal que certains outils soient venus se gréffer autour pour faciliter les interactions entre DocBook et OpenOffice.

Voir la page OpenOffice pour plus d'informations.

Wiki

Les Wiki sont réputés pour la facilité d'édition que procure leur synthaxe simplifiée. De là, il est possible d'envisager deux façons d'interagir entre un Wiki et DocBook :

  • Soit un Wiki dont la syntaxe pour écrire les pages est directement du format DocBook, mais là on perd l'avantage du Wiki pour se lancer dans une édition délicate, obligeant à connaitre la DTD DocBook afin de maîtriser l'enchaînement des balises : qui se sent capable ;o)
  • Soit un Wiki ayant une syntaxe wiki classique, mais qui possède la capacité d'exporter une (des) page(s) au format DocBook : cela aurait un sens dans une chaîne de production de document, mais ne permet pas de versionner le document DocBook : c'est déjà fait pour la page wiki.


Au delà des Wiki, certains GestionnaireDeContenu, qui s'étoffent de plus en plus, peuvent prendre en charge le format DocBook à des degrés variés.


Dans tous les cas, il ne faut pas perdre de vue qu'il est quasi indispensable, étant donné sa complexité, d'avoir une aide à la complétion lorsque l'on édite un document DocBook.


Voir la page Wiki pour plus d'informations.


Maven

L'outil de construction de projet Maven, est capable de générer en standard de nombreux types de livrables, et notamment un site web contenant divers rapports, mais aussi des informations écrites par l'utilisateur. Par défaut, cette documentation doit être écrite au format Maven, à savoir le format xDoc. Cependant Maven laisse la possibilité d'écrire sous tout autre format, à condition que ce format soit transformé en xDoc durant le processus de construction : xDoc est le format central de la documentation dans Maven. Une fois en xDoc, Maven transforme les documents en HTML et/ou en PDF.

Les créateurs de Maven on privilégiés xDoc pour sa simplicité : les balises sont effectivement peut nombreuses, et leur arborescence est relativement simple. En complexité nous ne sommes pas loin du HTML.

Cependant, en standard supporte évidemment DocBook. Il devient donc envisageable de rédiger un document de spécification (par exemple) au format DocBook, en l'intégrant au gestionnaire de version comme tout autre fichier source. Il suffira de paramétrer Maven pour que ce document soit transformé en PDF puis intégré au livrable.

Pour générer un document PDF à partir de DocBook dans Maven, il y a 3 façons de faire :

  • Soit utiliser le plugin Maven pdf. Ce plugin transformant des fichiers au format xDoc, il faudra au préalable écrire sa feuille XSL qui transforme le fichier DocBook en xDoc !
  • Soit utiliser le plugin Maven docbook. Ce plugin transforme un document SimplifiedDocBook en fichier xDoc, puis éventuellement le fichier xDoc en document PDF. L'inconvénient, est que ce plugin ne prend en charge que le Simplified DocBook, et pour l'avoir essayé, certaines balises ne sont pas prises en charge.
  • Soit utiliser le plugin Maven sdocbook. Ce plugin utilise le moteur de transformation Apache FO et les feuilles de style XSL de DocBook pour transofmer un document DocBook directement en fichier PDF.


Note : Pour Maven2 il y aurait le plugin AFAIK inclu dans Doxia [I quickly looked at the Doxia code (by decompiling it), and the DocBook parser has a parseXDoc operation that is being invoked. Internally, it is looking for all sorts of non-DocBook tags, like 'li' instead of 'listitem' etc.]


L'avantage des 2 premières solutions est qu'elles passent par le stade intermédiaire permet éventuellement de générer une version HTML que l'on pourra intégrer au site du projet généré par Maven.

L'avantage de la dernière est d'assurer une compatibilité maximum à la DTD DocBook de par les standards qu'elle utilise, permettant ainsi d'éviter les désagréments que l'on rencontrera certainement avec les 2 premières sur des documents DocBook complexes.


Voir la page Maven pour plus d'informations, et plus particulièrement ArticleMaven#Documentation_et_format_xDoc.


Configuration avec le plugin sdocbook

# -----------------------------------------------------------------------------
# SDocbook
# -----------------------------------------------------------------------------
maven.sdocbook.src.dir=${basedir}/docbook
maven.sdocbook.stylesheets.dir=C:/Dev/tools/docbook/docbook-xsl-1.69.0
  • Créer à la racine du projet le répertoire docbook qui contiendra les documents DocBook.
  • Créer alors votre document en l'associant à la DTD ou au schéma.
  • Lancer une compilation maven : maven sdocbook
  • Ruse pour la dépendance à jimi-1.0.jar : télécharger l'archive jimi1_0.zip à partir de la page http://java.sun.com/products/jimi/ en extraire le fichier Classes... et le renommer jimi-1.0.jar.


Outils en ligne

  • DocBook Online Tools : après avoir uploadé un document DocBook sur leur site, on peut le valider dans premier temps, puis le transformer en HTML ou PDF.



Exemple

Parmi les documents qu'il est possible de créer avec DocBook (livre, article, document), le plus communément utilisé est l'article. Pour cela, on utilisera la balise racine du même nom, et on pourra partir de l'exemple ci-dessous :


(Pour l'adition du document DocBook, on pourra au choix utiliser la DTD Docbook ou le Schéma XML Docbook)


Attention : La DTD DocBook étant complexe, les outils prenant en compte l'intégralité des éléments sont rares. Aussi il vous faudra vérifier le résultat obtenu.


Un article

 <?xml version="1.0" encoding="ISO-8859-1" ?>
 <!DOCTYPE 
     article 
     PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" 
     "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">

 <!-- <!DOCTYPE article PUBLIC " -//OASIS//DTD DocBook V3.1//EN"> -->
 <!-- La ligne ci dessu décrit le document -->
 <!-- On définit la classe et la langue de notre texte -->
 
 <article class="whitepaper" id="un-example" lang="fr">
 
   <!-- On entre d'abord les informations concernant le header, elles
   permetteront entre autre, de retrouver les auteurs, les dates de
   modification, ect -->
   <artheader>
     <title>Premier exemple</title>
     <author>
       <firstname>Xavier</firstname>
       <surname>Nicollet</surname>
       <affiliation><address><email>nicollet@efrei.fr</email></address></affiliation>
     </author>
   </artheader>
   
   <!-- On entre dans la première section -->
   <sect1>
     <title>Première partie</title>
     <para>
       Dans ce paragraphe, j’insère une figure:
       <!-- On verra plus tard d’autres moyens d’insérer des figures -->
       <figure>
         <title>Le logo d’EFREI LINUX:</title>
         <graphic fileref="fig/fig1"> </graphic>
       </figure>
     </para>
 
     <sect2>
       <title> Premiere sous-section </title>
       <para> Les tableaux peuvent être très complexes en docbook, en voici une
         version simple.
       </para>
       <para>
         Voici un tableau simple :
         Une description fictive des caractéristiques du compilateur
         <informaltable frame="all">
           <tgroup cols="4"> <!-- on décrit le nombre de colonnes -->
             <thead> <!-- on passe au "header" du tableau -->
               <row>
                 <entry>Architecture</entry>
                 <entry>Companie</entry>
                 <entry>Code natif supporté</entry>
                 <entry>Optimisation max.</entry>
               </row>
             </thead>
             <tbody> <!-- et on remplit les lignes -->
               <row>
                 <entry>i386</entry>
                 <entry>Intel</entry>
                 <entry>oui</entry>
                 <entry>-O4</entry>
               </row>
               <row>
                 <entry>alpha</entry>
                 <entry>DEC</entry>
                 <entry>oui</entry>
                 <entry>-O3</entry>
               </row>
             </tbody>
           </tgroup>
         </informaltable>
       </para>
     </sect2>
 
     <sect2>
       <title>Une autre sous_section</title>
       <para>Voici une liste:</para>
         <itemizedlist mark=opencircle>
           <listitem><para>Premier point</para></listitem>
           <listitem><para>Deuxième point</para></listitem>
           <listitem> <para>Troisième point</para></listitem>
         </itemizedlist>
     </sect2>
   </sect1>
 </article>
 


Un book

Document composé (ENTITY) et mode de génération chunk.


 <?xml version="1.0" encoding="ISO-8859-1"?>
 <!DOCTYPE book 
     PUBLIC "-//OASIS//DTD DocBook V4.2//EN" 
     "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" 
     [
         <!ENTITY introduction SYSTEM "introduction.xml">
         <!ENTITY developper.avec.copix SYSTEM "developper.xml">
     ]>
 
 <book lang="fr">
     <bookinfo>
         <title>Documentation de Copix</title>
         <authorgroup>
             <author>
                 <firstname>Gérald</firstname>
                 <surname>Croës</surname>
             </author>
             <author>
                 <firstname>Laurent</firstname>
                 <surname>Jouanneau</surname>
             </author>
         </authorgroup>
         <copyright>
             <year>2003</year><holder>Aston</holder>
         </copyright>
     </bookinfo>

     &introduction;
     &developper.avec.copix;

 </book>
 


Les principaux éléments

Afficher les informations en français

Pour faire afficher les informations tels que "Table des matières", "Index", "Figure"... dans la langue de votre choix, il faut préciser cette langue dans l'attribut lang de l'élément racine du document, à savoir article ou book.

<article lang="fr">
</article>


Rendre les choses plus percutantes

<emphasis>Percutant !</emphasis>
Percutant !


Essayer de le mettre en italique si possible

<emphasis remap="it">En italique</emphasis>
En italique


Montrer quelque chose à l’écran

<para><screen>
Quel âge avez-vous ?
10
Vous avez 10 ans.
</screen></para>
Quel âge avez-vous ?
10
Vous avez 10 ans.


Indiquer une commande à tapper

<para>Utiliser la commande <commande>ls</command> pour lister les fichiers de
votre répertoire.
</para>
Utiliser la commande ls pour lister les fichiers de votre répertoire.


Indiquer un email

<para>
Ceci est l’adresse d’EFREI LINUX: <email>efrei-linux@efrei.fr</email>.
</para>
Ceci est l’adresse d’EFREI LINUX: <efrei-linux@efrei.fr>.


Indiquer un nom de fichier

<para><filename>/usr/local/bin/gtk-config</filename></para>
/usr/local/bin/gtk-config


Indiquer une citation

<quote>Use the source, Luke</quote>
« Use the source, Luke »


Indiquer une touche

<keycap>SHIFT</keycap> <keycap>PAGE UP</keycap>
SHIFT PAGE UP


Mettre un commentaire

<!-- Mon commentaire -->
 


Afficher un prompt

<para>
    <screen>
        <prompt>[furax@localtux]$</prompt>
        <userinput>jade -t rtf -d /usr/lib/sgml/stylesheet/</userinput>
    </screen>
</para>
[furax@localtux]$jade -t rtf -d /usr/lib/sgml/stylesheet/


Afficher une variable d’environement

Utiliser la variable <envar>TERM</envar>.
Utiliser la variable TERM.


Plus loin avec les listes

  • Pour ceux qui n’auraient pas suivi, on a déjà parlé des listesla section intitulée La source sgml.
<para>
    <variablelist>
        <varlistentry>
            <term>Fruits:</term>
            <listitem> <para>bananes, pommes, poires...</para></listitem>
        </varlistentry>
        <varlistentry>
            <term>Legumes:</term>
            <listitem> <para>pommes de terres, haricots, ...</para></listitem>
        </varlistentry>
    </variablelist>
</para>
  • Ce qui nous donne:
Fruits:
    bananes, pommes, poires...
Legumes:
    pommes de terres, haricots, ...


Les liens

  • Les liens internes

Si c’est un saut vers le même document, donner un id à l’endroit où l’on veut aller:

<sect2 id="tests">

Dans le texte, faire:

<para>Cliquez ici <xref LinkEnd="tests"> pour aller où l’on veut. </para>

ou bien

Pour plus de détails, aller voir le chapitre <link linkend="developper">
Développer avec Copix</link>.


  • Les liens externes
<para>
Cliquer sur <ulink url="http://www.linux.efrei.fr/">ce lien</ulink>
pour aller sur le site web d’EFREI LINUX.
</para>
Cliquer sur ce lien (http://www.linux.efrei.fr/) pour aller sur le site web d’EFREI LINUX.


Les images

<para>
<mediaobject>
<imageobject>
<imagedata fileref="efrei_linux3.png" format="png">
</imageobject>
<imageobject>
<imagedata fileref="efrei_linux3.eps" format="eps">
</imageobject>
<textobject>
<phrase>
Texte alternatif à utiliser.
</phrase>
</textobject>

<para>
Le sous-titre vient ici
</para>

</mediaobject>
</para>
Le sous-titre vient ici


Afficher du code

  • Classique
<programlisting>
mon programme, ou n’importe quoi d’ailleurs
</programlisting>
mon programme, ou n’importe quoi d’ailleurs


  • Afficher du code spécifique C
<programlisting role="C">
#include <stdio.h>
int main()
{
printf("Young man...\n");
return 0;
}
</programlisting>
#include <stdio.h>
int main()
{
printf("Young man...\n");
return 0;
}


  • Afficher du texte non formatté
<![CDATA <-- en fait, il ne fallait pas aller à la ligne
[
<balise et ca ne plante pas> </balise>
] <-- idem
]>
<balise et ca ne plante pas> </balise>


Avertissements

On peut aussi mettre des avertissements.

<caution>
<para>
Ceci est un avertissement
</para>
</caution>
Attention
Ceci est un avertissement


Décrire une API

Et oui, DocBook sait aussi décrire des API!

<funcsynopsis>
<funcsynopsisinfo>#include <stdlib.h></funcsynopsisinfo>
<funcprototype>
<funcdef>double <function>atof</function></funcdef>
<paramdef>const char *<parameter>nptr</parameter></paramdef>
</funcprototype>
</funcsynopsis>

Ce qui donnera une belle api:

#include <stdlib.h>
double atof(const char *nptr);


TODO

API Java


Customisation des XSL

  • Les driver.
  • La redéfinition des templates.
  • Les variables.


Dictionnaire

DSSSL Documentation Style Semantics and Specification Language
Voir la page DSSSL
DTD Document Type Definition : voir la page DTD
PDF Portable Document Format : voir la page PDF
SGML Standard Generalized Markup Language : voir la page SGML
XML eXtended Markup Language : voir la page XML
XSD XML Schema Definition : voir la page XSD
XSL XML Stylesheet Language : voir la page XSL


Conclusion

La complexité de DocBook en fait un format puissant qui répondra à la plupart de nos besoins, en échange d'une compatibilité partielle avec certains outils : ces derniers ne supportant peu ou mal DocBook dans son ensemble.


En terme de facilité d'utilisation, il est difficle d'opposer DocBook à des poids lourds de l'édition de texte. Mais ce qu'il perd en facilité, il le gagne en maintenabilité (plus facile de faire du suivi de versions et de différences sur un fichier texte) et portabilité (essayez de convertir un docment Word en HTML ou en PDF sans frais supplémentaires)... A vous de voir quels sont vos critères.


DocBook sera discutable lorque le document est déstiné à demeurer dans un cirtcuit fermé, sur des systèmes similaires (même système d'exploitation, même éditeurs), uniquement manipulé par des utilisateurs avertis. Mais dés que le document doit s'intégrer à une chaîne de production, de construction de projet, etre consulté sur diverses systèmes, être édité par des outils variés mais protégé contre des modifications (volontaires ou non), DocBook sdevient la solution.


Au final, DocBook fourni tout un ensemble d'outils qui permettent de produire rapidement des documents de qualité, moyennant un petit temps d'apprentissage. Ce qui à mon sens, fait de DocBook la meilleure solution pour un document écrit, dont la satisfaction retirée sera fortement lié à la qualité de l'éditeur.


Mais venant du monde Agile en général, et de l'eXtreme Programming en particulier, je m'intérroge toujours sur la pertinence de formaliser et transmettre un savoir via un document écrit en général, et figé en particulier. Il existe en effet d'autres moyens à notre disposition, soit « classiquement » textuels comme les outils de travail collaboratif (Wiki et CMS), mais aussi les tests ou tout simplement la parole, spontannée ou plsu structurée à l'occasion d'un « forum »...


Ressources

Les sites officiels


Des tutoriaux


Autres