Page suivante - Page précédente - Table des matières

9. Comment dois-je présenter ma page de manuel ?

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 ?


Page suivante - Page précédente - Table des matières