Man page HOWTO: A quoi ressemble une page de manuel formatée ?

3. A quoi ressemble une page de manuel formatée ?

Laissez-moi vous présenter un exemple que j'expliquerai plus tard. En raison de la nature et du mode de réalisation de ce document, nous ne pouvons pas reproduire les caractères accentués, ni les différents enrichissements du texte (gras et italiques principalement) ; consultez la section traitant des polices de caractères pour obtenir des détails sur ces possibilités.

Voici comment se présente la page de manuel de notre programme hyphothétique "prout" :



      PROUT(1)                Manuel utilisateur               PROUT(1)


      NAME
             prout - proutibule la bibliotheque plaf

      SYNOPSIS
             prout [-plaf] [-c fichier-config ] fichier ...

      DESCRIPTION
             prout  proutibule  la  bibliotheque plaf en mouglifiant la
             table des symboles.  Par  defaut,  la  commande  recherche
             tous  les segments glurb et les trie par ordre betagonique
             decroissant afin que  le  gloupeur  gloup(1)  les  trouve.
             L'entree  symdef  est  alors  compactee selon l'algorithme
             NABOB.   Les  fichiers  sont  traites  dans   leur   ordre
             d'apparition sur la ligne de commandes.

      OPTIONS
             -b     N'affiche  pas  `bidouille  en cours' sur la sortie
                    standard pendant le traitement.

             -c fichier-config
                    Utilise le fichier de configuration  fichier-config
                    au  lieu  du  fichier global /etc/prout.conf.  Cela
                    supprime   aussi    l'effet    de    la    variable
                    d'environnement PROUTCONF.

             -a     Traite  egalement  les  en-tetes froutz en plus des
                    segments glurb.

             -r     Mode  recursif.  Fonctionne  a  la  vitesse  de  la
                    lumiere,  mais  necessite  plusieurs  megaoctets de
                    memoire virtuelle.

      FICHIERS
             /etc/prout.conf
                    Fichier de  configuration  general,  pour  tout  le
                    systeme. Voir prout(5) pour plus de details.
             ~/.proutrc
                    Fichier  de  configuration propre a chaque utilisa
                    teur. Voir prout(5) pour plus de details. 

      ENVIRONNEMENT
             PROUTCONF
                    Si elle existe, cette  variable  peut  contenir  le
                    chemin  d'acces  complet a un autre fichier de con
                    figuration global  prout.conf.   L'option  -c  rend
                    cette variable inoperante.

      DIAGNOSTICS
             Les  messages suivants peuvent etre affiches sur la sortie
             standard d'erreurs :

             Mauvais nombre magique.
                    Le fichier d'entree ne semble pas etre  un  fichier
                    archive.

             Segments glurb ancien style.
                    prout  ne peut traiter que le nouveau style de seg
                    ments glurb. Les bibliotheques GROBOL ne  sont  pas
                    supportees dans cette version.

      BOGUES
             Le  nom de cette commande aurait du etre choisi de maniere
             a mieux refleter sa fonction.

      AUTEUR
             Marcel Dugenou    <dugenou@renux.freenix.fr>

      VOIR AUSSI
             gloup(1), plaf(1), prout(5).

      Linux                      JANVIER 1996                         1

Et voici les explications promises :

La section NAME :

C'est la seule section requise. Les pages de manuel sans une section "NAME" sont aussi utiles que des réfrigerateurs au Pôle Nord. Cette section a aussi un format standardisé constitué d'une liste de programmes ou noms de fonctions séparés par des virgules suivie d'un tiret et d'une courte description (habituellement une ligne) de la fonctionnalité que le programme (fonction ou fichier) est supposé dispenser. A l'aide de makewhatis(8) les sections NAME sont incluses dans les fichiers de la base de données de whatis. makewhatis est la raison pour laquelle la section NAME doit exister et pourquoi elle doit adhérer au format que j'ai décrit. Dans le source groff, elle doit ressembler à :

.SH NAME prout \- proutibule de la bibliotheque plaf

Le \- est important ici : le backslash sert a faire la différence entre le tiret et une marque de césure qui peut apparaître à l'intérieur du nom de la commande ou dans la ligne de description.

Attention : en l'état actuel des choses, vous ne pouvez pas traduire NAME par NOM en français, à moins de modifier la plupart des programmes makewhatis existants. C'est bien dommage.

La section SYNOPSYS

... est censée donner un aperçu sur les options du programme. Pour les fonctions, cette section fait la liste des fichiers à inclure et son prototype pour que le programmeur connaisse le type et le nombre d'arguments ainsi que le type de retour.

La section DESCRIPTION

Elle explique en détail pourquoi votre séquence de 0 et de 1 est la meilleure de toutes. C'est ici que vous étalez tout votre savoir ! Gagnez l'estime des autres programmeurs et des utilisateurs en faisant de cette section une source d'information sûre et détaillée. Expliquez à quoi servent les arguments, le format de fichier, les algorithmes qui effectuent le plus dur du travail.

La section OPTIONS

Elle donne une description pour chaque option, comment elle affecte le fonctionnement du programme. Vous le saviez, n'est-ce pas ?

La section FICHIERS

Elle indique les fichiers utilisés par le programme ou la fonction. Par exemple, les fichiers de configuration, les fichiers de démarrage, les fichiers sur lesquels le programme agit. Ce serait une bonne idée de donner les chemins absolus de ces fichiers et d'avoir un processus d'installation qui modifie la partie répertoire selon les préférences de l'utilisateur : les manuels de groff ont comme préfixe par défaut /usr/local, donc ils référencent /usrl/local/lib/groff/* par défaut. Cependant, si vous installez en utilisant "make prefix=/opt/gnu", les références dans la page de manuel change en /opt/gnu/lib/groff/*.

La section ENVIRONNEMENT

fait la liste de toutes les variables d'environnement qui affectent votre programme ou fonction et, bien sûr, explique comment. La plupart du temps, les variables contiendront les chemins, nom de fichiers, options par défaut.

La section DIAGNOSTIQUES

Elle doit donner une vue d'ensemble des messages d'erreurs les plus courants de votre programme et des éventuelles solutions à ces problèmes. Il n'est pas nécessaire d'expliquer les messages d'erreurs du système (de perror(3)) ou des signaux fatals (de psignal(3)) qui peuvent apparaître pendant l'exécution de tout programme.

La section BOGUES

Devrait idéalement ne pas exister. Si vous êtes brave, vous pouvez décrire ici les limitations, les inconvénients, les caractéristiques que certains pourraient prendre pour des défauts. Si vous n'êtes pas brave, renommez-la en section "A FAIRE".

La section AUTEUR

Il est appréciable de l'avoir quand il y a des erreurs grossières dans la documentation ou dans le comportement du programme et que vous voulez envoyer un rapport de bogue.

La section VOIR AUSSI

C'est une liste de pages de manuel relatives à l'application citées par ordre alphabétique. Par convention, c'est la dernière section.

Vous êtes libres d'en inventer d'autres si elles n'empietent pas sur celles décrites au-dessus. Nous avons volontairement décrit une version francisée de page de manuel, puisque ce document est destiné aux pays francophones. Néanmoins, vous devez avoir conscience que si vous devez diffuser une application dans le monde entier, il vous faudra fournir un manuel en langue anglaise (ce qui est la version standard, traditionnelle), et que les noms "officiels" de ces sections sont en réalité, dans l'ordre : NAME, SYNOPSIS, DESCRIPTION, OPTIONS, FILES, ENVIRONMENT, DIAGNOSTICS, BUGS, AUTHOR et SEE ALSO.

Donc comment générer cette page de manuel ? J'attendais cette question, voici le source :

 .\" Formater ce fichier par la commande :
 .\" groff -man -Tlatin1 prout.1  (si vous avez saisi des accents Iso-8859-1)
 .\" groff -man -Tascii  prout.1  (cas general )
 .\"
 .TH PROUT 1 "JANVIER 1996" Linux "Manuel utilisateur"
 .SH NAME
 prout \- proutibule la bibliotheque plaf
 .SH SYNOPSIS
 .B prout [-plaf] [-c
 .I fichier-config
 .B ]
 .I fichier
 .B ...
 .SH DESCRIPTION
 .B prout
 proutibule la bibliotheque plaf en mouglifiant la table des symboles.
 Par defaut, la commande recherche tous les segments glurb et les trie
 par ordre betagonique decroissant afin que le gloupeur 
 .BR gloup (1)
 les trouve. L'entree symdef est alors compactee selon l'algorithme NABOB.
 Les fichiers sont traites dans leur ordre d'apparition sur la ligne
 de commandes.
 .SH OPTIONS
 .IP -b
 N'affiche pas `bidouille en cours' sur la sortie standard pendant 
 le traitement.
 .IP "-c fichier-config"
 Utilise le fichier de configuration 
 .I fichier-config
 au lieu du fichier global
 .IR /etc/prout.conf .
 Cela supprime aussi l'effet de la variable d'environnement
 .B PROUTCONF.
 .IP -a
 Traite egalement les en-tetes froutz en plus des segments glurb.
 .IP -r
 Mode recursif. Fonctionne a la vitesse de la lumiere, mais necessite
 plusieurs megaoctets de memoire virtuelle.
 .SH FICHIERS
 .I /etc/prout.conf
 .RS
 Fichier de configuration general, pour tout le systeme. Voir
 .BR prout (5)
 pour plus de details.
 .RE
 .I ~/.proutrc
 .RS
 Fichier de configuration propre a chaque utilisateur. Voir
 .BR prout (5)
 pour plus de details.
 .SH ENVIRONNEMENT
 .IP PROUTCONF
 Si elle existe, cette variable peut contenir le chemin d'acces complet
 a un autre fichier de configuration global
 .IR prout.conf .
 L'option
 .B -c
 rend cette variable inoperante.
 .SH DIAGNOSTICS
 Les messages suivants peuvent etre affiches sur la sortie standard d'erreurs :
 
 Mauvais nombre magique.
 .RS
 Le fichier d'entree ne semble pas etre un fichier archive.
 .RE
 Segments glurb ancien style.
 .RS
 .B prout
 ne peut traiter que le nouveau style de segments glurb. Les bibliotheques
 GROBOL ne sont pas supportees dans cette version.
 .SH BOGUES
 Le nom de cette commande aurait du etre choisi de maniere a mieux
 refleter sa fonction.
 .SH AUTEUR
 Marcel Dugenou    <dugenou@renux.freenix.fr>
 .SH "VOIR AUSSI"
 .BR gloup (1),
 .BR plaf (1),
 .BR prout (5).