Ce chapitre décrit précisément comment
écrire une documentation en utilisant un des formats supportés.
Ce chapitre est aussi bien destiné aux développeurs PEAR
qui travaillent sur un package PEAR existant qu'à ceux qui
prévoient d'en créer un nouveau.
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.
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).
| Avertissement |
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.
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.
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.
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.
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
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
|
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.
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.
