Man page HOWTO
Auteur : Jens Schweikhardt
[email protected]
www.shuttle.de/schweikh/home.html
Mars 1998
(Adaptation fran�aise par Alexandre Devaure
[email protected], 2
juin 1999). Ce HOWTO explique ce que vous devrez avoir en t�te quand
vous pr�voyez d'�crire une documentation en ligne (plus connue sous le
nom de page de manuel) que vous voulez rendre accessible via la com�
mande man(1). Tout au long de ce HOWTO, une entr�e du manuel sera sim�
plement appel�e page de manuel, quelque soit sa longueur r�elle et
sans intention sexiste.
______________________________________________________________________
Table des mati�res
1. Quelques �vidences � propos de la documentation
2. Comment acc�de-t-on aux pages de manuel ?
3. A quoi ressemble une page de manuel format�e ?
4. Comment documenter plusieurs choses dans une seule page de manuel ?
5. Quel ensemble de macros utiliser ?
6. Quels pr�processeurs puis-je utiliser ?
7. Dois-je distribuer les sources et/ou la documentation d�j� format�e ?
8. Quelles sont les conventions pour les fontes ?
9. Comment dois-je pr�senter ma page de manuel ?
10. Comment puis-je avoir un texte en pur ASCII sans tous ces fichus ^H^ de contr�le ?
11. Comment avoir une belle page de manuel en PostScript ?
12. Comment faire fonctionner les programmes
13. La langue fran�aise
14. Les conditions de copie
______________________________________________________________________
11..
QQuueellqquueess ��vviiddeenncceess �� pprrooppooss ddee llaa ddooccuummeennttaattiioonn
Pourquoi �crivons-nous une documentation ? C'est une question b�te.
Parce que nous voulons que d'autres personnes puissent utiliser notre
programme, notre fonction dans une librairie ou quoi que ce soit que
nous avons �crit et rendu disponible. Mais �crire une documentation
n'est pas suffisant :
� la documentation doit �tre accessible. Si elle est cach�e � un
endroit non standard o� les outils de recherche relatifs � la
documentation ne la trouveront pas, comment peut-elle remplir son
r�le ?
� la documentation doit �tre fiable et pr�cise. Il n'y a rien de plus
irritant qu'un programme se comportant diff�remment de ce qui est
�crit dans sa documentation. Les utilisateurs vous maudiront, vous
enverront des courriers d'insulte, puis rejetteront � jamais tout
autre travail venant de vous.
La m�thode traditionnelle pour acc�der � la documentation sous UNIX
fait appel � la commande man(1). Ce HOWTO d�crit ce que vous devez
faire pour �crire une page de manuel qui sera correctement trait�e
par les outils pr�vus � cet effet, dont les plus importants sont
man(1), xman(1x), apropos(1), makewhatis(8) et catman(8).
La qualit� et la v�racit� des informations sont, bien s�r, de votre
ressort. Malgr� tout, vous trouverez dans ce guide quelques id�es qui
vous permettront d'�viter certains pi�ges courants.
22..
CCoommmmeenntt aacccc��ddee--tt--oonn aauuxx ppaaggeess ddee mmaannuueell ??
Vous devez conna�tre avec pr�cision le m�canisme d'acc�s aux pages de
manuel afin de savoir donner un nom correct � vos documents, et d'�tre
capable de les installer au bon endroit. Chaque page de manuel
appartient � une section sp�cifique, d�not�e par un simple chiffre.
Les sections les plus courantes rencontr�es sous Linux sont :
� 1 : commandes utilisateurs pouvant �tre ex�cut�es par tout le
monde ;
� 2 : appels syst�mes, c'est-�-dire les fonctions fournies par le
noyau ;
� 3 : fonctions des biblioth�ques ;
� 4 : p�riph�riques, c'est-�-dire les fichiers sp�ciaux que l'on
trouve dans le r�pertoire /dev ;
� 5 : descriptions des formats de fichiers (comme par exemple
/etc/passwd ;
� 6 : les jeux, sans commentaire...
� 7 : divers (macros, conventions particuli�res, ...) ;
� 8 : outils d'administration ex�cutables uniquement par le super
utilisateur ;
� 9 : un autre endroit (sp�cifique � Linux) destin� � la
documentation des services offerts par le noyau ;
� n : nouvelle documentation, qui pourra �tre d�plac�e vers un
endroit appropri� ;
� o : ancienne documentation, qui peut �tre conserv�e encore un
certain temps ;
� l : documentation locale, propre � ce syst�me particulier.
Le nom du fichier source d'une page de manuel (le fichier d'entr�e
du syst�me de formatage) est le nom de la commande d�crite (ou de
la fonction, du fichier, etc.), suivi d'un point et du num�ro de
section. Si, par exemple, vous documentez le format du fichier
"_p_a_s_s_w_d", vous devez appeler le fichier source "_p_a_s_s_w_d_._5". Nous
avons ici un exemple d'un fichier qui porte le m�me nom qu'une
commande ; nous aurions tout aussi bien avoir une fonction de
biblioth�que appel�e "_p_a_s_s_w_d". L'organisation en sections constitue
la m�thode habituelle pour r�soudre ces ambigu�t�s : la description
de la commande se trouvera dans le fichier "_p_a_s_s_w_d_._1" et notre
hypoth�tique fonction de biblioth�que dans "_p_a_s_s_w_d_._3".
Quelquefois, une lettre est ajout�e au num�ro de section comme par
exemple "_x_t_e_r_m_._1_x" ou "_w_i_s_h_._1_t_k". Le but de cette notation est
d'indiquer qu'il s'agit respectivement d'une documentation d'un
programme X Window ou d'une application Tk. Certains programmes
d'affichage du manuel peuvent exploiter cette particularit� ; xman,
par exemple affichera "_x_t_e_r_m_(_x_)" et "_w_i_s_h_(_t_k_)" dans la liste des
documents disponibles.
S'il vous pla�t, n'utilisez pas les sections n, o et l : selon le
standard du syst�me de fichiers (File System Standard), ces sections
sont d�conseill�es, utilisez plut�t les sections num�riques.
Attention aux �ventuels conflits de noms avec des programmes,
fonctions ou fichiers d�j� existants. Ce serait certainement une
mauvaise id�e d'�crire un autre �diteur de texte et de le nommer ed,
sed (pour super ed) ou red (pour Roger edition). En vous assurant que
le nom de votre programme est unique, vous �viterez que quelqu'un
ex�cute votre programme et qu'il lise la page de manuel d'un autre ou
_v_i_c_e _v_e_r_c_a. Vous pouvez �ventuellement vous aider de la base de
donn�es "lsm" qui recense beaucoup de programmes disponibles pour
Linux.
Maintenant que nous savons quel nom donner � notre fichier, la
prochaine d�cision est de choisir le r�pertoire dans lequel nous
l'installerons (quand l'utilisateur lancera la commande "make
install"). Sous Linux, toutes les pages de manuel sont dans des sous-
r�pertoires � partir d'une racine m�moris�e dans la variable
d'environnement MANPATH. Les outils de traitement de la documentation
l'utilisent de la m�me mani�re que le shell utilise la variable PATH
pour trouver les ex�cutables. En fait, MANPATH a le m�me format que
PATH : toutes les deux sont une liste de r�pertoires s�par�s par des
":" (mais MANPATH n'autorise pas de champs vides ou des chemins
relatifs, seulement des chemins absolus). Si MANPATH n'existe pas ou
si elle n'est pas export�e, /usr/man est utilis�e comme valeur par
d�faut. Dans le but d'acc�lerer la recherche et pour garder les
r�pertoires de taille raisonable, les r�pertoires point�s dans MANPATH
(aussi appel�s r�pertoires de base) contiennent une multitude de sous-
r�pertoires nomm�s "_m_a_n_<_s_>" o� <s> d�signe le caract�re correspondant
� la section pr�sent� plus haut. Toutes les sections ne sont pas
repr�sent�es, il n'y a pas, par exemple de raison de garder une entr�e
"_m_a_n_o". Vous pourrez y trouver �galement des sous-r�pertoires appel�s
"_c_a_t_<_s_>", "_d_v_i_<_s_>" et "_p_s_<_s_>", qui contiennent toute la documentation
format�e, pr�te � �tre affich�e ou imprim�e : nous reviendrons sur ce
sujet plus loin. Le seul fichier � �tre pr�sent � c�t� de ces sous-
r�pertoires du r�pertoire de base s'appelle "_w_h_a_t_i_s". Le but et la
cr�ation de ce fichier sera d�crit dans la section 11. La m�thode la
plus s�re pour installer au bon endroit une page de manuel de la
section "s" est de mettre le fichier dans le r�pertoire
"_/_u_s_r_/_m_a_n_/_m_a_n_<_s_>". Toutefois, un bon Makefile devra autoriser
l'utilisateur de choisir un autre r�pertoire de base, disons par
exemple par le biais d'une variable d'environnement que l'on pourrait
nommer MANDIR. La plupart des distributions GNU peuvent �tre
configur�es � l'aide de l'option --prefix=/nom/option. Les pages de
manuels correspondantes seront alors install�es � partir du r�pertoire
de base _/_m_o_n_/_o_p_t_i_o_n_/_m_a_n. Je vous sugg�re d'utiliser une m�thode
similaire pour vos r�alisations personnelles.
Depuis l'av�nement du "_S_y_s_t_�_m_e _d_e _f_i_c_h_i_e_r_s _s_t_a_n_d_a_r_d" pour Linux (FS-
STnd), les choses se sont compliqu�es. Le FS-STnd 1.2 stipule que :
des am�nagements doivent �tre faits dans la structure de
_/_u_s_r_/_m_a_n pour supporter des pages de manuel �crites dans
diff�rentes (ou mutiples) langues.
Ceci est fait en introduisant un niveau de r�pertoires suppl�mentaire
qui distingue les diff�rentes langues. Citant encore le FS-Stnd 1.2 :
Le nommage des sous-r�pertoires correspondants aux langues
de _/_u_s_r_/_m_a_n est bas� sur l'appendice E du standard POSIX
1003.1 qui d�crit la cha�ne de caract�res d'authentification
_l_o_c_a_l_e (qui est la m�thode la mieux accept�e pour d�crire un
environement culturel). La cha�ne _l_o_c_a_l_e se pr�sente sous la
forme
<langage>[_<pays>][.<jeu-de-caracteres>][,<version>]
(Reportez vous au FS-Stnd pour voir quelques cha�nes _l_o_c_a_l_ecourantes.)
D'apr�s ces recommandations, nous avons nos pages de manuel dans
_/_u_s_r_/_m_a_n_/_<_l_o_c_a_l_e_>_/_m_a_n_[_1_-_9_l_n_o_]. Les versions format�es se trouveraient
alors bien entendu dans _/_u_s_r_/_m_a_n_/_<_l_o_c_a_l_e_>_/_c_a_t_[_1_-_9_l_n_o_] : nous pourrions
ne les fournir que pour une seule langue.
TOUTEFOIS, je (l'auteur du document, pas le traducteur) ne peut pas
recommander de passer a cette structure en l'�tat actuel des choses.
Le FS-Stnd 1.2 autorise aussi que
les syst�mes qui n'utilisent qu'une seule langue et jeu de
caract�res pour toutes les pages de manuel peuvent omettre
la sous-cha�ne _<_l_o_c_a_l_e_> et stocker toutes ces pages dans le
r�pertoire _m_a_n_d_i_r. Par exemple, les machines �quip�es seule�
ment de pages de manuel en anglais cod�es en ASCII peuvent
mettre les pages de manuel (les r�pertoires _m_a_n_[_1_-_9_])
directement dans _/_u_s_r_/_m_a_n_/. Il s'agit en fait de l'arrange�
ment habituel.
Je (l'auteur du document, pas le traducteur) ne changerai pas ma
configuration tant que tous les outils (comme xman, info, tkman et
beaucoup d'autres) ne seront pas tous adapt�s � cette nouvelle
structure.
33..
AA qquuooii rreesssseemmbbllee uunnee ppaaggee ddee mmaannuueell ffoorrmmaatt��ee ??
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 <
[email protected]>
VOIR AUSSI
gloup(1), plaf(1), prout(5).
Linux JANVIER 1996 1
Et voici les explications promises :
LLaa sseeccttiioonn NNAAMMEE ::
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.
AAtttteennttiioonn : 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.
LLaa sseeccttiioonn SSYYNNOOPPSSYYSS
... 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.
LLaa sseeccttiioonn DDEESSCCRRIIPPTTIIOONN
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.
LLaa sseeccttiioonn OOPPTTIIOONNSS
Elle donne une description pour chaque option, comment elle
affecte le fonctionnement du programme. Vous le saviez, n'est-ce
pas ?
LLaa sseeccttiioonn FFIICCHHIIEERRSS
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 _/_u_s_r_/_l_o_c_a_l,
donc ils r�f�rencent _/_u_s_r_l_/_l_o_c_a_l_/_l_i_b_/_g_r_o_f_f_/_* par d�faut.
Cependant, si vous installez en utilisant "make
prefix=/opt/gnu", les r�f�rences dans la page de manuel change
en _/_o_p_t_/_g_n_u_/_l_i_b_/_g_r_o_f_f_/_*.
LLaa sseeccttiioonn EENNVVIIRROONNNNEEMMEENNTT
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.
LLaa sseeccttiioonn DDIIAAGGNNOOSSTTIIQQUUEESS
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.
LLaa sseeccttiioonn BBOOGGUUEESS
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".
LLaa sseeccttiioonn AAUUTTEEUURR
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.
LLaa sseeccttiioonn VVOOIIRR AAUUSSSSII
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 ver�
sion 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 <
[email protected]>
.SH "VOIR AUSSI"
.BR gloup (1),
.BR plaf (1),
.BR prout (5).
44..
CCoommmmeenntt ddooccuummeenntteerr pplluussiieeuurrss cchhoosseess ddaannss uunnee sseeuullee ppaaggee ddee mmaannuueell ??
De nombreux programmes (grep, egrep) et fonctions (printf,
fprintf,...) sont document�es dans une seule page de manuel.
Cependant, ces pages seraient inutilisables si elles n'�taient
accessibles que par un seul nom. Nous ne pouvous nous attendre � ce
qu'un utilisateur se souviennent que la page de manuel de egrep est en
fait celle de grep. Il est par cons�quent indispensable que la page
soit accessible sous diff�rents noms. Vous avez plusieurs possibilit�s
pour y arriver :
1. avoir des copies identiques pour chaque nom ;
2. connecter toutes les pages de manuels en utilisant des liens
physiques ;
3. utiliser les liens symboliques pointant la page de manuel ;
4. utiliser le m�canisme de "source" de groff fournie par la macro
".SO".
La premi�re possibilit� est une perte de place. La deuxi�me n'est
pas recommand�e parce que les versions intelligentes du programme
catman peuvent gagner beaucoup de temps en regardant le type du
fichier et son contenu. Les liens physiques r�duiraient
l'efficacit� de cet outil (dont le but est de formater toutes les
pages de manuel pour qu'elles soient affich�es plus rapidement). La
troisi�me alternative comporte un pi�ge si vous �tes concern� par
la portabilit�, vous devez savoir qu'il existe des syst�mes de
fichiers qui ne supportent pas les liens symboliques. En bref, la
Meilleure Chose (TM) est d'utiliser le m�canisme source de groff.
Voila comment l'utiliser : si vous voulez que votre page soit
accessible sous les noms truc et bidule dans la section 1, alors
mettez la page de manuel dans truc.1 et r�alisez le fichier bidule.1
contenant :
.SO man1/truc.1
Il est important de sp�cifier le r�pertoire _m_a_n_1_/ aussi bien que le
nom du fichier truc.1 car lors de l'ex�cution de groff, celui-ci aura
comme r�pertoire courant le r�pertoire de base des pages de manuel, et
il interpr�tera les arguments de .SO comme �tant relatifs � cet
emplacement.
55..
QQuueell eennsseemmbbllee ddee mmaaccrrooss uuttiilliisseerr ??
Il y a de nombreux ensembles de macros �tudi�s sp�cialement pour
�crire des pages de manuel. Ils sont habituellement dans le r�pertoire
de macro de groff _/_u_s_r_/_l_i_b_/_g_r_o_f_f_/_t_m_a_c. Les noms de fichiers sont du
genre _t_m_a_c_._<_q_u_e_l_q_u_e _c_h_o_s_e_>, o� _<_q_u_e_l_q_u_e_-_c_h_o_s_e_> est l'argument de
l'option -m de groff. groff utilisera _t_m_a_c_._<_q_u_e_l_q_u_e_-_c_h_o_s_e_> quand
l'option -m <quelque-chose> sera donn�e. Souvent, l'espace entre "-m"
et <quelque-chose> est oubli�, on �crira donc groff -man pour
formater des pages de manuel en utilisant l'ensemble de macro tman.an.
Voil� la raison de ce nom bizarre "_t_m_a_n_._a_n".
En plus de _t_m_a_n_._a_n, il existe un autre ensemble de macro populaire,
_t_m_a_n_._d_o_c, originaire de l'universit� de Californie � Berkeley (UCB).
De nombreuses pages de manuels de BSD l'utilisent et il semble que UCB
en a fait son standard pour la documentation. Les macros de _t_m_a_n_._d_o_c
sont plus souples mais, h�las, il y a des lecteurs de pages de manuels
qui ne les utilisent pas mais qui appellent toujours groff -man. Par
exemple, toutes les versions du programme xman que j'ai rencontr�es
faisaient la t�te devant les pages de manuels requ�rant _t_m_a_n_._d_o_c. Donc
fa�tes-vous une faveur : utilisez _t_m_a_c_._a_n, utiliser un autre ensemble
de macros est consid�r� comme hasardeux. _t_m_a_c_._a_n_d_o_c est un pseudo
ensemble de macros qui regarde le source et charge soit _t_m_a_c_._a_n ou
_t_m_a_c_._d_o_c. En fait, tous les programmes de lecture du manuel devraient
l'utiliser mais jusqu'� pr�sent, peu le font, aussi il vaut mieux
assurer le coup en se cantonnant au bon vieux _t_m_a_c_._a_n. Tout ce que je
dirais � partir de maintenant concernant les macros est valable
seulement pour _t_m_a_c_._a_n. Si vous voulez quand m�me utiliser les macros
de _t_m_a_c_._d_o_c, voici un pointeur vers leur documentation et un mode
d'emploi tr�s d�taill� : www.bsdi.com/bsdi-man. Vous trouverez un
formulaire de recherche sur cette page. Entrez mdoc et il vous
trouvera mdoc(7) et mdoc.samples(7), un didacticiel sur la r�alisation
des pages de manuel BSD.
66..
QQuueellss pprr��pprroocceesssseeuurrss ppuuiiss--jjee uuttiilliisseerr ??
groff est fourni avec au moins 3 pr�processeurs, tbl, eqn et pic
(certains syst�mes les nomment gtbl, geqn et gpic). Ils sont destin�s
� traduire leurs macros et leurs donn�es en code source troff
standard. tbl est un pr�processeur de tableaux, eqn en est un
d'�quation et de math�matiques et pic g�re les images. Consultez leurs
pages de manuel pour d�couvrir les fonctionalit�s qu'ils proposent.
Mais autant �tre clair : n'�crivez pas de pages de manuel qui
utilisent des pr�processeurs.
eqn produira g�n�ralement un r�sultat catastrophique sur des
p�riph�riques du genre t�l�type, qui malheureusement repr�sentent 99%
des visualtions de pages de manuel. Par exemple _X_A_l_l_o_c_C_o_l_o_r_._3_x
contient des formules avec des exposants. A cause de la nature de ces
terminaux, l'exposant sera sur la m�me ligne que la base. �_N _p_u_i_s_s_a_n_c_e
_d_e_u_x� s'affichera "N2".
Il vaut mieux �viter tbl aussi, car je n'ai jamais vu aucun xman qui
fonctionne avec lui. xman 3.1.6 utilise la ligne de commande suivante
pour formater les pages de manuel, par exemple _s_i_g_n_a_l_(_7_) :
gtbl /usr/man/man7/signal.7 | geqn | gtbl | groff -Tascii -man \
/tmp/xmana01760 2> /dev/null
qui coince sur toutes les sources utilisant gtbl, car sa sortie est
redirig�e encore une fois vers gtbl. Le r�sultat donne une page de
manuel sans votre tableau. Je ne sais pas si c'est un bogue ou une
particularit� de gtbl qui s'�trangle sur sa propre sortie ou si xman
devrait �tre un peu plus gentil et ne pas utiliser gtbl deux fois...
De toute fa�on, si vous voulez un tableau, formatez-le vous-m�me et
mettez-le entre les lignes .nf et .fi ce qui permettra de ne pas le
formater. Vous ne pourrez pas avoir de gras ou d'italique par cette
m�thode mais elle permettra d'avoir votre tableau dans tous les cas.
Je n'ai jamais vu une page de manuel n�cessitant le pr�processeur pic
mais je n'aimerais pas �a. Comme vous pouvez le voir plus haut, xman
ne l'utilise pas et groff ferait s�rement la danse de Saint-Guy en
voyant les donn�es en entr�e.
77..
DDooiiss--jjee ddiissttrriibbuueerr lleess ssoouurrcceess eett//oouu llaa ddooccuummeennttaattiioonn dd��jj�� ffoorrmmaatt��ee ??
Voyons les avantages (+) et les inconv�nients (-) de quelques
possibilit�s choisies :
1. code source uniquement :
� (+) distribution plus petite ;
� (-) inutilisable sur les syst�mes ne disposant pas de groff.
2. verison format�e non compact�e uniquement :
� (+) utilisable m�me sur des syst�mes d�pourvus de groff ;
� (-) l'utilisateur ne peut pas g�n�rer un fichier dvi ou
PostScript ;
� (-) g�chis de l'espace disque sur les syst�mes sachant g�rer aussi
les pages compress�es.
3. version format�e et compact�e seulement :
� (+) utilisables m�me sur des syst�mes d�pourvus de groff ;
� (-) l'utilisateur ne peut pas g�n�rer de fichier dvi ou
PostScript ;
� (-) quel format de compactage utiliser ? .Z ? .z ? .gz ? Tous ?.
4. code source et la version format�e non compact�e :
� (+) accessible m�me sur les syst�mes ne disposant pas de groff ;
� (-) taille de la distribution plus grande ;
� (-) certains syst�mes peuvent n�cessiter des pages de manuels
formatt�es et compact�es ;
� (-) informations redondantes sur les syst�mes �quip�s de groff.
A mon avis, la meilleure solution est de distribuer uniquement le code
source. L'argument selon lequel la documentation ne pourra pas �tre
accessible sur les syst�mes sans groff n'a aucune importance. Plus de
500 pages de manuel du Projet de Documentation de Linux ne sont que
sous forme de code source. Les pages de manuel de XFree86 ne sont
disponibles que sous forme de code source. Les pages de manuel de la
FSF n'existent que sous forme de code source. En fait, j'ai rarement
vu des logiciels distribu�s avec les pages de manuels format�es. Si un
administrateur a besoin que les pages de manuel soient accessibles, il
aura forc�ment install� groff.
88..
QQuueelllleess ssoonntt lleess ccoonnvveennttiioonnss ppoouurr lleess ffoonntteess ??
Avant tout, n'utilisez pas les op�rateurs directs de fonte comme \fB
\fP, etc. Employez des macros avec des arguments. Cette m�thode vous
�vitera une erreur classique : oublier un changement de fonte � la fin
d'un mot ce qui provoque la continuation du gras ou de l'italique
jusqu'au prochain changement de fonte. Croyez-moi, �a arrive plus
souvent qu'on ne le pense !
Les macros _t_m_a_c_._a_n offrent les possibilit�s suivantes :
� .B caract�res gras
� .BI gras et italiques en alternance
� .BR gras et romain en alternance
� .I italiques
� .IB italiques et gras en alternance
� .IR italiques et romain en alternance
� .RB romain et gras en alternance
� .RI romain et italiques en alternance
� .SM taille r�duite (9/10 du corps normal)
� .SB gras, taille r�duite (NON petit et gras en alternance)
X et Y en alternance signifie que les arguments impairs seront
imprim�s en X et les pairs en Y. Par exemple :
.BI "Arg 1 est gras, " "arg2 est en italiques, " "arg3 en gras"
Les guillemets sont n�cessaires pour placer des espaces dans un
argument.
Voil� donc pour ce qui est possible. Voyons maintenant comment il faut
utiliser ces possibilit�s (des parties ont �t� honteusement copi�es de
man(7)) :
Bien qu'il existe de nombreuses conventions typographiques pour les
pages de manuel dans le monde UNIX, l'existence de plusieurs centaines
de pages de manuel sp�cifiques � Linux d�finit nos standards :
Pour les fonctions, les arguments sont toujours en italiques, m�me
dans la section SYNOPSYS, alors que le reste est en gras. Vous
�crirez donc :
.BI "mafonction(int " argc ", char **" argv );
Les noms de fichiers sont toujours en italiques, hormis dans la
section SYNOPSYS o� les fichiers � inclure sont en gras. Vous �crirez
alors :
.I /usr/include/stdio.h
et
.B #include <stdio.h>
Les noms des macros, qui sont habituellement en majuscules, sont en
gras :
.B MAXINT
Lors de l'�num�ration d'une liste de codes d'erreurs, ces codes sont
en gras. Cette liste fait g�n�ralement appel � la macro .TP
(paragraphe avec titre) comme ci-dessous :
.TP
.B EBADF
.I fd n'est pas un descripteur de fichier valide
.TP
.B EINVAL
.I fd ne convient pas pour �tre lu
Toute r�f�rence � une autre page de manuel (ou � la page courante) est
en gras. Si le num�ro de la section du manuel est indiqu�, il s'�crit
en roman, sans espace :
.BR man (7)
Les acronymes sont plus �l�gants lorsqu'ils apparaissent dans un corps
plus petit. Je recommande donc :
.SM UNIX
.SM ASCII
.SM TAB
.SM NFS
.SM LALR(1)
99..
CCoommmmeenntt ddooiiss--jjee pprr��sseenntteerr mmaa ppaaggee ddee mmaannuueell ??
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 ?
1100..
CCoommmmeenntt ppuuiiss--jjee aavvooiirr uunn tteexxttee eenn ppuurr AASSCCIIII ssaannss ttoouuss cceess ffiicchhuuss ^^HH^^
ddee ccoonnttrr��llee ??
Jetez un oeuil � la commande col(1), col peut enlever ces caract�res
d'effacement. Pour les impatients, voici la commande :
$ groff -t -e -mandoc -Tascii manpage.1 | col -bx > manpage.txt
Les options -t et -e disent � groff d'utiliser les pr�processeurs tbl
et eqn. C'est inutile pour les pages de manuel ne n�cessitant pas de
pr�processeur mais cela ne g�ne pas, si ce n'est une surcharge du
processeur. D'un autre c�t�, ne pas utiliser -t alors qu'il est n�ces�
saire fera que les tableaux seront tr�s mal format�s. Vous pourrez
m�me trouver ("deviner" serait un terme plus exact) la commande n�ces�
saire pour traiter tel ou tel document groff (pas uniquement des pages
de manuel) par le biais de grog :
$ grog /usr/man/man7/signal.7
groff -t -man /usr/man/man7/signal.7
En fait, grog signifie "_G_R_O_f_f _G_u_e_s_s", et cet outil fait bien ce qu'il
dit (en anglais, guess = deviner...) : il tente de deviner la commande
n�cessaire pour formater un document groff en fonction de son contenu.
S'il �tait parfait, nous n'aurions jamais plus besoin d'options. Mais
s'il arrive qu'il d�termine un mauvais jeu de macros, je ne l'ai par
contre jamais vu se tromper sur les pr�processeurs � employer.
Voici un petit script Perl r�alis� par l'auteur de ce document, qui
peut supprimer les en-t�tes et les pieds de page, ce qui permet de
gagner quelques longueurs de papier lorsque l'on imprime de longues et
complexes pages de manuel. Sauvez-le dans un fichier nomm� _s_t_r_i_p_-
_h_e_a_d_e_r et mettez-le en mode 755.
#!/usr/bin/perl -n
# pour qu'il avale tout le fichier en une seule fois:
undef $/;
# on enleve les sauts de page:
s/\n{4}\S.{50,}\n{6}\S.{50,}\n{3}/\n/g;
# le premier en-tete et le dernier pied de page:
s/\n\S.{50,}\n//g;
# transorme deux ou plus lignes vides consecutives en une seule:
s/\n{3,}/\n\n/g;
# et voila ce qui reste...
print;
Il faut appeler ce programme en tant que premier filtre apr�s la
comande man, car il se base sur le nombre de sauts de ligne issus de
groff. Par exemple :
$ man bash | strip-headers | col -bx > bash.txt
1111..
CCoommmmeenntt aavvooiirr uunnee bbeellllee ppaaggee ddee mmaannuueell eenn PPoossttSSccrriipptt ??
$ groff -t -e -mandoc -Tps manpage.1 > manpage.ps
Imprimez-la � l'aide de votre imprimante PostScript pr�f�r�e ou d'un
interpr�teur. Voir la section pr�c�dente pour les options.
1122..
CCoommmmeenntt ffaaiirree ffoonnccttiioonnnneerr lleess pprrooggrraammmmeess aapprrooppooss eett wwhhaattiiss ??
Supposons que vous recherchiez les compilateurs install�s sur votre
syst�me et comment les invoquer (nous consid�rons le cas courant, o�
tout le manuel est en langue anglaise). Pour r�pondre � cette question
(fr�quemment pos�e), il faut faire :
$ apropos compiler
f77 (1) - Fortran 77 compiler
gcc (1) - GNU C and C++ compiler
pc (1) - Pascal compiler
apropos et whatis sont utilis�es pour obtenir une r�ponse rapide sur
les pages de manuels qui contiennent des informations sur un certain
sujet. Les deux programmes cherchent dans des fichiers nomm�s _w_h_a_t_i_s
qui sont dans chaque r�pertoire de base du manuel. Comme je l'ai d�j�
dit, les fichiers de la base de donn�es _w_h_a_t_i_s contiennent une entr�e
d'une ligne pour chaque page de manuel dans l'arborescence des
r�pertoires successifs. En fait, cette ligne est exactement celle de
la section NAME (pour �tre pr�cis : tout est r�duit � une seule ligne
et le tiret est supprim�, la section �tant plac�e entre parenth�ses).
Ces fichiers sont cr��s � l'aide du programme makewhatis(8). Il en
existe plusieurs versions, donc r�f�rez-vous � la page de manuel du
programme pour conna�tre les options possibles. Afin que makefile
puisse extraire les sections NAME correctement, il est important que
vous, le r�dacteur du manuel, respectiez le format de cette section
d�crit dans la partie 2. La diff�rence entre apropos et whatis est ce
qu'ils recherchent et o�. apropos (qui est l'�quivalent de man -k)
cherche la cha�ne de caract�res qui lui est pass�e en argument
n'importe o� dans la ligne alors que whatis (�quivalent de man -f)
recherche dans la partie avant le tiret un nom de commande complet.
Par cons�quence, whatis dira s'il y a un manuel de cc mais restera
muet pour gcc.
1133..
LLaa llaanngguuee ffrraann��aaiissee
C'est bien s�r � vous de d�cider si vous allez r�diger votre manuel en
fran�ais, en anglais ou dans ces deux langues. Le fran�ais poss�de des
r�gles typographiques tr�s diff�rentes de l'anglais : n'esp�rez pas
pouvoir les respecter avec les outils de formatage du manuel.
Consultez la documentation de groff si vous d�sirez lui faire prendre
en compte les motifs de c�sure de la langue de Moli�re, mais en ayant
conscience que ce ne sera sans doute pas possible sur tous les
syst�mes sur lesquels votre documentation est susceptible d'�tre
exploit�e.
Vous pouvez utiliser les caract�res accentu�s, pourvu qu'ils soient
saisis selon la norme ISO-8859-1 (standard sous Linux). Les pages
devront alors �tre format�es avec l'option -Tlatin1 . Mais il faudra
que toute la cha�ne de visualisation soit capable de g�rer les
caract�res ISO sur 8 bits, ce qui est rarement le cas sans une
configuration particuli�re des utilitaires more ou less g�n�ralement
employ�s.
Vous voil� pr�venu !
1144..
LLeess ccoonnddiittiioonnss ddee ccooppiiee
Copyright 1995, 96, 97 Jens Schweikardt
[email protected]
T�l�phone : ++49 7151 909516
Sauf mention contraire, les documents Linux _H_O_W_T_O portent le copyright
de leurs auteurs respectifs. Ils peuvent �tre reproduits et distribu�s
en tout ou partie, sur n'importe quel support physique ou
�lectronique, � condition que cette notice soit incluse dans chaque
copie. La redistribution est autoris�e et encourag�e ; toutefois,
l'auteur voudrait en �tre pr�venu.
Toutes les traductions, travaux d�riv�s ou compilation de travaux
incluant des documents Linux _H_O_W_T_O doivent �tre couverts par ce
copyright. C'est-�-dire que vous ne pouvez pas produire un travail
d�riv� d'un HOWTO et imposer des restrictions suppl�mentaires sur sa
distribution. Des d�rogations � ces r�gles peuvent �tre accord�es sous
certaines conditions : contactez le coordinateur des Linux _H_O_W_T_O dont
l'adresse est donn�e plus loin.
En r�sum�, nous d�sirons promouvoir la diffusion de ces informations �
travers tous les canaux de communication possibles. Cependant, nous
voulons conserver la propri�t� des _H_O_W_T_O et aimerions �tre tenu au
courant de tout projet de redistribution.
Si vous avez des questions, contactez Greg Hankins, le coordinateur,
par courrier �lectronique � l'adresse
[email protected].
