Organisation du source d'une page du manuel

2 Organisation du source d'une page du manuel

Les fichiers sources des pages de manuel sont au format nroff/troff et utilisent les macros du paquetage man. Sur une machine Linux, la page de manuel man(7) donne une description de ce paquetage.

En bref, un fichier troff est composée de lignes de texte entrecoupées de lignes de formatage du texte. Ces lignes de formatage sont constituées d'un nom de macro qui débute forcément par un point et d'éventuels paramètres de la macro. La macro ." introduit un commentaire. L'exemple suivant est extrait de la page de manuel de ls(1) :

." LS fileutils manual page rel. 7.65
.TH LS 1 "December 1999" "GNU fileutils 4.0" "FSF"
.SH NAME 
ls \- list directory contents
.SH SYNOPSIS
.B ls
[
.I OPTION
]... [
.I FILE
]...
.PP
List information about the FILEs (the current directory by
default).

La macro .TH introduit le titre, et les haut et bas de page de la page de manuel. Remarquez que les arguments de la macro sont séparés par des espaces ; aussi on utilise les guillemets " pour coder un espace au sein d'un argument. La macro .SH introduit une section du manuel. Les macros .B et .I indiquent respectivement d'utiliser une fonte grasse et italique. La macro .PP débute un nouveau paragraphe.

Un affichage de la page pourra rendre quelque chose comme :

LS(1)   FSF   LS(1)

NAME
    ls - list directory contents

SYNOPSIS
    ls [OPTION]... [FILE]...
    List information about the FILEs (the current directory by default).

On peut aussi trouver des séquences d'échappement au sein de source troff. Ces séquences commencent par un ``\''. La séquence ``\e'' code le caractère ``\'' ; la séquence ``\-'' le tiret ``--''. Les séquences ``\fx'' changent la fonte courante. ``\f1'' ou ``\fR'' désigne la fonte Roman (celle par défaut) ; ``\f2'' ou ``\fI'' une fonte italique ; ``\f3'' ou ``\fB'' une fonte grasse. Ainsi les deux extraits suivants de code troff sont équivalents :

SYNOPSIS 
.B ls
[
.I OPTION
]... [
.I FILE
]...

SYNOPSIS \fBls\fR [\fIOPTION\fR ]... [\fIFILE\fR]...

Parmi les sections d'une page de manuel, on peut trouver une section SEE ALSO qui renvoie à des commandes << proches >> de la commande courante. Voici un extrait du source de la page de manuel de la commande man(1) :

.SH "SEE ALSO"
apropos(1), whatis(1), less(1), groff(1).