man(1). Tout au long de ce HOWTO, une entr�e
du manuel sera simplement appel�e page de manuel,
quelque soit sa longueur r�elle et sans intention sexiste.
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 :
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.
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 :
/dev ;/etc/passwd ;Quelquefois, une lettre est ajout�e au num�ro de section comme
par exemple "xterm.1x" ou "wish.1tk". 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 "xterm(x)" et "wish(tk)"
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 vice verca. 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 "man<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 "mano". Vous pourrez y trouver �galement
des sous-r�pertoires appel�s "cat<s>",
"dvi<s>" et "ps<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 "whatis". 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
"/usr/man/man<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
/mon/option/man. Je vous sugg�re d'utiliser une m�thode
similaire pour vos r�alisations personnelles.
Depuis l'av�nement du "Syst�me de fichiers standard" 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 /usr/man 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 /usr/man est bas� sur l'appendice E du standard POSIX
1003.1 qui d�crit la cha�ne de caract�res
d'authentification locale (qui est la m�thode la
mieux accept�e pour d�crire un environement culturel). La
cha�ne locale se pr�sente sous la forme
<langage>[_<pays>][.<jeu-de-caracteres>][,<version>]
(Reportez vous au FS-Stnd pour voir quelques cha�nes
localecourantes.) D'apr�s ces recommandations, nous
avons nos pages de manuel dans
/usr/man/<locale>/man[1-9lno]. Les versions
format�es se trouveraient alors bien entendu dans
/usr/man/<locale>/cat[1-9lno] : 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 <locale> et stocker toutes ces pages dans le r�pertoire mandir. Par exemple, les machines �quip�es seulement de pages de manuel en anglais cod�es en ASCII peuvent mettre les pages de manuel (les r�pertoires man[1-9]) directement dans /usr/man/. Il s'agit en fait de l'arrangement 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.
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).
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 :
groff
fournie par la macro ".SO".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
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.
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 /usr/lib/groff/tmac. Les noms de
fichiers sont du genre tmac.<quelque chose>, o�
<quelque-chose> est l'argument de l'option -m
de groff. groff utilisera
tmac.<quelque-chose> 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 "tman.an".
En plus de tman.an, il existe un autre ensemble de macro
populaire, tman.doc, 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 tman.doc 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 tman.doc. Donc fa�tes-vous
une faveur : utilisez tmac.an, utiliser un autre ensemble
de macros est consid�r� comme hasardeux. tmac.andoc est
un pseudo ensemble de macros qui regarde le source et charge soit
tmac.an ou tmac.doc. 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 tmac.an. Tout ce que je
dirais � partir de maintenant concernant les macros est valable
seulement pour tmac.an. Si vous voulez quand m�me utiliser
les macros de tmac.doc, 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.
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
XAllocColor.3x 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 puissance
deux» 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 signal(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.
Voyons les avantages (+) et les inconv�nients (-) de quelques possibilit�s choisies :
groff.groff ;groff ;groff ;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.
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 tmac.an 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
.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)
Voil� quelques conseils pour rendre votre documentation plus s�re, plus lisible et plus «formatable» :
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
makewhatis(8) pourra extraire la ligne
de description de la section NAME ?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
-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�cessaire fera que les tableaux seront tr�s
mal format�s. Vous pourrez m�me trouver ("deviner" serait un
terme plus exact) la commande n�cessaire 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 "GROff Guess", 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� strip-header 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
$ groff -t -e -mandoc -Tps manpage.1 > manpage.ps
apropos et whatis ? 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
whatis 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 whatis 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.
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 !
Copyright 1995, 96, 97 Jens Schweikardt schweikh@noc.dfn.de
T�l�phone : ++49 7151 909516
Sauf mention contraire, les documents Linux HOWTO 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 HOWTO 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 HOWTO 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 HOWTO 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 gregh@sunsite.unc.edu.