Lorsque l'on crée un logiciel, la documentation jointe joue un rôle important dans son succès. Sous Linux, la première aide que l'on puisse apporter à l'utilisateur prend la forme de man pages ou, en bon français, de pages de manuel. Celles-ci portent habituellement le nom du programme et sont appelées par la commande man suivie du nom en question. Cet article décrit la création d'une telle page.
LES MAN PAGES
Si vous jetez un oeil dans l'arborescence du système Linux, vous trouverez dans /usr/man, un grand nombre de répertoires comprenant des fichiers avec une extension .gz. Il s'agit des pages de manuel classées par catégorie et compressées par l'utilitaire gzip.
Les différentes catégories de man pages sont :
1 - Commandes utilisateurs
2 - Appels systèmes
3 - Fonctions des bibliothèques
4 - Fichiers spéciaux
5 - Format de fichiers
7 - Divers
8 - Administration système
Toutes les man pages
respectent la même organisation. En effet, lorsque vous visualisez
une page, les informations sont classées de manière stricte.
On retrouve, dans l'ordre, le nom du logiciel (NOM), un synopsis présentant
les options (SYNOPSIS), un descriptif comprenant les explications des
options (DESCRIPTION), les fichiers concernés (FICHIERS), les liens
vers d'autres man pages (VOIR AUSSI), d'eventuelles notes (NOTES), une
signature (AUTEUR) et enfin les éventuels bogues ou problèmes
(BOGUES).
Si vous vous lancez dans la rédaction d'une page man, n'oubliez
jamais cette convention. C'est elle qui garantie la clarté
de vos explications.
REDACTION D'UNE PAGE
Le programme
utilisé pour lire des pages de manuel est groff. Il s'agit d'un
utilitaire de formatage de texte à l'instar de TeX ou LaTeX. Son
mode de fonctionnement repose sur la création d'un script qui sera
ensuite interprété par groff. Il en résultera un
affichage formaté de manière spécifique. Vous pourrez
ensuite le placer dans le répertoire prévu à
cet effet dans l'arborescence du système pour le consulter avec
la commande man.
Les personnes ayant déjà utilisé TeX ou un langage
comme HTML retrouveront facilement leurs marques avec groff. Utilisé
pour la création des man pages, groff vous permettra également
de créer des documents PostScript ou DVI.
Afin de bien comprendre le fonctionnement de groff, jetez un petit coup
d'oeil à l'exemple en figure 1. On peut constater de prime-abord
que certaines commandes de formatage reviennent à intervalles réguliers.
Voyons ensemble leurs significations :
.TH définit le titre de la page ; Ici LMAG suivi de la date
.SH décrit un début de section comme par exemple NOM, SYNOPSIS,
etc.
.SS annonce le début d'une sous-section (ici, les options)
.TP permet de définir chaque entrée d'une liste. Dans notre
exemple, il s'agit de la liste des options.
D'autres commandes
de formatage permettent de mettre des éléments du texte
en valeur par rapport à l'ensemble.
permet de revenir à la police (font) précédemment
utilisée. Cette commande s'utilise après un changement avec
les commandes qui suivent.
active le passage en mode gras (bold) pour le texte qui suit jusqu'à
.
active le passage en mode italique de la même manière que
.
active le passage en police Romande jusqu'au prochain .
LECTURE D'UNE PAGE DE MANUEL
Afin de tester votre
page toute fraîche, tapez ce qui suit dans le répertoire
où est placé le fichier man (ici lmag.1) :
groff -Tascii -man lmag.1 | less
Nous appelons l'utilitaire groff avec les paramètres -Tascii pour
obtenir une sortie ASCII en utilisant les macros man (-man). Nous redirigeons
ensuite la sortie obtenue vers la commande less avec un pipe (tuyau) afin
de pouvoir faire défiler le texte sur l'écran.
Si vous désirez
obtenir un fichier PostScript ou DVI de votre man page utilisez le paramètre
-Tps ou -Tdvi et redirigez la sortie vers un fichier.
Exemple :
groff -Tps -man lmag.1 > lmag.ps
Vous obtiendrez un fichier lmag.ps lisible avec GhostScript et imprimable
directement sur n'importe quelle imprimante PostScript.
Finalement, pour installer votre page, copiez-la dans le répertoire /usr/man/man1. Elle pourra ensuite être affichée avec la commande man lmag. Vous pouvez également compresser votre man page avec l'utilitaire gzip avant de la copier en tapant gzip lmag.1.
FIG 1
.TH LMAG 1 16 octobre
1998"
.SH NOM
lmag - Linux Magazine France
.SH SYNOPSYS
[--version] [-p ]
.SH DESCRIPTION
genère automatiquement une page de Linux Magazine France.
.SS Options
.TP
-version
Affiche le numéro de version du programme
.TP
p
spécifie la page générer. Il sagit d'un numéro
de page.
.SH FICHIER
.TP
/dev/lmag0
Le péripherique de contrôle de la rédaction de Linux
Magazine
.SH VOIR AUSSI
pao(1), kiosque(1)
.SH BOGUE
Nécessite parfois une relecture orthographique