Le format DocBook XML

Docbook est un dialecte XML utilisé par un grand nombre de projets pour maintenir leur documentation. Par exemple, Docbook est utilisé pour les documentations des projets OpenSource KDE et PHP. PEAR a opté pour l'usage de DocBook, parce que nous croyons qu'il fournit une base solide pour la documentation technique des packages de PEAR.

Le désavantage de DocBook est qu'il est relativement difficile d'utilisation. Les essais sur la documentation exige qu'un certain nombre d'outils soient installés et on doit apprendre un dialecte (pas très compliqué) de XML. Une fois qu'on est familier avec la façon dont DocBook fonctionne, l'écriture de la documentation devient appréciable.

Le livre [DocBook: The Definitive Guide], écrit par Norman Walsh et Leonard Muellner et publié par O'Reilly & Associates, Inc., est disponible en ligne. Il est aussi disponible en français Il propose une ressource importante pour les personnes déésireuses d'apprendre DocBook.

Lisez plus particulièrement la section "DocBook Element Reference" de ce livre. Cette section fournit des informations détaillées sur chaque élément, y compris quels éléments peuvent (et doivent) être utilisés en tant que parent et enfant.

Logiciels nécessaire

Même si du XML Docbook peut (comme n'importe quel fichier XML) être écrit avec un simple éditeur de texte, il vous faudra installer des logiciels sur votre ordinateur afin de vérifier la validité de votre documentation. Une liste des logiciels nécessaires et les instructions d'installation correspondantes peuvent être trouvées sur la page Documentation HOWTO de PHP. En plus de fournir des informations sur les logiciels, ce HOWTO fournit une multitude d'informations utiles non décrites dans ce chapitre. Nous vous encourageons à le lire complétement (Le chapitre II peut être sauté, il ne contient que des informations spécifiques à PHP)

Malheureusement, l'installation de ces logiciels peut être difficile dans certaines circonstances. Si vous n'êtes pas capable de les faire fonctionner, n'utilisez pas cela comme excuse pour ne pas écrire de documentation. Il y a un serveur de test qui, toutes les deux heures, téléchargent automatiquement la documenation PEAR depuis CVS et construit le manuel. Chaque erreur de parsage que vous modifiez sera monté dans les logs de la prochaine construction :

Cette génération automatique vous donne aussi une idée de ce que vos changements ont produit dans le manuel actuel. Cela peut vous aider parce que le manuel du site web n'est regénéré qu'une fois par semaine. (Dimanche vers midi UTC).

Le manuel de PEAR sur le site web est regénéré seulement une fois par semaine. Toutes les erreurs de validation XML causent un echec de génération. Si la regénération échoue, l'ancienne version est réutilisée mais cela veut dire que le manuel est dépassé. Et donc, toujours vérifier les logs des génération test pour vous assurer que vos changement sont valides. Plus important encore, n'éffectuez aucun commit ou updates juste avant la regénération principale qui se produit le dimanche vers midi UTC.

Une fois les logiciels installés, il vous faut récupérer les dernières versions disponibles des sources XML via le dépôt CVS de PEAR :

     
$ cvs -d :pserver:<user>@cvs.php.net:/repository login
     
     
[password]
     
     
$ cvs -d :pserver:<user>@cvs.php.net:/repository co peardoc
     
    

Si vous n'avez pas de compte pour cvs.php.net, utilisez cvsread comme nom pour le login. Et quand le mot de passe vous est demandé, utilisez phpfi.

Après cette commande, votre répertoire local ./peardoc contiendra une copie locale des dernières sources. Si vous n'êtes pas familier avec CVS, alors l'ouvrage en ligne "Open Source Development with CVS" peut vous fournir toute l'information nécéssaire.

Structure des dossiers

Ce chapitre va préciser les détails sur la structure des dossiers. Le chemin peardoc/fr/package/ est l'endroit où créer votre documentation. Si vous avez des questions sur la structure de la documentation, contactez la liste de diffusion de la documentation de PEAR.

Écrire la documentation

Au lieu d'une longue et ennuyeuse description de l'utilisation de DocBook pour la écrire la documentation, nous voudrions vous diriger à un groupe de "documents de référence", avec lequels vous devriez apprendre rapidement :

  • peardoc/authoring

    L'arbre CVS est un ensemble complet de template DocBook XML. Ces fichiers fournissent une norme de l'apparence que doit avoir la documentation de PEAR.

    La manière la plus simple de les utiliser est de les copier dans votre dossier de travail, de les renommer en conséquence, éditer le contenu pour qu'il corresponde à votre programme et puis pour les uploader dans le repository CVS de votre package.

  • HTTP Request

    La documentation pour HTTP_Request, qui est un package relativement petit, se compose seulement d'un groupe de documentation pour utilisateur final, qui décrit tous les dispositifs de base du package. Chaque description de fonctionnalité inclut au moins un exemple. Pour les petits packages avec seulement une poignée de méthodes, ce type de documentation est absolument suffisant.

  • Embelisseur XML

    XML_Beautifier est un package qui est également relativement compact, mais qui permet différentes options de configuration. Ces options sont décrites dans la documentation. En plus, la documentation donne des exemples d'utilisation et (à la différence de HTTP_Request) inclut également la documentation de l'API pour ses méthodes.

  • DB

    DB est un gros package de PEAR et dispose d'une excellente documentation, y compris des exemples d'utilisation. La documentation de DB adhère soigneusement au formatage indiqué dans peardoc/authoring. Le lien précédent pointe vers le code source DocBook dans le CVS. Cela peut être très utile de regarder le HTML généré depuis ces sources.

En plus des exemples ci-dessus, vous trouverez beaucoup plus d'exemples de documentation en passant en revue le repository de peardoc, qui contient votre version locale de l'arbre de CVS. Le dossier peardoc/en/packages/ devrait particulièrement vous intèresser. Vous pouvez également passer en revue le module CVS en utilisant l'interface web, incluant l'XML brut pour le fichier que vous être en train de lire.

Testing documentation

Using GNU make

Generating human-readable versions of the DocBook sources requires the existance of the above-mentioned software. The PEAR documentation system uses Unix style makefiles:

        
peardoc$ autoconf
peardoc$ ./configure --with-lang=en
peardoc$ make html
        
      

If you want to build a language other than English, change en, above, to the appropriate language code.

This will generate a "raw" HTML version of the whole manual. The result will be placed in the subdirectory html/.

The command make test does not generate any human-readable result, but it can be used to make sure that the XML is syntactically correct and that the build runs fine. And it is much faster than make html.

Using xmllint

Alternatively one can use the xmllint program that is part of the libxml2 toolkit. This is especially useful for systems where the DSSSL/make setup does not work properly.

In addition to testing the well-formedness of the DocBook sources, xmllint can also check the semantical correctness with the help of RELAX NG schemas. The schema files for DocBook are available as a ZIP package from docbook.org. After unzipping the package into the directory relaxng/ inside the peardoc source folder, one can run xmllint from the root folder of the PEAR documentation as follows:

xmllint --valid --noout --relaxng relaxng/ manual.xml

Partial builds

The build process (not the test builds, which are reasonably quick) actually takes a very long time which makes debugging and testing a very hard task. In order to increase build performance, the script make-partial.php in the root directory of the documentation module may be used. This is an interactive command line script that will enable to you to selectively include the different parts of the manual. In the following example a version of the manual is generated which only contains a certain part of the Developer's Guide and the documentation for the HTTP packages. Using these partial builds reduces the build time dramatically.

         
peardoc$ ./make-partial.php
Include about-pear? [NO]
Include guide-newmaint? [NO]
Include guide-developers? [NO] y
Include guide.developers.intro? [NO]
Include guide.developers.meaning? [NO]
Include guide.developers.contributing? [NO]
Include guide.developers.packagedef? [NO]
Include guide.developers.release? [NO]
Include guide.developers.supporting? [NO]
Include guide.developers.recommendations? [NO]
Include guide.developers.documentation? [NO] y
Include core? [NO]
Include packages? [NO] y
Include package.authentication? [NO]
Include package.benchmarking? [NO]
Include package.caching? [NO]
Include package.configuration? [NO]
Include package.console? [NO]
Include package.database? [NO]
Include package.datetime? [NO]
Include package.encryption? [NO]
Include package.fileformats? [NO]
Include package.filesystem? [NO]
Include package.gtk? [NO]
Include package.html? [NO]
Include package.http? [NO] y
Include package.images? [NO]
Include package.internationalization? [NO]
Include package.logging? [NO]
Include package.mail? [NO]
Include package.math? [NO]
Include package.networking? [NO]
Include package.numbers? [NO]
Include package.payment? [NO]
Include package.pear? [NO]
Include package.php? [NO]
Include package.science? [NO]
Include package.streams? [NO]
Include package.structures? [NO]
Include package.system? [NO]
Include package.text? [NO]
Include package.tools? [NO]
Include package.xml? [NO]
Include package.webservices? [NO]
Include pecl? [NO]
CONFIG_FILES=manual.xml CONFIG_HEADERS= ./config.status
creating manual.xml
/usr/bin/jade -wno-idref  -d html.dsl -V use-output-dir -t sgml ./phpdocxml.dcl manual.xml
         
       

Traduction de la documentation

La traduction de la documentation est une autre tâche importante. Il n'y pas que traduire les nouvelles documentations dans les langues existantes, les nouvelles langues sont les bienvenues. Aussi, les traductions existantes doivent être maintenue à jour en fonction des changements de la version anglaise de référence. Une aide sur la façon d'effectuer une traduction est fournie dans la section de suivi de version du manuel.

Questions ?

Nous sommes bien conscient de ne pas couvir toutes les questions à propos de l'écriture de la documentation en docBook dans ce chapitre. Si vous avez d'autres questions ou que vous rencontrez le moindre problème, n'hésitez pas à contacter l'équipe de documentation via pear-doc@lists.php.net. Pour rejoindre la liste pear-doc, envoyez un email à pear-doc-subscribe@lists.php.net.

Écrire la documentation (Previous) Conseils pour une bonne documentation (Next)
Last updated: Sun, 29 Aug 2010 — Download Documentation
Do you think that something on this page is wrong? Please file a bug report or add a note.
View this page in:

User Notes:

There are no user contributed notes for this page.