Copyright © 2004 Yves Mettier
Cette création est mise à disposition sous un contrat Creative Commons.
L'article original se trouve sur http://ymettier.free.fr/articles_lmag/.
Article publié dans le numéro 60 (avril 2004) de GNU/Linux France Magazine
Table des matières
Résumé
Votre projet contient une arborescence assez classique avec un répertoire doc. Et votre documentation est en texte, voire html, et vous souhaiteriez produire du postscript ou du pdf, ou même du html avec ce bon vieux aspect qu'on retrouve en particulier dans les HOWTOs. Pour cela, il s'agit en fait de partir d'un fichier sgml, qui sera le code source de votre documentation.
Il ne s'agit pas exactement de compilation, quoique. Mais à partir d'un document sgml, vous pouvez générer des documents lisibles par nous, humains (quoique certains sont capable de lire le sgml comme vous lisez un journal), en fonction des outils dont vous disposez. Ces outils, ce sont en réalité jade, sgml-common, et les outils docbook. Voici pour exemple les paquets installés sur ma distribution (mandrake cooker) :
docbook-dtd31-sgml docbook-dtd412-xml docbook-dtd41-sgml docbook-dtd42-xml docbook-style-dsssl docbook-utils docbook-utils-pdf jadetex libopenjade0 openjade sgml-common
Pour les installer, commencez par docbook-utils et docbook-utils-pdf qui vous diront les dépendances nécessaires.
La génération d'un document se fait ensuite avec un des nombreux font-ends de jade qui sont de deux familles : docbook2* et db2*. Pour générer du html, voici la syntaxe :
docbook2html fichier.sgml
Vous créez ainsi plusieurs pages html dans un répertoire créé pour l'occasion au nom de votre fichier sans son extension, ici fichier. Mais vous pouvez aussi préférer générer du html dans un seul fichier. Dans ce cas, la syntaxe devient :
docbook2html -u fichier.sgml
Et là, le fichier est fichier/fichier.html.
Pour générer un fichier postscript, un fichier pdf, et ainsi de suite, utilisez respectivement docbook2ps, docbook2pdf avec le nom de votre fichier sgml en argument : l'outil vous créera un fichier du même nom avec l'extention en fonction du format souhaité.
Vous pouvez utiliser db2* à la place de docbook2* comme vous voulez. Ainsi, pour créer fichier.pdf, voici la syntaxe :
db2pdf fichier.sgml
Un fichier de documentation sgml de base doit contenir entre autres ceci, pour faire les choses bien :
Le nom de l'auteur de la documentation, et une mention de copyright
Le nom de la personne ou des personnes détenant le copyright de l'outil qu'on documente
La licence de la documentation (par exemple : Free Documentation License)
La date de dernière mise à jour de la documentation
Voici le squelette d'un tel document, qui serait écrit par moi, sur un programme nommé plouf :
1 <!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook V4.1//EN" [ 2 <!ENTITY plouf "<emphasis role='bold'>Plouf</emphasis>"> 3 <!ENTITY currentdate "<emphasis>Sun Feb 01 20:00:00 CEST 2004</emphasis>"> 4 ]> 5 6 <book id="plouf"> 7 <bookinfo> 8 <title>&plouf; Documentation - ¤tdate;</title> 9 <authorgroup> 10 <author> 11 <firstname> 12 Yves 13 </firstname> 14 <surname> 15 METTIER 16 </surname> 17 <affiliation> 18 <address> 19 <email>ymettier@libertysurf.fr</email> 20 </address> 21 </affiliation> 22 </author> 23 </authorgroup> 24 <copyright> 25 <year>2004</year> <holder>METTIER Yves</holder> 26 </copyright> 27 <legalnotice> 28 29 <para> 30 This documentation is free software; you can redistribute it 31 and/or modify it under the terms of the GNU General Public 32 License as published by the Free Software Foundation; either 33 version 2 of the License, or (at your option) any later 34 version. 35 </para> 36 37 <para> 38 This program is distributed in the hope that it will be 39 useful, but WITHOUT ANY WARRANTY; without even the implied 40 warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR 41 PURPOSE. See the GNU General Public License for more details. 42 </para> 43 <para> 44 You should have received a copy of the GNU General Public 45 License along with this program; if not, write to the Free 46 Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, 47 MA 02111-1307 USA 48 </para> 49 <para> 50 For more details see the file COPYING in the source 51 distribution of GNOME. 52 </para> 53 </legalnotice> 54 </bookinfo> 55 56 <toc></toc> 57 58 <chapter id="compilation-ch"> 59 <title>Compilation</title> 60 <sect1> 61 <title>Compilation des sources</title> 62 <para> 63 Procédure de compilation des sources ici 64 </para> 65 </sect1> 66 </chapter> 67 </book>
Cet article ne peut se substituer à un bon livre sur docbook, surtout que celui d'O'reilly est disponible gratuitement sur internet (http://www.docbook.org pour plus d'informations). Mais comme le code précédent n'est rien d'autre que du docbook, sous-ensemble de SGML, je vais vous en présenter quelques morceaux pour les besoins de base.
La première chose que vous pouvez constater est que ce document est organisé en trois parties. La première commence ligne 7 et finit ligne 54. Ce sont les informations générales, dont le titre, le nom de l'auteur... La seconde partie est très courte : c'est la ligne 56 sur laquelle nous ne reviendrons pas : la balise <lt;toc> ne sert à rien d'autre qu'à mettre une table des matières (Table Of Contents). La troisième démarre ligne 58 et finit ligne 66.
Dans ce noeud, la balise <authorgroup> définit les auteurs, <copyright> le copyright du document, et <legalnotice> la licence du document. La première est la plus compliquée, et un exemple un peu plus complet se substituera mieux à toute explication :
1 <authorgroup> 2 <author> 3 <firstname>prénom de l'auteur principal de la documentation</firstname> 4 <surname>NOM de l'auteur principal de la documentation</surname> 5 <affiliation> 6 <address> 7 <email>adresse électronique de l'auteur principal de la documentation</email> 8 </address> 9 </affiliation> 10 </author> 11 <othercredit> 12 <firstname>prénom d'un contributeur éventuel</firstname> 13 <surname>NOM d'un contributeur éventuel</surname> 14 <affiliation> 15 <address> 16 <email>adresse électronique d'un contributeur éventuel</email> 17 </address> 18 </affiliation> 19 <contrib>Description de sa contribution</contrib> 20 </othercredit> 21 <othercredit> 22 <firstname>prénom d'un contributeur éventuel</firstname> 23 <surname>NOM d'un contributeur éventuel</surname> 24 <affiliation> 25 <address> 26 <email>adresse électronique d'un contributeur éventuel</email> 27 </address> 28 </affiliation> 29 <contrib>Description de sa contribution</contrib> 30 </othercredit> 31 </authorgroup>
Vous pouvez mettre autant d'auteurs et de contributeurs que vous le souhaitez. Ici, il n'y a qu'un auteur, mais deux contributeurs.
Pour le copyright et la licence, l'exemple plus haut était clair. Remarquez que le texte est contenu dans des paragraphes, délimités par des balises <para>, balises qu'on retrouve plus bas pour le contenu du document et ses nombreux paragraphes.
Un document peut contenir un certain nombre de chapitres, les uns à la suite des autres. Il est toujours préférable de nommer chaque chapitre avec le tag id de la balise <chapter>. Et le noeud suivant est le titre du chapitre, dans la balise <title>. Puis commencent au choix les paragraphes ou les sections.
Il est possible de diviser un chapitre en sections de niveau 1, elles-mêmes divisées en sous-sections de niveau 2, et on va ainsi jusqu'au niveau 5 inclus. Chaque section contient en premier noeud un titre. Les noeuds suivants sont, au choix, des paragraphes avec un tag <para> ou des sous-sections <sect?>.
Voici quelques tags utiles supplémentaires :
<emphasis>: accentue le texte. Le résultat est généralement des caractères gras.<programlisting>: permet d'inclure du code qui sera reproduit tel quel<xref linkend='identifiant'>: permet de faire un lien hypertexte. En SGML, pas besoin de refermer ce tag. En XML, n'oubliez pas de le refermer, par exemple ainsi :<xref linkend='compilation-ch' />
Pour créer une liste, voici un exemple parlant :
1 <itemizedlist> 2 <listitem><para>Premier item</para></listitem> 3 <listitem><para>Deuxième item</para></listitem> 4 <listitem><para>Troisième item</para></listitem> 5 <listitem><para>Et ainsi de suite</para></listitem> 6 </itemizedlist>
Pour un tableau, je vous recommande la documentation de docbook et l'exemple en ligne sur http://www.docbook.org. Mais voici tout de même un exemple illustratif :
1 <table> 2 <title>Menu de la semaine</title> 3 <tgroup cols=<emphasis>"7"</emphasis>> 4 <tbody> 5 <row> 6 <entry>Lundi</entry> 7 <entry>Mardi</entry> 8 <entry>Mercredi</entry> 9 <entry>Jeudi</entry> 10 <entry>Vendredi</entry> 11 <entry>Samedi</entry> 12 <entry>Dimanche</entry> 13 </row> 14 <row> 15 <entry>des patates</entry> 16 <entry>des patates (!?)</entry> 17 <entry>des patates (encore)</entry> 18 <entry>des patates (c'est comme hier)</entry> 19 <entry>des patates (commence a y en avoir marre ! )</entry> 20 <entry>des patates (vivement la semaine prochaine !!! )</entry> 21 <entry>des patates au beurre (miam)</entry> 22 </row> 23 </tbody> 24 </tgroup> 25 </table>
Vous pouvez visualiser ce que donnent la liste précédente et le tableau précédent sur la figure 1 tel qu'un navitateur à base de gecko (galeon ici) les représentent.
Si vous avez suivi cet article, que vous voulez le mettre en pratique, mais que vous n'avez pas encore trop d'idées de contenu pour votre documentation, en voici. Faites au moins un chapitre sur comment compiler/installer le programme. En général, comme il s'agit juste de la séquence ./configure; make; make install, il n'y a que cela à spécifier. Mais il faut le dire.
Vous pouvez aussi démarrer le squelette d'une FAQ. Et qui sait, certaines questions ont déjà été posées par des utilisateurs, voire par vous Mais comment j'ai fait l'autre fois pour...
Et puis il vous reste à démarrer la documentation du programme : comment le lancer, description de ce qu'il fait, etc. Vous pouvez aussi distinguer une documentation pour l'utilisateur qui veut démarrer, donc une documentation typiquement courte, et une autre plus longue, dite de référence. Commencez peut-être par un seul document, et quand il devient gros, vous le découpez en deux, trois, voire quatre documents distincts. Le projet Postgresql par exemple dispose de huit documents pour sa version 7.3 !
Cet article n'est pas un article sur docbook malgré les apparences, mais se veut être un point de départ pour vous si vous voulez générer de la documentation à partir d'un fichier sgml au format docbook. Le choix de le faire court a été qu'il se lise vite et permette de mémoriser le principal, qui est généralement noyé dans les ouvrages traitant de docbook. Ici, au contraire, vous avez un bon point de départ pour écrire une documentation pour un programme d'un projet libre. Mais vous n'irez pas loin si vous souhaitez écrire autre chose qu'une telle documentation avec cet article. Pour votre documentation, il ne vous reste plus maintenant qu'à la démarrer, puis à la continuer ou la laisser continuer par un contributeur, pendant que vous verrez les détails de db2html dans votre fichier Makefile du répertoire doc de votre projet, répertoire indispensable au bon fonctionnement du projet, même si le programme s'en passe !
docbook : http://www.docbook.org