MAN(7) Manuel de l'administrateur Linux MAN(7)
NOM
man - Macros pour la mise en forme des pages de manuel.
SYNOPSIS
groff -Tascii -man file ...
groff -Tps -man file ...
man [section] title
DESCRIPTION
Cette page de manuel explique le contenu du package groff
tmac.an. Ce package doit être utilisé par les
développeurs pour écrire ou porter des pages de manuels
pour Linux. Il est largement compatible avec d'autres ver
sions de ce package, donc le portage de pages pour Linux
ne devrait pas poser de problèmes (sauf pour NET-2 BSD qui
utilise un package complètement différent).
Notez que les pages de manuel NET-2 BSD peuvent être visu
alisées avec groff simplement en spécifiant l'option -mdoc
à la place de l'option -man. L'utilisation de l'option
-mandoc est néanmoins recommandée puisqu'il détectera
automatiquement le package utilisé.
PRÉAMBULE
La première commande d'une page de manuel doit être
.TH titre section date source manuel,
où :
titre Le titre de la page de manuel (par exemple
MAN).
section Le numéro de section dans laquelle placer
la page (par exemple 7).
date La date de la dernière modification. Pensez
à modifier cette date à chaque changement
dans la page, car c'est la maniere la plus
courante d'avoir un contrôle de version.
source La source de la commande
Pour les exécutables, utilisez quelque
chose comme GNU, NET-2, SLS Distribution,
MCC Distribution.
Pour les appels systèmes, indiquez la ver
sion du noyau que vous utilisez : Linux
0.99.11.
Pour les fonctions de bibliothèque,
Linux 20 Octobre 1996 1
MAN(7) Manuel de l'administrateur Linux MAN(7)
utilisez la source de la fonction : GNU,
BSD 4.3, Linux DLL 4.4.1.
manuel Le titre du manuel (par exemple Manuel du
programmeur Linux).
Les sections du manuel sont traditionnellement réparties
ainsi :
1 Commandes
Les commandes qui peuvent être invoquées
par l'utilisateur depuis le shell.
2 Appel systèmes
Les fonctions fournies par le noyau.
3 Fonctions de bibliothèques
La plupart des fonctions de la libc telles
que sort(3))
4 Périphériques
Fichiers spéciaux trouvés dans /dev)
5 Formats de fichiers et conventions
Le format de /etc/passwd et d'autres
fichiers lisibles par un humain.
6 Jeux
7 Ensembles de macros et de standards
Une description du système de fichiers
standard, cette page de manuel, des jeux de
caractères, entre autres...
8 Commandes d'administration système.
Les commandes comme mount(8), que seul root
peut exécuter.
9 Routines du noyau
Il s'agit d'une section non-standard, et
est incluse ici car le code source de Linux
est librement disponible sous license GPL,
et beaucoup de gens travaillent sur les
changements dans le noyau.
FONTES
Bien qu'il y ait de nombreuses conventions arbitraires
concernant les pages de manuel pour UNIX, l'existence de
plusieurs centaines de pages spécifiques à Linux définit
nos propres standards :
Pour les fonctions, les arguments sont toujours
indiqués en italique, même dans le paragraphe SYN
OPSIS, ou le reste de la fonction est en caractère
Linux 20 Octobre 1996 2
MAN(7) Manuel de l'administrateur Linux MAN(7)
gras:
int mafonction(int argc, char **argv);
Les noms de fichiers sont toujours en italique (par
exemple /usr/include/stdio.h), sauf dans le para
graphe SYNOPSIS, ou les fichiers inclus sont en
gras (par exemple #include <stdio.h>).
Les macros, généralement en majuscule, sont en gras
(par exemple MAXINT).
Dans l'énumeration d'une liste de code d'erreurs,
les codes sont en gras, et la liste utilise nor
malement la macro .TP.
Toute référence à une autre page de manuel, ou au
sujet principal de la page en cours, est en gras.
Si le numéro de section de manuel est donné, il est
en Roman, sans espace (par exemple man(7)).
Les commandes pour sélectionner les fontes sont les
suivantes :
.B Gras
.BI Gras alterné avec Italique
.BR Gras alterné avec Roman
.I Italique
.IB Italique alterné avec Gras
.IR Italique alterné avec Roman
.RB Roman alterné avec Gras
.RI Roman alterné avec Italique
.SB Petit alterné avec Gras
.SM Petit
Traditionnellement, chaque commande peut avoir jusqu'à six
arguments, mais les versions GNU semblent éliminer cette
contrainte. Les arguments sont délimités par des espaces.
Des guillemets sont utilisés pour encadrer un argument qui
contient des espaces. Tous les arguments seront imprimés
les uns après les autres sans inercaler d'espace, ainsi la
commande .BR peut être utilisée pour indiquer un mot en
Gras suivi par un signe de ponctuation en Roman.
SECTIONS (PARAGRAPHES)
Les sections commencent par .SH suivies de leurs titres.
Linux 20 Octobre 1996 3
MAN(7) Manuel de l'administrateur Linux MAN(7)
Si le titre contient des espaces, l'encadrer par des
guillemets. Les titres traditionnels sont : NOM, SYNOP
SIS, DESCRIPTION, OPTIONS, FICHIERS, VOIR AUSSI, DIAGNOS
TIQUE, BUGS, et AUTEUR. Le seul titre indispensable est
NOM, qui doit être suivi sur la ligne suivante par une
courte description du programme :
.SH NOM
chess \- Jeu d'echec
Il est tres important que ce format soit respecté, et
qu'il se trouve un backslash avant le tiret suivant le nom
du programme. Il est important que toute la description
soit placée sur une seule ligne. Cette syntaxe est
utilisée par le programme makewhatis(8) pour créer la base
de données des descriptions pour les commandes whatis(1)
et apropos(1).
NDT : Vous vous doutez bien que la version de distribution
de makewhatis(8) ne reconnaît pas la section 'NOM' mais la
section 'NAME'. Pour que les commandes whatis(1) et apro
pos(1) fonctionnent, il faut modifier le script make
whatis(8). la modification à apporter est décrite dans le
fichier LISEZ_MOI, qui est livré avec l'archive des pages
de manuel en français.
AUTRES MACROS
D'autres macros sont disponibles :
.DT Tabulation par défaut.
.HP Début d'indentation.
.IP Début de paragraphe avec un mot-clé. C'est le même
format que .TP, sauf que le mot-clé est sur la même
ligne, pas sur la suivante.
.LP Comme .PP
.PD Fixe la distance entre paragraphe à la valeur
fournie en argument
.PP Commencer un nouveau paragraphe
.RE Fin d'indentation relative (dans un paragraphe)
.RS Début d'indentation relative (dans un paragraphe)
.SS Sous-titre, comme .SH, mais pour une sous-section
.TP Début de paragraphe avec un mot-clé. Ce mot est sur
la ligne suivante. Commande similaire à .IP
Linux 20 Octobre 1996 4
MAN(7) Manuel de l'administrateur Linux MAN(7)
FICHIERS
/usr/local/lib/groff/tmac/tmac.an
/usr/man/whatis
VOIR AUSSI
groff(1), man(1), whatis(1), apropos(1), makewhatis(8)
TRADUCTION
Christophe Blaess, 1997.
Linux 20 Octobre 1996 5