La rédaction d'une page de manuel consiste en l'écriture d'un fichier qui, formaté via la commande groff, affiche la page de manuel4.2. Pour réaliser une page de manuel d'une commande imaginaire coffee, par exemple, il faut d'abord éditer le fichier coffee.man. Ce fichier peut ressembler à ceci :
.TH COFFEE 1 "29 Juillet 94" .SH NOM coffee \- Controle la machine a cafe .SH SYNOPSIS \fBcoffee\fP [ -c | -b ] [ -t \fItype\fP ] \fInombre\fP .SH DESCRIPTION \fBcoffee\fP demande a la machine connectee sur \fB/dev/cf0\fR de faire du cafe. Le parametre \fInombre\fP specifie le nombre de tasses. .SS Options .TP \fB-c\fP caffe chaud .TP \fB-t \fItype\fR specifie le type de caffe ou \fItype\fP peut etre \fBColombie\fP .SH FICHIERS .TP \fC/dev/cf0\fR Le periferique de controle de la machine (j'ai fait espray pour la fote) .SH "VOIR AUSSI" lait(5), sucre(5), cognac(5) .SH BOGUES Connait pas les beugues moi, Mosieur !
La séquence .TH affecte le titre de la page de manuel, et .SH un début de section. La syntaxe :
coffee \- Controle la machine a cafe
doit être respectée pour que la page de manuel puisse intégrer la base de données accessible par la commande man -k ou apropos4.3.
Les séquences \fB, \fI et \fR permettent respectivement d'afficher le texte en gras, en italique et de revenir à la police précédente. La séquence .SS permet quand à elle de débuter une sous-section et la séquence .TP permet d'afficher les options en retrait.
Il faut maintenant formatter cette page de manuel, à l'aide de groff :
groff -Tascii -man coffee.man | less
L'option -Tascii précise que le format devra être de type ASCII (l'option -Tps permettrait de formater une page de manuel au format PostScript), et la page de manuel est affichée à l'écran. Le résultat ressemble à ceci :
COFFEE(1) COFFEE(1)
NOM
coffee - Controle la machine a cafe
SYNOPSIS
coffee [ -c | -b ] [ -t type ] nombre
DESCRIPTION
coffee demande a la machine connectee sur /dev/cf0 de
faire du cafe. Le parametre nombre specifie le nombre de
tasses.
Options
-c caffe chaud
-t type
specifie le type de caffe ou type peut etre Colom
bie
FICHIERS
/dev/cf0
Le periferique de controle de la machine (j'ai fait
espray pour la fote)
VOIR AUSSI
lait(5), sucre(5), cognac(5)
BOGUES
Connait pas les beugues moi, Mosieur !
Il ne reste plus qu'à copier ce fichier dans le répertoire contenant les pages de manuel (en changant l'extension .man en .1) :
cp coffee.man /usr/man/man1/coffee.1
Pour installer la page de manuel dans un autre répertoire (par exemple $HOME/man), il faut inclure ce répertoire dans la variable d'environnement $MANPATH :
export MANPATH=$MANPATH:$HOME/man
Cette commande devra être incluse dans un fichier de démarrage (comme le fichier .bashrc, par exemple) pour qu'il soit tenu compte de cette modification à chaque session.
Il ne reste plus qu'à lancer la commande man :
man coffee
La page de manuel devrait alors s'afficher.