Manpages - Tutorial

1. Historique

Les systèmes UNIX sont réputés pour la richesse de leur documentation. Historiquement, le premier manuel d'utilisation [1] est apparu le 3 novembre 1971. Il n'était disponible que sous format papier, et a été écrit en grande partie par Thompson et Ritchie (sur PDP-11/20 avec ed ;).

Les pages de manuel en ligne (appelées ci-après manpages) sont apparues avec la version 7 d'Unix, diffusée en 1979. Depuis lors, un utilisateur d'UNIX a accès, par l'intermédiaire de la commande man, à une page explicative décrivant le fonctionnant de chacun des programmes installés sur sa machine. La simplicité et l'efficacité des manpages font que celles-ci sont utilisées depuis bientôt 30 ans maintenant, même si plusieurs projets ont été initiés pour remplacer ce système de documentation.

Ce besoin de proposer une autre norme pour éditer des manuels est apparu suite aux différents reproches faits aux manpages. En effet, certains utilisateurs ont pointé du doigt le manque de richesse que proposait ce système au niveau du formattage de texte, la limitation à une page unique par manuel, les faibles possibilités de navigation... C'est pour ces raisons que le projet GNU a développé Texinfo, qui est devenu leur système de documentation officiel, et qui permet de formatter les manuels comme un livre, avec des chapitres, sections ou références croisées. Ce système autorise l'export du manuel dans de nombreux formats différents. D'autres projets on également vu le jour pour concurrencer les manpages. On peut par exemple citer les environnements KDE ou Gnome, qui eux proposent leurs manuels au format html et fournissent leur propre visionneur pour lire ces documentations.

Malgré les efforts fournis pour améliorer le système de documentation trouvé sur les systèmes UNIX, les 'manpages' sont toujours très largement utilisées. Nous décrivons dans ce document l'anatomie d'une manpage, et expliquons comment réaliser rapidement une page de manuel.

2. Utilisation des manpages

2.1 Organisation des manuels

La commande man permet de visualiser les pages de manuel sur les systèmes UNIX. On l'utilise de la manière suivante :

man [section] <page>

page est le nom de la page à visualiser, habituellement le nom du programme dont on veut lire le manuel. L'argument optionnel section permet de spécifier la section dans laquelle chercher le manuel. Les numéros de section sont définis comme suit :

Il se peut qu'un même nom de page se retrouve dans plusieurs sections différentes. C'est le cas par exemple pour man(1) et man(7), printf(1) et printf(3), ...

Remarques :
- La notation page(section) indique que la page de manuel voulue est à aller chercher dans la section indiquée entre parenthèses.
- Il se peut que d'autres sections soient présentes sur certains systèmes, comme la section 9 relative aux routines du noyau, ou bien la section 3p contenant les pages de manuel relatives à perl.

2.2 Le formatage

Les pages de manuel UNIX sont écrites par défaut au format troff [2], qui est un programme permettant de formater du texte, apparu en 1973. Il propose des macros facilitant la mise en forme de textes (paragraphes, marges, polices,...). Des versions plus évoluées de troff peuvent être utilisées sur certains systèmes pour formater les manpages, comme par exemple groff [3], qui en est la version remise au gout du jour par le projet GNU (il existe d'ailleurs une version pour Windows, permettant de lire les pages de manuel sur ce système). Ainsi, pour lire une page de manuel, on peut utiliser la commande suivante:

groff -man -Tascii mon_programme.1

L'option -m indique la macro à utiliser pour interpreter le texte contenu dans le fichier mon_manuel.1. Ici, nous utilisons une macro qui est spécifique à l'écriture des manpages (il en existe d'autres pour construire du postscript, html, ...). La macro à utiliser est précisée avec l'option -m (voir en annexe pour de plus amples précisions sur le choix des macros). Nous spécifions également que la sortie sera sous forme d'un simple texte ascii (option -T).

Remarque : Le nom de fichier contenant une page de manuel est défini par le nom de la commande suivi d'un point et du numéro de section dans laquelle sera rangé le manuel. Dans l'exemple ci-dessus, la commande est un programme dont le nom est mon_programme, et son manuel sera donc naturellement rangé dans la section 1 (c.f. Les différentes sections).

Outre l'utilisation de la commande groff pour visualiser un manuel que l'on vient d'éditer, il est également possible d'utiliser la commande man. En effet, si le fichier mon_programme.1 est rangé dans un répertoire listé dans la variable d'environnement MANPATH, il suffit juste de taper man 1 mon_programme pour obtenir un résultat similaire à la commande utilisant groff. Une manière de tester une page de manuel que l'on veut écrire est donc la suivante:

• créer le chemin quelquepart/man/manX où X est le numéro de section dans lequel on veut inclure son manuel
• rajouter le chemin vers un répertoire temporaire dans la variable d'environnement MANPATH (quelque chose comme MANPATH=${MANPATH}:quelquepart/man; export MANPATH, à adapter suivant le shell utilisé)
• éditer un fichier nommé mon_programme.X dans le répertoire quelquepart/man/manX
• visualiser le résultat obtenu avec man X mon_programme

2.3 Exporter ses manuels

Grâce à l'option -T de la commande groff, il est possible de spécifier un autre format que le format 'manpage' conventionnel pour exporter ses manuels. On peut par exemple exporter sa documentation en: ps, dvi ou html. Il est ainsi aisé d'imprimer de longs manuels en les ayant au préalable exporté en postscript, ou bien de les consulter en ligne au format html (le site d'OpenBSD représente une bonne source de documentation, avec des manuels très clairs et détaillés [4]).

3. Structure d'une manpage

3.1 Les balises

Les manpages sont formatées grâce à l'utilisation de balises. Ces balises sont composées de une ou deux lettres précédées d'un point. Voici la liste des principales balises à utiliser pour construire une manpage:

.\"

Ligne de commentaire.

.TH

Spécifie l'en-tête de la page de manuel. Son format est le suivant :

.TH [nom du programme] [numéro de section] [centre du pied de page]
    [section gauche du pied de page] [section centrale de l'en-tête]

.SH

Spécifie une nouvelle section. Les sections sont présentées dans la partie suivante.

.TP

Indique un nouveau paragraphe avec titre. Cela revient à indenter le texte qui vient deux lignes après cette macro.

.PP

Nouveau paragraphe.

Balises relatives à la fonte

Tous les caractères suivants sur la ligne seront formatés, selon le format spécifié comme suit:

• .B caractères gras.
• .I caractères italiques.
• .SM taille réduite.
• .SB gras, taille réduite.

Il est également possible d'utiliser les opérateurs directs \fX ... \fP pour ne formater que le texte entre les \f (avec X une des balises mentionnées plus haut).

3.2 Les sections

NAME :

C'est la seule section requise. Cette section a 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 réspecter le format suivant:

        .SH NAME ls \- list directory contents

Le \- est important ici : le backslash sert à 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.

SYNOPSYS

Cette section est censée donner un aperçu des 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.

DESCRIPTION

Elle explique plus en détail ce que fait le programme. Il s'agit en général d'un paragraphe d'une dizaine de lignes et doit être une source d'information sûre et détaillée. Il peut être utile ici d'expliquer à quoi servent les arguments, le format de fichier, les algorithmes qui effectuent le plus dur du travail.

OPTIONS

Elle donne une description de chaque option, et explique de quelle manière celle-ci influe sur le fonctionnement du programme.

FILES

Cette section 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.

ENVIRONNEMENT

Cette section fait la liste de toutes les variables d'environnement qui affectent le programme ou fonction et explique de quelle manière celles-ci affectent le déroulement du programme. La plupart du temps, les variables contiendront les chemins, nom de fichiers, options par défaut.

DIAGNOSTICS

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 (perror(3)) ou des signaux fatals (psignal(3)) qui peuvent apparaître pendant l'exécution de tout programme.

BUGS

Devrait idéalement ne pas exister. Il est tout de même possible ici de décrire les limitations, les inconvénients, les caractéristiques que certains pourraient prendre pour des défauts.

AUTHOR

Cette section indique l'auteur et les principaux contributeurs qui ont participé à la création du programme. Cette section est utile pour pouvoir envoyer des rapports de bugs ou bien prendre contact avec les auteurs d'un logiciel.

SEE ALSO

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. Il est également possible de faire référence ici à des pages web ou à de la documentation écrite.

Autres sections

Nous avons vu ci-dessus les principales sections des pages de manuel, mais il peut en exister d'autres, comme EXAMPLES, STANDARDS, HISTORY, LICENCE, ... La seule contrainte est de renseigner la section NAME. Pour le reste, on peut découper en autant de section que nécessaire afin de fournir à l'utilisateur le manuel le plus complet possible.

4. Un exemple simple de manpage

4.1 Le fichier source

.\"
.\" This is a manpage example. 
.\" Process this file with:
.\" groff -man -Tascii coffee.1
.\"

.TH  COFFEE 1 "February 18, 2007" "Version 1.0" "Coffee Manual"
.SH NAME Coffee \- USB coffee-machine controller
.SH SYNOPSIS
.B coffee
[\fB-h\fP|\fB-v\fP] [\fB-o\fP \fIorigin\fP] [\fBs\fP \fIquantity\fP] 
[\fB-t\fP \fItemperature\fP] [\fB-c\fP \fIflavor\fP] 
.SH DESCRIPTION
\fBCoffee\fP is an USB coffee-machine controller. The coffee is
configurable, and one can choose between different origins, temperatures, sugar
quantity, and last but not least, you can have a crepe and even specify its flavor.
.SH OPTIONS
The following options are supported:
.TP
\fB-s\fP , \fB--sugar\fP 
Specify the quantity of sugar you want. 
.TP
\fB-t\fP , \fB--temp\fP 
Specify the temperature you want for your coffee.
.br
\fINote:\fP beware that choosing 'hot' could lead to severe injuries.
.TP
\fB-o\fP , \fB--origin\fP 
You can choose where your coffee comes from. Possible choices are:
\fIcolombia\fP, \fIethiopia\fP, \fIcarrouf\fP.
.TP
\fB-c\fP , \fB--crepe\fP 
Specify the crepe flavor you want. Available flavors are \fIrhum\fP and
\fIwhisky\fP for now on.
.TP
\fB-h\fP, \fB--help\f
Print a short help text describing the supported command-line options,
and then exit. 
.TP
\fB-v\fP, \fB--version\f
Display \fBcoffee\fP version and exit.
.SH LICENCE
Copyright (c) 2007 by Frederic Culot. 
.br
This software is released under the GNU General Public License. Please
read the COPYING file for more information. 
.SH BUGS
No bugs.
Anyway, if you find any, please send a report to boss@estat.com so that the
author could be fired.
.SH AUTHOR
\fBFrederic Culot\fP . (Oups, better not mention this!)
.SH SEE ALSO
couscous(1), sugar(5), rhum(5)

4.2 Le résultat

COFFEE(1)		  Coffee Manual			COFFEE(1)


NAME
       Coffee - USB coffee-machine controller

SYNOPSIS
       coffee  [-h|-v]	[-o origin] [s quantity] [-t temperature]
       [-c flavor]

DESCRIPTION
       Coffee is an USB coffee-machine controller. The coffee  is
       configurable,  and  one	can choose between different ori-
       gins, temperatures,  sugar  quantity,  and  last	 but  not
       least, you can have a crepe and even specify its flavor.

OPTIONS
       The following options are supported:

       -s , --sugar 
	      Specify the quantity of sugar you want.

       -t , --temp 
	      Specify the temperature you want for your coffee.
	      Note:  beware  that  choosing  'hot'  could lead to
	      severe injuries.

       -o , --origin 
	      You can choose where your coffee comes from. Possi-
	      ble choices are: colombia, ethiopia, carrouf.

       -c , --crepe 
	      Specify  the  crepe flavor you want. Available fla-
	      vors are rhum and whisky for now on.

       -h, --help
	      Print a short help text  describing  the	supported
	      command-line options, and then exit.

       -v, --version
	      Display coffee version and exit.

LICENCE
       Copyright (c) 2007 by Frederic Culot.
       This  software  is  released  under the GNU General Public
       License. Please read the COPYING file  for  more	 informa-
       tion.

BUGS
       No  bugs.  Anyway, if you find any, please send a
       report to boss@estat.com so that the author could be fired.

AUTHOR
       Frederic	 Culot	<fc@estat.com>. (Oups, better not mention
       this!)

SEE ALSO
       couscous(1), sugar(5), rhum(5)


Version 1.0		February 18, 2007			2

5. Bibliographie

6. Annexes

Quel ensemble de macros utiliser ?

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 ou bien /usr/share/tmac sur les BSD. Les noms de fichiers sont tmac.<format>, où <format> est l'argument de l'option -m de groff. Souvent, l'espace entre "-m" et <format> est oublié, on écrira donc groff -man pour formater des pages de manuel en utilisant l'ensemble de macros tman.an.

En plus de tman.an, il existe un autre ensemble de macros assez répandu, tman.doc, originaire de l'université de Californie à Berkeley (UCB). De nombreuses pages de manuels de BSD l'utilisent. Les macros de tman.doc sont plus souples mais tous les lecteurs ne permettent pas de les visualiser correctement. Par exemple, le programme xman ne permet pas de formater correctement les pages de manuels requérant tman.doc.

Il existe égalemen tmac.andoc, qui est un pseudo ensemble de macros qui parcours le source et charge soit tmac.an ou tmac.doc. En fait, tous les programmes de lecture de manuels devraient l'utiliser mais jusqu'à présent, peu le font. Il est donc préférable d'utiliser tmac.an, qui n'est certes pas l'ensemble de macros le plus complet, mais qui permettra de générer des manuels pouvant être visualisés de manière identique partout.

Exporter des manpages en pur ASCII sans ^H

Petite remarque lors de l'export des pages de manuel en ASCII: on peut se retrouver dans certains cas avec des caractères d'effacement (^H) en fin de ligne qui polluent l'affichage du manuel. Pour supprimer ces caractères, il faut utiliser la commande col(1) de la manière suivante :

groff -man -Tascii manuel.1 | col -b > manuel.txt