Provided by:
manpages-fr_3.32d0.2p4-1_all 
NOM
man-pages - Conventions pour l'ecriture des pages de manuel Linux
SYNOPSIS
man [section] titre
DESCRIPTION
Cette page decrit les conventions utilisees 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 decrites sur
cette page peuvent aussi etre 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 etre invoquees par l'utilisateur
depuis un interpreteur de commandes.
2 Appels syst`eme
Les fonctions fournies par le noyau.
3 Fonctions de biblioth`eques
La plupart des fonctions de la bibliotheque C (libc).
4 Fichiers sp'eciaux (p'eriph'eriques)
Fichiers speciaux trouves 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 caracteres, et diverses autres choses.
8 Commandes d'administration syst`eme
Les commandes comme mount(8), que seul root peut executer.
Paquet de macros
Les nouvelles pages de manuel doivent etre mises en forme en utilisant
le paquet groff an.tmac decrit dans man(7). Ce choix est principalement
destine a assurer une coherence : 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 a environ 75
caracteres, autant que faire se peut. Cela permet d'eviter les retours
a la ligne ajoutes 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 premiere commande d'une page de manuel doit etre une commande TH
.TH titre section date source manuel,
ou :
titre Le titre de la page de manuel, en majuscules (par
exemple MAN-PAGES).
section Le numero de section dans laquelle placer la page (par
exemple 7).
date La date de la derniere modification. Pensez a modifier
cette date a chaque changement dans la page, car c'est
la maniere la plus courante d'avoir un controle de
version. Les dates doivent etre de la forme
AAAA-MM-JJ.
source La source de la commande, fonction, ou de l'appel
systeme.
Pour les quelques pages de man-pages dans les
sections 1 et 8, il est conseille d'ecrire GNU.
Pour les appels systeme, ecrivez simplement Linux.
Precedemment, il etait courant d'ecrire aussi le
numero de version du noyau pour laquelle la page de
manuel etait ecrite. Cependant, cela n'etait pas fait
de facon systematique, et etait donc pire que
d'omettre simplement le numero de version. N'incluez
donc pas de numero de version.
Pour les fonctions de bibliotheque de glibc ou de
l'une des bibliotheques GNU standards, utilisez GNU C
Library, GNU, ou une chaine vide.
Pour les pages de la section 4, utilisez Linux.
En cas d'hesitation, ecrivez Linux ou GNU.
manuel Le titre du manuel (par exemple Linux Programmer's
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 suggerees. La
plupart des pages devraient contenir au moins les sections mises en
'evidence. Dans les nouvelles pages de manuel, placez les sections dans
l'ordre indique dans la liste.
Nom anglais Nom francais Notes
NAME NOM
SYNOPSIS SYNOPSIS
CONFIGURATION CONFIGURATION [En general seulement section 4]
DESCRIPTION DESCRIPTION
OPTIONS OPTIONS [En general seulement sections 1, 8]
EXIT STATUS CODE DE RETOUR [En general seulement sections 1, 8]
RETURN VALUE VALEUR RENVOYEE [En general seulement sections 2, 3]
ERRORS ERREURS [Typiquement uniquement sections 2, 3]
ENVIRONMENT ENVIRONNEMENT
FILES FICHIERS
VERSIONS VERSIONS [En general seulement sections 2, 3]
CONFORMING TO CONFORMITE
NOTES NOTES
BUGS BOGUES
EXAMPLE EXEMPLE
SEE ALSO VOIR AUSSI
Lorsque l'une des sections traditionnelles s'applique, utilisez-la ;
cette coherence rend l'information plus facile a comprendre. Si cela
est necessaire, vous pouvez creer vos propres titres de sections si
cela rend les choses plus comprehensibles (particulierement pour les
pages des sections 4 et 5). Cependant, avant de faire cela, verifiez
qu'aucun des titres de sections traditionnels ne peut etre utilise,
avec des sous-sections (.SS).
La liste suivante decrit le contenu de chacune des sections ci-dessus.
NAME (NOM) Le nom de cette page. D'importants details sur les lignes
qui doivent suivre la commande .SH NAME se trouvent dans
la page man(7).
SYNOPSIS Indique brievement l'interface de la commande ou de la
fonction. Pour les commandes, ce paragraphe montre sa
syntaxe et ses arguments. Les caracteres gras marquent le
texte invariable et l'italique indique les arguments
remplacables. Les crochets << [] >> encadrent les
arguments optionnels, les barres verticales << | >>
separent les alternatives, et les ellipses << ... >>
signalent les repetitions. Pour les fonctions, on trouve
toutes les declarations et directives #include, suivies
de la declaration de fonction.
Si une macro de test de fonctionnalite doit etre definie
pour obtenir la declaration d'une fonction (ou d'une
variable) dans un fichier d'en-tete, alors la section
SYNOPSIS doit l'indiquer, comme decrit dans
feature_test_macros(7).
CONFIGURATION Details de configuration pour un peripherique. Cette
section est presente normalement que dans les pages de la
section 4.
DESCRIPTION Fournit une explication sur ce que la commande, la
fonction ou le format represente. Decrit les interactions
avec les fichiers et l'entree standard, ou ce qui est
produit sur la sortie standard ou d'erreur. Ne contient
pas les details d'implementation internes, sauf s'ils
sont critique pour comprendre l'interface. Decrit le cas
principal, pour les details sur les options, on utilise
le paragraphe OPTIONS.
OPTIONS Decrit les options acceptees par le programme et leur
influence sur son comportement. Cette section ne doit
etre utilisee 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 associees. Cette section ne doit etre utilisee
que pour les pages de manuel des sections 1 et 8.
RETURN VALUE (VALEUR RENVOY'EE)
Pour les pages des sections 2 et 3, donne une liste des
valeurs qu'une routine de bibliotheque renverra a
l'appelant et les conditions qui provoquent ces retours.
ERRORS (ERREURS)
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
d'erreurs doit ^etre tri'ee par ordre alphab'etique.
ENVIRONMENT (ENVIRONNEMENT)
Decrit toutes les variables d'environnement qui affectent
le programme ou la fonction, ainsi que leurs effets.
FILES (FICHIERS)
Liste les fichiers utilises par le programme ou la
fonction, tels que fichiers de configuration, de
demarrage, et les fichiers manipules directement par le
programme. Il faut donner le chemin d'acces complet des
fichiers et utiliser le mecanisme d'installation pour
modifier le prefixe. Pour la plupart des programmes,
l'installation par defaut se fait dans /usr/local, aussi,
votre page de manuel de base devrait utiliser /usr/local
comme base.
VERSIONS Un court resume de la version du noyau Linux ou de la
glibc ou l'appel systeme ou la fonction de bibliotheque
est apparu, ou dont le fonctionnement est modifie de
maniere significative. De maniere generale, 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 ete redigees). Les correctifs pour y remedier sont
les bienvenus. Dans la perpective d'ecriture de nouveau
code, cette information n'a de sens que dans le cas
d'interface noyau ajoutee a Linux 2.4 ou suivant
(c'est-a-dire les modifications depuis la version 2.2 du
noyau), et les fonctions de la bibliotheque ajoutees dans
glibc depuis la version 2.1 (c'est-a-dire les
modifications depuis la version 2.0 de la glibc).
La page de manuel syscalls(2) fournit egalement des
informations de versions de noyau dans lesquelles sont
apparus les appels systeme.
CONFORMING TO (CONFORMIT'E)
Decrit les normes ou conventions liees a la fonction ou a
la commande decrite par la page de manuel. Pour une page
dans la section 2 ou 3, cette section doit indiquer la
version de POSIX.1 a laquelle l'appel se conforme, et
s'il est specifie par C99. (Il est inutile de trop se
preoccuper des autres normes comme SUS, SUSv2 ou XPG, ou
des implementations SVr4 ou BSD 4.x, sauf si la fonction
etait presente dans ces systemes mais n'est pas dans la
version actuelle de POSIX.1, consultez standards(7).)
Si la fonction n'est gouvernee par aucune norme, mais
existe sur d'autres systemes, mentionnez-les. Si elle est
specifique a 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 etre utile d'utiliser des sous-
sections (SS) appelees Linux Notes (Notes sur Linux) ou
Glibc Notes (Notes sur la glibc).
BUGS (BOGUES) Liste les limitations ou les defauts recenses, ainsi que
les sujets a debat.
EXAMPLE (EXEMPLE)
Donne un ou plusieurs exemples d'utilisation de la
fonction, du fichier ou de la commande. Pour plus de
details sur l'ecriture d'exemples de programmes,
consultez la section qui y est consacree ci-dessous.
AUTHORS (AUTEURS)
Liste les auteurs de la documentation ou du programme.
L'utilisation d'une section AUTHORS est fortement
d'ecourag'ee. En general, il vaut mieux ne pas remplir les
pages de manuel avec une liste (potentiellement longue)
d'auteurs ; si vous ecrivez ou modifiez de facon
importante une page, ajoutez une notice de copyright en
commentaire dans le fichier source. Si vous etes l'auteur
d'un pilote de peripherique 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 (separees par des
virgules) ayant un rapport, dans l'ordre des sections
puis alphabetique, suivies des autres documents
eventuels. Ne terminez pas la liste par un point.
Conventions de fontes
Pour les fonctions, les arguments sont toujours indiques en italique,
m^eme dans le paragraphe SYNOPSIS, ou le reste de la fonction est en
caracteres gras :
int myfunction(int argc, char **argv);
Les noms de variables devraient, tout comme les noms de parametres,
etre formates en italique.
Les noms de fichiers, que ce soit des chemins ou des references a des
fichiers du repertoire /usr/include) sont toujours en italique (par
exemple <stdio.h>), sauf dans le paragraphe SYNOPSIS, ou les fichiers
inclus sont en gras (par exemple #include <stdio.h>). Lorsque vous
faites reference a un fichier d'entete standard situe dans
/usr/include, specifiez le fichier d'entete entoure avec les symboles
inferieur et superieur, de la meme maniere que dans un fichier source C
(par exemple, <stdio.h>).
Les macros, generalement en majuscules, sont en gras (par exemple
MAXINT). Exception : NULL ne doit pas etre en gras.
Dans l'enumeration d'une liste de code d'erreurs, les codes sont en
gras, et la liste utilise normalement la macro .TP.
Les commandes completes devraient, si elles sont longues, etre ecrites
sous forme indentee, par exemple
man 7 man-pages
Si la commande est courte, elle peut etre incluse dans le texte, en
italique, par exemple, man 7 man-pages. Dans ce cas, il peut etre
interessant d'utiliser des espaces insecables (<< \ >>) aux endroits
appropries dans la commande. Les options des commandes doivent elles
aussi etre formatees en italique, par exemple, -l.
Les expressions, si elles ne sont pas ecrites sur une ligne indentee,
devraient etre mises en italique. Ici aussi, l'utilisation d'espaces
insecables est appropriee si l'expression est melangee a du texte
normal.
Toute reference au sujet de la page de manuel courante doit etre ecrite
en gras. Si le sujet est une fonction (c'est-a-dire s'il s'agit d'une
page de section 2 ou 3), le nom doit etre suivi d'une paire de
parentheses en caracteres romans (normaux). Par exemple, dans la page
fcntl(2), les references au sujet de la page sont ecrites fcntl(). La
facon d'ecrire 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 reference a une autre page de manuel, ou au sujet principal de la
page en cours, est en gras, et toujours suivi du numero de section, en
fonte normale, sans espace (par exemple intro(2)). Dans le source, on
l'ecrit habituellement de cette facon :
.BR intro (2)
(inclure le numero de section dans les references croisees permet a des
outils comme man2html(1) de creer des liens hypertexte appropries)
Orthographe
A partir de la version 2.59, la version anglaise de man-pages suit les
conventions orthographiques americaines ; veuillez ecrire 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 systeme ou une fonction de
bibliotheque. Cependant, veuillez noter ceci :
* Les programmes d'exemple doivent etre ecrits en C.
* Un programme d'exemple n'est necessaire et utile que s'il montre
quelque chose qui ne peut pas etre fourni facilement dans une
description de l'interface. Un programme d'exemple qui ne fait
qu'appeler une fonction ne sert en general a rien.
* Les programmes d'exemple doivent etre plutot courts (de preference
moins de 100 lignes, idealement moins de 50 lignes).
* Les programmes d'exemple doivent verifier les erreurs apres les
appels systeme et les appels de fonctions de bibliotheque.
* Les programmes d'exemple doivent etre complets et compiler sans
avertissements avec cc -Wall.
* Si possible et raisonnable, les programmes d'exemples doivent
permettre d'experimenter, en changeant de comportement en fonction
des entrees (arguments de ligne de commande, ou bien entrees lues
par le programme).
* Les programmes d'exemple doivent etre mis en forme dans le style de
Kernighan et Ritchie, avec des indentations de 4 espaces (evitez
d'utiliser le caractere tabulation dans les fichiers source !).
Pour voir a quoi les programmes d'exemples devraient ressembler,
consultez wait(2) et pipe(2).
Si vous incluez une session d'interpreteur de commandes pour demontrer
l'utilisation d'un programme ou d'autres fonctionnalites systeme,
mettez le texte entre par l'utilisateur en gras pour le distinguer de
la sortie produite par le systeme.
Indentation des d'efinitions de structure, session shell, etc.
Lorsque des definitions de structure, des sorties de session shell,
etc. sont inclus dans le texte courant, indentez-les avec 4 espaces
(c'est-a-dire un bloc entoure 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.32 du projet man-pages
Linux. Une description du projet et des instructions pour signaler des
anomalies peuvent etre trouvees a l'adresse
<URL:http://www.kernel.org/doc/man-pages/>.
TRADUCTION
Depuis 2010, cette traduction est maintenue a l'aide de l'outil po4a
<URL:http://po4a.alioth.debian.org/> par l'equipe de traduction
francophone au sein du projet perkamon
<URL:http://perkamon.alioth.debian.org/>.
Julien Cristau et l'equipe francophone de traduction de
Debian (2006-2009).
Veuillez signaler toute erreur de traduction en ecrivant a
<debian-l10n-french@lists.debian.org> ou par un rapport de bogue sur le
paquet manpages-fr.
Vous pouvez toujours avoir acces a la version anglaise de ce document
en utilisant la commande << man -L C <section> <page_de_man> >>.