NOM
man-pages - Conventions pour l’écriture des pages de manuel Linux
SYNOPSIS
man [section] titre
Cette page décrit les conventions utilisées pour les pages de manuel du
projet man-pages pour Linux, qui contient les pages de manuel pour
Linux dans les sections 2, 3, 4, 5 et 7. Les conventions décrites sur
cette page peuvent aussi être utiles aux auteurs de pages de manuels
pour d’autres projets.
Sections des pages de manuel
Les sections du manuel sont traditionnellement les suivantes :
1 Commandes (programmes)
Les commandes qui peuvent être invoquées par l’utilisateur
depuis un interpréteur de commandes.
2 Appels système
Les fonctions fournies par le noyau.
3 Fonctions de bibliothèques
La plupart des fonctions de la bibliothèque C (libc).
4 Fichiers spéciaux (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 Conventions et divers
Panorama de divers sujets, conventions et protocoles, normes
de jeux de caractères, et diverses autres choses.
8 Commandes d’administration système
Les commandes comme mount(8), que seul root peut exécuter.
Paquet de macros
Les nouvelles pages de manuel doivent être mises en forme en utilisant
le paquet groff an.tmac décrit dans man(7). Ce choix est principalement
destiné à assurer une cohérence : la plupart des pages de manuel Linux
sont mises en forme avec ces macros.
Conventions pour l’agencement des sources
Veuillez limiter la longueur des lignes dans le source à environ 75
caractères, autant que faire se peut. Cela permet d’éviter les retours
à la ligne ajoutés par les clients de mail lorsque des patches sont
soumis par ce moyen.
Chaque phrase doit commencer une ligne. Cela permet de voir plus
facilement l’effet des patches, qui s’appliquent souvent au niveau
d’une phrase.
Ligne de titre
La première commande d’une page de manuel doit être une commande TH
.TH titre section date source manuel,
où :
titre Le titre de la page de manuel, en majuscules (par
exemple MAN-PAGES).
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 manière la plus courante d’avoir un contrôle de
version. Les dates doivent être de la forme
AAAA-MM-JJ.
source La source de la commande, fonction, ou de l’appel
système.
Pour les quelques pages de man-pages dans les sections
1 et 8, il est conseillé d’écrire GNU.
Pour les appels système, écrivez simplement Linux.
Précédemment, il était courant d’écrire aussi le
numéro de version du noyau pour laquelle la page de
manuel était écrite. Cependant, cela n’était pas fait
de façon systématique, et était donc pire que
d’omettre simplement le numéro de version. N’incluez
donc pas de numéro de version.
Pour les fonctions de bibliothèque de glibc ou de
l’une des bibliothèques GNU standard, utilisez GNU C
Library, GNU, ou une chaîne vide.
Pour les pages de la section 4, utilisez Linux.
En cas d’hésitation, écrivez Linux ou GNU.
manuel Le titre du manuel (par exemple Linux Programmers
Manual pour les pages des sections 2 et 3 dans le
paquet man-pages)
Sections dans une page de manuel
La liste ci‐dessous indique les sections habituelles ou suggérées. La
plupart des pages devraient contenir au moins les sections mises en
évidence. Dans les nouvelles pages de manuel, placez les sections dans
l’ordre indiqué dans la liste.
NAME
SYNOPSIS
CONFIGURATION [En général seulement section 4]
DESCRIPTION
OPTIONS [En général seulement sections 1, 8]
EXIT STATUS [En général seulement sections 1, 8]
RETURN VALUE [En général seulement sections 2, 3]
ERRORS [Typiquement uniquement sections 2, 3]
ENVIRONMENT
FILES
VERSIONS [En général seulement sections 2, 3]
CONFORMING TO
NOTES
BUGS
EXAMPLE
SEE ALSO
Lorsque lune des sections traditionnelles sapplique, utilisez-la ;
cette cohérence rend l’information plus facile à comprendre. Si cela
est nécessaire, vous pouvez créer vos propres titres de sections si
cela rend les choses plus compréhensibles (particulièrement pour les
pages des sections 4 et 5). Cependant, avant de faire cela, vérifiez
qu’aucun des titres de sections traditionnels ne peut être utilisé,
avec des sous‐sections (.SS).
La liste suivante décrit le contenu de chacune des sections ci‐dessus.
NAME Le nom de cette page. D’importants détails sur les lignes
qui doivent suivre la commande .SH NAME se trouvent dans
la page man(7).
SYNOPSIS Indique brièvement l’interface de la commande ou de la
fonction. Pour les commandes, ce paragraphe montre sa
syntaxe et ses arguments. Les caractères gras marquent le
texte invariable et l’italique indique les arguments
remplaçables. Les crochets « [] » encadrent les arguments
optionnels, les barres verticales « | » séparent les
alternatives, et les ellipses «... » signalent les
répétitions. Pour les fonctions, on trouve toutes les
déclarations et directives #include, suivies de la
déclaration de fonction.
Si une macro de test de fonctionnalité doit être définie
pour obtenir la déclaration d’une fonction (ou d’une
variable) dans un fichier d’en-tête, alors la section
SYNOPSIS doit l’indiquer, comme décrit dans
feature_test_macros(7).
CONFIGURATION Détails de configuration pour un périphérique. Cette
section est présente normalement que dans les pages de la
section 4.
DESCRIPTION Fournit une explication sur ce que la commande, la
fonction ou le format représente. Décrit les interactions
avec les fichiers et l’entrée standard, ou ce qui est
produit sur la sortie standard ou d’erreur. Ne contient
pas les détails d’implémentation internes, sauf s’ils
sont critique pour comprendre l’interface. Décrit le cas
principal, pour les détails sur les options, on utilise
le paragraphe OPTIONS.
OPTIONS Décrit les options acceptées par le programme et leur
influence sur son comportement. Cette section ne doit
être utilisée que pour les pages de manuel des sections 1
et 8.
EXIT STATUS (CODE DE RETOUR)
Indique les codes de retour d’un programme et les
conditions associées. Cette section ne doit être utilisée
que pour les pages de manuel des sections 1 et 8.
RETURN VALUE (VALEUR RENVOYÉE)
Pour les pages des sections 2 et 3, donne une liste des
valeurs qu’une routine de bibliothèque renverra à
l’appelant et les conditions qui provoquent ces retours.
ERRORS Pour les pages des sections 2 et 3, cette partie contient
une liste des valeurs possibles de errno en cas d’erreur,
avec la description des causes de ces erreurs. La liste
derreurs doit tre trie par ordre alphabtique.
ENVIRONMENT (ENVIRONNEMENT)
Décrit toutes les variables d’environnement qui affectent
le programme ou la fonction, ainsi que leurs effets.
FILES (FICHIERS)
Liste les fichiers utilisés par le programme ou la
fonction, tels que fichiers de configuration, de
démarrage, et les fichiers manipulés directement par le
programme. Il faut donner le chemin d’accès complet des
fichiers et utiliser le mécanisme d’installation pour
modifier le préfixe. Pour la plupart des programmes,
l’installation par défaut se fait dans /usr/local, aussi,
votre page de manuel de base devrait utiliser /usr/local
comme base.
VERSIONS Un court résumé de la version du noyau Linux ou de la
glibc où l’appel système ou la fonction de bibliothèque
est apparu, ou dont le fonctionnement est modifié de
manière significative. De manière générale, la page de
manuel de chaque nouvelle interface devrait inclure une
section VERSIONS. Malheureusement, bien des pages de
manuel existantes n’incluent pas cette information (car
il n’y avait pas de politique pour le faire lors qu’elles
ont été rédigées). Les correctifs pour y remédier sont
les bienvenus. Dans la perpective d’écriture de nouveau
code, cette information n’a de sens que dans le cas
d’interface noyau ajoutée à Linux 2.4 ou suivant
(c’est-à-dire les modifications depuis la version 2.2 du
noyau), et les fonctions de la bibliothèque ajoutées dans
glibc depuis la version 2.1 (c’est-à-dire les
modifications depuis la version 2.0 de la glibc).
La page de manuel syscalls(2) fournit également des
informations de versions de noyau dans lesquelles sont
apparus les appels système.
CONFORMING TO (CONFORMITÉ)
Décrit les normes ou conventions liées à la fonction ou à
la commande décrite par la page de manuel. Pour une page
dans la section 2 ou 3, cette section doit indiquer la
version de POSIX.1 à laquelle l’appel se conforme, et
s’il est spécifié par C99. (Il est inutile de trop se
préoccuper des autres normes comme SUS, SUSv2 ou XPG, ou
des implémentations SVr4 ou BSD4.x, sauf si la fonction
était présente dans ces systèmes mais n’est pas dans la
version actuelle de POSIX.1. (Voir standards(7).)
Si la fonction n’est gouvernée par aucun standard, mais
existe sur d’autres systèmes, mentionnez‐les. Si elle est
spécifique à Linux, notez‐le.
Si cette section ne consiste qu’en une liste de normes
(ce qui est d’habitude le cas), terminez la liste par un
point (« . »).
NOTES Contient des notes diverses. Pour les pages des sections
2 et 3, il peut être utile d’utiliser des sous‐sections
(SS) appelées Linux Notes ou Glibc Notes.
BUGS (BOGUES) Liste les limitations ou les défauts recensés, ainsi que
les sujets à débat.
EXAMPLE (EXEMPLE)
Donne un ou plusieurs exemples d’utilisation de la
fonction, du fichier ou de la commande. Pour plus de
détails sur l’écriture d’exemples de programmes, voir la
section qui y est consacrée ci‐dessous.
AUTHORS (AUTEURS)
Liste les auteurs de la documentation ou du programme.
L’utilisation d’une section AUTHORS est fortement
découragée. En général, il vaut mieux ne pas remplir les
pages de manuel avec une liste (potentiellement longue)
d’auteurs ; si vous écrivez ou modifiez de façon
importante une page, ajoutez une notice de copyright en
commentaire dans le fichier source. Si vous êtes l’auteur
d’un pilote de périphérique et voulez inclure une adresse
pour signaler les bogues, placez‐la dans la section BUGS.
SEE ALSO (VOIR AUSSI)
Fournit une liste des pages de manuel (séparées par des
virgules) ayant un rapport, dans l’ordre des sections
puis alphabétique, suivies des autres documents
éventuels. Ne terminez pas la liste par un point.
Conventions de fontes
Pour les fonctions, les arguments sont toujours indiqués en italique,
mme dans le paragraphe SYNOPSIS, où le reste de la fonction est en
caractères gras :
int myfunction(int argc, char **argv);
Les noms de variables devraient, tout comme les noms de paramètres,
être formatés en italique.
Les noms de fichiers, que ce soit des chemins ou des références à des
fichiers du répertoire /usr/include) sont toujours en italique (par
exemple <stdio.h>), sauf dans le paragraphe SYNOPSIS, où les fichiers
inclus sont en gras (par exemple #include <stdio.h>). Lorsque vous
faites référence à un fichier d’entête standard situé dans
/usr/include, spécifiez le fichier d’entête entouré avec les symboles
inférieur et supérieur, de la même manière que dans un fichier source C
(par exemple, <stdio.h>).
Les macros, généralement en majuscules, sont en gras (par exemple
MAXINT). Exception : NULL ne doit pas être en gras.
Dans l’énumération d’une liste de code d’erreurs, les codes sont en
gras, et la liste utilise normalement la macro .TP.
Les commandes complètes devraient, si elles sont longues, être écrites
sous forme indentée, par exemple
man 7 man-pages
Si la commande est courte, elle peut être incluse dans le texte, en
italique, par exemple, man 7 man-pages. Dans ce cas, il peut être
intéressant d’utiliser des espaces insécables (« \ ») aux endroits
appropriés dans la commande. Les options des commandes doivent elles
aussi être formatées en italique, par exemple, -l.
Les expressions, si elles ne sont pas écrites sur une ligne indentée,
devraient être mises en italique. Ici aussi, l’utilisation d’espaces
insécables est appropriée si l’expression est mélangée à du texte
normal.
Toute référence au sujet de la page de manuel courante doit être écrite
en gras. Si le sujet est une fonction (c’est‐à‐dire s’il s’agit d’une
page de section 2 ou 3), le nom doit être suivi d’une paire de
parenthèses en caractères romans (normaux). Par exemple, dans la page
fcntl(2), les références au sujet de la page sont écrites fcntl(). La
façon d’écrire ceci dans le fichier source est :
.BR fcntl ()
(avec ce format au lieu de « \fB...\fP() » le travail d’outils qui
parsent les sources des pages de manuel est plus facile)
Toute référence à une autre page de manuel, ou au sujet principal de la
page en cours, est en gras, et toujours suivi du numéro de section, en
fonte normale, sans espace (par exemple intro(2)). Dans le source, on
l’écrit habituellement de cette façon :
.BR intro (2)
(inclure le numéro de section dans les références croisées permet à des
outils comme man2html(1) de créer des liens hypertexte appropriés)
Orthographe
A partir de la version 2.59, la version anglaise de man-pages suit les
conventions orthographiques américaines ; veuillez écrire les nouvelles
pages et les rustines en suivants ces conventions.
Programmes d’exemples et sessions shell.
Les pages de manuel peuvent contenir des programmes permettant de
montrer comment utiliser un appel système ou une fonction de
bibliothèque. Cependant, veuillez noter ceci :
* Les programmes d’exemple doivent être écrits en C.
* Un programme d’exemple n’est nécessaire et utile que s’il montre
quelque chose qui ne peut pas être fourni facilement dans une
description de l’interface. Un programme d’exemple qui ne fait
qu’appeler une fonction ne sert en général à rien.
* Les programmes d’exemple doivent être plutôt courts (de préférence
moins de 100 lignes, idéalement moins de 50 lignes).
* Les programmes d’exemple doivent vérifier les erreurs après les
appels système et les appels de fonctions de bibliothèque.
* Les programmes d’exemple doivent être complets et compiler sans
avertissements avec cc -Wall.
* Si possible et raisonnable, les programmes d’exemples doivent
permettre d’expérimenter, en changeant de comportement en fonction
des entrées (arguments de ligne de commande, ou bien entrées lues
par le programme).
* Les programmes d’exemple doivent être mis en forme dans le style de
Kernighan et Ritchie, avec des indentations de 4 espaces (évitez
d’utiliser le caractère tabulation dans les fichiers source !).
Pour voir à quoi les programmes d’exemples devraient ressembler, voyez
wait(2) et pipe(2).
Si vous incluez une session d’interpréteur de commandes pour démontrer
l’utilisation d’un programme ou d’autres fonctionnalités système,
mettez le texte entré par l’utilisateur en gras pour le distinguer de
la sortie produite par le système.
Indentation des définitions de structure, session shell, etc.
Lorsque des définitions de structure, des sorties de session shell,
etc. sont inclus dans le texte courant, indentez-les avec 4 espaces
(c’est-à-dire un bloc entouré par .in +4n et .in).
EXEMPLE
Pour des exemples canoniques de pages de manuel du paquet man-pages,
voir pipe(2) et fcntl(2).
VOIR AUSSI
man(1), man2html(1), groff(7), groff_man(7), man(7), mdoc(7)
COLOPHON
Cette page fait partie de la publication 3.23 du projet man-pages
Linux. Une description du projet et des instructions pour signaler des
anomalies peuvent être trouvées à l’adresse
http://www.kernel.org/doc/man-pages/.
TRADUCTION
Cette page de manuel a été traduite et est maintenue par Julien Cristau
<julien.cristau@ens-lyon.org> et l’équipe francophone de traduction de
Debian.
Veuillez signaler toute erreur de traduction en écrivant à
<debian-l10n-french@lists.debian.org> ou par un rapport de bogue sur le
paquet manpages-fr.
Vous pouvez toujours avoir accès à la version anglaise de ce document
en utilisant la commande « man -L C <section> <page_de_man> ».