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 :
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
\- 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.
... 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.
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.
Elle donne une description pour chaque option, comment elle affecte le fonctionnement du programme. Vous le saviez, n'est-ce pas ?
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/*.
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.
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.
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".
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.
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.
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).
Hosting by: Hurra Communications GmbH
Generated: 2007-01-26 18:01:31