Pour répondre à cette question, le mieux est de présenter un exemple pratique. En raison de la nature et du mode de réalisation ce 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
hypothé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.
NAMEC'est la seule section indispensable.
Les pages de manuel sans section NAME sont aussi inutiles qu'un
réfrigérateur au pôle nord. Cette section possède aussi un format
standardisé consistant en une liste de noms de programmes ou de fonctions
suivis d'un tiret ou d'une courte description (une ligne en général) des
fonctionnalités, l'élément séparateur de cette liste étant la virgule.
C'est le format exploité par l'utilitaire makewhatis(8), qui
analyse ces noms de section pour les intégrer dans la base de données
whatis : Voilà pourquoi il est important de respecter cette
organisation. Dans le code source groff, cela donne quelque chose
comme ceci :
.SH NAME
prout \- proutibule la bibliotheque plaf
Le "backslash" est très important : cette contre-oblique
est nécessaire pour que le tiret qui suit soit distingué d'une marque
de césure, qui peut apparaître aussi bien dans le nom de commande que
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...
SYNOPSISElle permet de donner un court aperçu des options du programme. Dans le cas des fonctions, cette section contient les fichiers d'en-têtes qu'il est nécessaire d'inclure, ainsi que le prototype afin que le programmeur connaisse immédiatement le type et le nombre des arguments demandés ainsi que le type de la valeur de retour.
DESCRIPTIONC'est elle qui explique en détail pourquoi votre séquence de 0 et de 1 est meilleure que toutes les autres. C'est ici que vous étalez tout votre savoir ! Gagnez l'estime des autres développeurs et l'admiration des utilisateurs en faisant de cette section la référence absolue, contenant toutes les informations possibles sur votre application, avec force détails. Expliquez clairement le rôle de chaque argument, décrivez le format des fichiers utilisés, les algorithmes qui effectuent le plus dur du travail, etc.
OPTIONSElle donne une description de chaque option modifiant le comportement du programme. Vous deviez vous en douter...
FICHIERSElle indique quels sont les fichiers utilisés par le programme ou la
fonction. Ce sont par exemple les fichiers de configuration et
d'initialisation auxquels il est directement fait appel. Il est
toujours préférable de donner leur chemin d'accès complet et de se
débrouiller pour que la procédure d'installation modifie la partie
répertoire de ces chemins dans la page de manuel, en fonction des
préférences de l'utilisateur. Pour citer un exemple, l'application
GNU groff s'installe par défaut dans /usr/local,
les pages de manuel référencent donc /usr/local/lib/groff/*.
Mais si vous l'installez par "make prefix=/opt/gnu",
toutes les pages de manuel seront modifiées pour indiquer
/opt/gnu/lib/groff/*.
ENVIRONNEMENTIndique toutes les variables d'environnement prises en compte par votre programme ou votre fonction, et leur action. La plupart du temps, ces variables contiennent des chemins d'accès, des noms de fichiers ou des options par défaut.
DIAGNOSTICSElle doit donner un aperçu des messages d'erreur les plus courants
susceptibles d'être affichés par le programme, et les éventuelles
solutions à ces problèmes. Il n'est pas nécessaire de
citer les messages d'erreur du système (issus de perror(3))
ou fatals (issus de psignal(3)) car ils peuvent apparaître
durant l'exécution de n'importe quel programme.
BOGUESDans un monde idéal, cette section n'aurait pas lieu d'être !
Si vous êtes brave, vous pourrez décrire ici les limites et les
inconvénients de votre application, voire les caractéristiques que
certains pourraient considérer comme des défauts. Sinon, faites la
même liste mais renommez cette section "A FAIRE"...
AUTEURElle est très utile pour savoir qui a fait quoi, et pour trouver l'adresse à laquelle envoyer un rapport de bogue en cas d'erreur grossière dans la documentation (ce qui ne devrait pas arriver !) ou d'un comportement anormal du programme.
VOIR AUSSIC'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 libre d'inventer toute autre section, si le cas à traiter ne
peut se classer dans aucune de celles que nous venons d'énumérer.
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.
Tout cela est très bien, mais comment générer cette belle page de manuel ? Nous nous attendions à cette question ! Alors, voici le code source complet :
.\" 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).
Chapitre suivant, Chapitre Précédent
Table des matières de ce chapitre, Table des matières générale
Début du document, Début de ce chapitre