Voilà quelques conseils pour rendre votre documentation plus
sûre, plus lisible et plus «formatable» :
- Les exemples doivent fonctionner : testez-les
(utilisez le copier-coller pour passer à votre shell ce que
contient votre page de manuel) et redirigez la sortie de
votre commande dans votre page, ne tapez pas ce que vous
PENSEZ que votre programme affichera.
- relisez-vous, corrigez toutes les éventuelles fautes de
frappe ou d'orthographe, faîtes-vous relire par un tiers
(surtout si vous ne rédigez pas le texte dans votre langue
natale) . (d'ailleurs ce HOWTO n'a pas été relu...
Y a-t-il un volontaire ?)
- testez votre page de manuel : est-ce que
groff trouve des erreurs lors du formatage ?
C'est agréable de trouver dans un commentaire la ligne de
commande qu'il faut taper pour le formatage. Est-ce que la
commande man(1) affiche des erreurs ou des
avertissements lorsqu'on appelle "man
votre_programme" ? Est-ce que la façon dont
man(1) utilise le système de formatage produit le
résultat escompté ? Est-ce que cela fonctionne aussi
bien avec xman(1x) et tkman(1tk) ?
XFree86 3.1 contient la version 3.1.6 de
xman qui décompacte les pages avec :
gzip -c -d < %s > %s
zcat < %s > %s
- Est-ce que
makewhatis(8) pourra extraire la ligne
de description de la section NAME ?
|