Provided by: manpages-fr_3.65d1p1-1_all 
NOM
man-pages - Conventions pour l'écriture des pages de manuel Linux
SYNOPSIS
man [section] titre
DESCRIPTION
Cette page décrit les conventions utilisées pour les pages de manuel du projet man-pages
pour Linux, qui documente l'interface de programmation en espace utilisateur fournie par
le noyau Linux et la bibliothèque C de GNU. Le projet fournit donc la plupart des pages de
la section 2, ainsi que de nombreuses pages qui apparaissent dans les sections 3, 4, 5 et
7 des pages de manuel sur un système Linux. 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 Panorama, 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 non trivial dans la page. 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 standards, 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 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 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.
Nom anglais Nom français Notes
NAME NOM
SYNOPSIS SYNOPSIS
CONFIGURATION CONFIGURATION [En général en section 4]
DESCRIPTION DESCRIPTION
OPTIONS OPTIONS [En général en sections 1, 8]
EXIT STATUS CODE DE RETOUR [En général en sections 1, 8]
RETURN VALUE VALEUR RENVOYÉE [En général en sections 2, 3]
ERRORS ERREURS [Typiquement en sections 2, 3]
ENVIRONMENT ENVIRONNEMENT
FILES FICHIERS
VERSIONS VERSIONS [En général en sections 2, 3]
ATTRIBUTES ATTRIBUTS [En général en sections 2, 3]
CONFORMING TO CONFORMITÉ
NOTES NOTES
BUGS BOGUES
EXAMPLE EXEMPLE
SEE ALSO VOIR AUSSI
Lorsque l'une des sections traditionnelles s'applique, 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 (NOM) Le nom de cette page. D'importantes précisions sur les lignes qui doivent
suivre la commande .SH NAME sont disponibles dans la page man(7). Tous les
mots de cette ligne (y compris le mot suivant immédiatement le « \- », sauf
en français, dans les traductions, où la convention est de commencer le
premier mot par une majuscule) devraient être en minuscule, sauf si
l'anglais ou la convention terminologique technique impose autre chose.
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, cela contient 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, le paragraphe OPTIONS est utilisé.
La description d'un nouveau comportement ou de nouveaux drapeaux d'un appel
système ou d'une fonction d'une bibliothèque doit préciser la version du
noyau ou de la bibliothèque C qui a introduit ce changement. Il est
recommandé de noter cette information à propos des drapeaux sous la forme
d'une liste .TP, comme ci-dessous dans le cas d'un drapeau d'appel système :
XYZ_FLAG (depuis Linux 3.7)
Description du drapeau.
Préciser la version est particulièrement utile aux utilisateurs qui sont
contraints à utiliser d'anciennes version du noyau ou de la bibliothèque C,
ce qui est par exemple courant dans le cas des systèmes embarqués.
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 (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 être triée par ordre alphabétique.
ENVIRONMENT (ENVIRONNEMENT)
Description de toutes les variables d'environnement qui affectent le
programme ou la fonction, ainsi que leurs effets.
FILES (FICHIERS)
Liste des 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.
ATTRIBUTS Un résumé des divers attributs de la ou des fonctions documentées sur cette
page, séparé en sous-sections. Les sous-sections suivantes sont définies.
Multithreading (consultez pthreads(7))
Cette sous-section note les attributs relatifs aux applications
multithread.
* Si la fonction est sûre dans un contexte multithread.
* Si la fonction est un point d'annulation.
* Si la fonction est pour annulations sûres asynchrones.
Des précisions sur ces attributs sont disponibles dans pthreads(7).
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 perspective 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écrites par la page de manuel. Les termes à préférer pour les diverses
normes sont indiqués dans les titres de sous-sections de standards(7). Dans
les pages de section 2 ou 3, cette section doit indiquer la ou les versions
de POSIX.1 à laquelle l'appel se conforme et s'il est spécifié par C99 (pas
la peine de trop se préoccuper des autres normes comme SUS, SUSv2 ou XPG ni
des implémentations SVr4 ou BSD 4.x, sauf si la fonction était présente dans
ces systèmes mais n'est plus dans la version actuelle de POSIX.1, consultez
standards(7)).
Si la fonction n'est gouvernée par aucune norme, 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 (Notes sur
Linux) ou Glibc Notes (Notes sur la glibc).
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, consultez 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.
Quand la liste SEE ALSO (VOIR AUSSI) contient plusieurs noms long de pages
de manuel, pour améliorer l'apparence de la sortie, il peut être utile
d'utiliser les directives .ad l (pas de justification à gauche) et .nh (pas
de césure). La césure d'un nom de page en particulier peut-être évitée en
faisant précéder son nom de la chaîne « \% ».
GUIDE DE STYLE
Les sous-sections suivantes décrivent le style préféré pour le projet man-pages. Pour des
précisions sur les points non couverts ci-dessous, le « Chicago Manual of Style » est
globalement une source de qualité. Essayez également de parcourir les pages existantes
dans l’arborescence des sources du projet pour prendre connaissance des habitudes
actuelles.
Utilisation de formulation neutre
Autant que possible, utilisez le pluriel de genre neutre (en anglais) dans le texte des
pages de manuel. L’utilisation de « they » (« them », « themself », « their ») en tant que
pronom singulier de genre neutre est acceptable.
Conventions de polices
Pour les fonctions, les arguments sont toujours indiqués en italique, même dans le
paragraphe SYNOPSIS, où le reste de la fonction est en caractères gras :
int mafonction(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 d’en-tête)
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'en-tête standard, indiquez le fichier d'en-tê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, précédées et suivies d’une ligne vide, 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, des espaces insécables (« \ ») pourraient être utilisées
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 romains (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 cela dans le fichier source est :
.BR fcntl ()
(avec ce format au lieu de « \fB...\fP() » le travail d'outils qui parcourent 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 caractères romains (normaux), sans
espace (par exemple intro(2)). Dans le source, c’est habituellement écrit 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)
Les caractères de contrôle devraient être écrits en gras, sans guillemets. Par exemple :
^X.
Orthographe
Depuis la version 2.59, la version anglaise de man-pages suit les conventions
orthographiques américaines (auparavant, un mélange aléatoire de conventions britanniques
et américaines existait) ; veuillez écrire les nouvelles pages et les correctifs en
suivants ces conventions.
En plus des différences de conventions bien connues, quelques autres subtilités sont à
surveiller :
* L’anglais américain a tendance à utiliser les formes « backward », « upward »,
« toward », etc. au lieu des formes britanniques « backwards », « upwards »,
« towards », etc.
Numéros de version BSD
Le schéma classique d’écriture des numéros de version BSD est x.yBSD, où x.y est un numéro
de version (par exemple 4.2BSD). Éviter les formes du genre BSD 4.3.
Majuscules
Dans les titres de sous-section (« SS »), le premier mot commence par une majuscule, mais
le reste devraient être en minuscule, sauf si l'anglais (par exemple les noms propres) ou
les exigences du langage de programmation imposent autre chose. Par exemple :
.SS Unicode sous Linux
Indentation des définitions de structure, session d’interpréteur, etc.
Lorsque des définitions de structure, des sorties de session d'interpréteur, etc. sont
inclues en corps de texte, indentez-les avec quatre espaces (c'est-à-dire un bloc entouré
par .in +4n et .in).
Termes préférés
Le tableau suivant indique les termes préférés à utiliser dans les pages de manuel,
principalement pour s’assurer de la cohérence entres les pages.
Terme Éviter Notes
──────────────────────────────────────────────────────────────────────────────────
masque de bits (bit mask) bitmask
interne, intégré (built-in) builtin
époque (Epoch) epoch Pour l’époque UNIX
(1er janvier 1970 à
00:00:00 (UTC))
nom de fichier (filename) file name
système de fichiers file system
(filesystem)
nom d’hôte (hostname) host name
inœud (inode) i-node
minuscule (lowercase) lower case, lower-case
chemin (pathname) path name
pseudoterminal pseudo-terminal
port privilégié (privileged reserved port, system
port) port
temps-réel (real-time) realtime, real time
exécution (run time) runtime
Set-GID sauvegardé (saved saved group ID, saved
set-group-ID) set-GID
Set-UID sauvegardé (saved saved user ID, saved
set-user-ID) set-UID
Set-GID (set-group-ID) set-GID, setgid
Set-UID (set-user-ID) set-UID, setuid
superutilisateur super user, super-user
(superuser)
superbloc (superbloc) super block, super-block
horodatage (timestamp) time stamp
fuseau horaire (timezone) time zone
majuscule (uppercase) upper case, upper-case
utilisable (useable) useable
espace utilisateur (user userspace
space)
identifiant (username) user name
zéros (zeros) zeroes
Consultez la section Écriture des mot composés ci-dessous.
Termes à éviter
Le tableau suivant indique les termes à éviter dans les pages de manuel, avec quelques
suggestions d’alternatives, principalement pour s’assurer de la cohérence entres les
pages.
Éviter Préférer Notes
──────────────────────────────────────────────────────────────────────────
32bit 32 bits (32-bit) de même pour 8 bits,
16 bits, etc.
current process processus appelant (calling Une erreur commune des
process) programmeurs du noyau
qui écrivent des pages
de manuel
manpage page de manuel (man page,
manual page)
minus infinity infini négatif (negative
infinity)
non-root utilisateur ordinaire
(unprivileged user)
non-superuser utilisateur ordinaire
(unprivileged user)
nonprivileged non privilégié
(unprivileged)
OS système d’exploitation
(operating system)
plus infinity infini positif (positive
infinity)
pty pseudoterminal
tty terminal
Unices systèmes UNIX (UNIX systems)
Unixes systèmes UNIX (UNIX systems)
Marques déposées
Utiliser l’orthographe et la casse adéquates pour les marques déposées. Voici une liste
des orthographes adéquates de quelques marques déposées parfois mal orthographiées :
DG/UX
HP-UX
UNIX
UnixWare
NULL, NUL, pointeur NULL, et caractères NULL
Un pointeur NULL est un pointeur qui ne pointe nulle part, et est habituellement indiqué
par la constante NULL. D’un autre côté, NUL est l’octet NULL : un octet de valeur nulle,
représenté en C à l’aide de la constante caractère « \0 ».
Le terme à préférer pour le pointeur est « pointeur NULL » ou simplement « NULL » ; la
version anglaise préfère « null pointer ».
Le terme à préférer pour l’octet est « octet NULL ». Évitez d’écrire « NUL » car cela
pourrait être facilement confondu avec « NULL ». Évitez aussi les termes « octet zéro » et
« caractère NULL ». L’octet qui termine une chaîne en C devrait être décrit comme
l’« octet NULL final » ; les chaînes peuvent être décrites comme « terminées par NULL »,
mais évitez « terminées par NUL ».
Liens hypertextes
Pour les liens hypertextes, utilisez la paire de macro .UR et .UE (consultez
groff_man(7)). Cela produit des liens propres qui peuvent être utilisés dans des
navigateurs web, lors du rendu de pages, avec par exemple :
BROWSER=firefox man -H nomdepage
Utilisation de p.ex., c.-à-d., et autres
En général, l’utilisation d’abréviations comme « p.ex. », « c.-à-d. » devrait être évitée,
en préférant les formulations complètes (« par exemple », « c’est-à-dire »).
Le seul endroit où ce genre d’abréviation pourrait être acceptable est dans les courtes
parenthèses.
Toujours inclure les points dans ces abréviations comme ici. En anglais, « e.g. » et
« i.e. » doivent toujours êtres suivies d’une virgule.
Tirets em
Les tirets long sont rendus en anglais à l’aide de la macro « \(em », mais en français les
caractères UTF-8 sont préférés directement.
Écriture des mot composés
En anglais, les mots composés sont utilisés pour qualifier des noms, mais ce n’est pas le
cas en français. Certaines formulations sont au pluriel en français, comme les premier et
dernier exemples suivants :
valeur sur 32 bits (32-bit value)
argument de ligne de commande (command-line argument)
nombre à virgule flottante (floating-point number)
vérification lors de l’exécution (run-time check)
fonction en espace utilisateur (user-space function)
chaîne de caractères larges (wide-character string)
Mot composés avec les préfixes « multi », « non », « pre », « re », « sub », etc.
La tendance générale en anglais moderne est de ne pas utiliser de tirets après les
préfixes comme « multi », « non », « pre », « re », « sub », etc. Les pages de manuels
devrait normalement suivre cette règles quand ces préfixes sont utilisés dans des
constructions anglaises naturelles avec de simples suffixes. La liste suivante donne des
exemples de forme préférés. En français, la convention est similaire pour les véritables
préfixes (comme « multi- », « pré- », « re- », « ré- ») qui s’écrivent sans tiret, mais
les mots composés, avec « sous- » par exemple, gardent le tiret et les expressions avec
« non » laissent ce mot à part :
interprocessus (interprocess)
multithreadé (multithreaded)
multiprocessus (multiprocess)
non bloquant (nonblocking)
autre que par défaut (nondefault)
non vide (nonempty)
non interactive (noninteractive)
positif (nonnegative)
non portable (nonportable)
non nul (nonzero)
préalloué (preallocated)
précréé (precreate)
préenregistré (prerecorded)
rétabli (reestablished)
réinitialiser (reinitialize)
réarmer (rearm)
relire (reread)
sous-composant (subcomponent)
sous-répertoire (subdirectory)
sous-système (subsystem)
Les tirets sont gardés en anglais lorsque les préfixes sont utilisés dans des mots anglais
non standards, avec les marques déposées, les noms propres, les acronymes ou les mots
composés. Quelques exemples :
non ASCII (non-ASCII)
non anglais (non-English)
non NULL (non-NULL)
non temps-réel (non-real-time)
pseudo-UNIX
Enfin, remarquez qu’en anglais « re-create »(recréer) et « recreate » (s’amuser) sont deux
mots différents et que c’est sans doute le premier qu’il faut utiliser.
Véritable caractère moins
Quand un véritable caractère moins est nécessaire (par exemple pour les nombres comme -1
ou pour écrire des option qui commencent par un tiret comme dans ls -l), utilisez la forme
suivante dans les sources de page de manuel :
\-
Ce guide s’applique aussi aux exemples de code.
Constantes caractère
Pour produire des guillemets simples qui rendront aussi bien en ASCII qu’en UTF-8,
utilisez la forme suivante pour les constantes caractère dans les sources de page de
manuel :
\(aqC\(aq
où C est le caractère protégé. Ce guide s’applique aussi aux constantes caractères
utilisés dans les exemples de code. En français, si possible, préférez la forme
typographique en vigueur (par exemple : « C »).
Programmes d'exemples et sessions d’interpréteur.
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 respecter les points
suivants.
* 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 fonction 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
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 quatre espaces (évitez le caractère tabulation dans
les fichiers source).
* Par cohérence, tous les programmes d’exemple devrait se terminer par une des deux
formes suivantes :
exit(EXIT_SUCCESS);
exit(EXIT_FAILURE);
Évitez d’utiliser les formes suivantes pour terminer un programme :
exit(0);
exit(1);
return n;
* Si un texte d’explication complet précède le code source du programme, indiquez le code
source à l’aide d’un titre de sous section Source du programme, comme :
.SS Source du programme
Toujours faire comme cela si le texte d’explication contient un journal de session
d’interpréteur.
Si vous incluez un journal de session d'interpréteur de commandes pour démontrer
l'utilisation d'un programme ou d'autres fonctionnalités système :
* placez le journal de session au dessus du code source ;
* indentez le journal de session par quatre espaces ;
* mettez le texte entré par l'utilisateur en gras pour le distinguer de la sortie
produite par le système.
Pour voir à quoi les programmes d'exemples devraient ressembler, consultez wait(2) et
pipe(2).
EXEMPLE
Pour des exemples canoniques de pages de manuel du paquet man-pages, consultez 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.65 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
Depuis 2010, cette traduction est maintenue à l'aide de l'outil po4a
<http://po4a.alioth.debian.org/> par l'équipe de traduction francophone au sein du projet
perkamon <http://perkamon.alioth.debian.org/>.
Julien Cristau et l'équipe francophone de traduction de Debian (2006-2009).
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> ».