Réaliser des pages de manuel à l'aide de groff

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 manuel^4.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 apropos^4.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.