Provided by: manpages-fr_4.21.0-2_all 
NOM
man-pages - Conventions pour l'écriture des pages de manuel Linux
SYNOPSIS
man [section] titre
DESCRIPTION
Cette page décrit les conventions qui devraient être utilisées pour l’écriture des pages
de manuel du projet man-pages de Linux, qui documente l'interface de programmation
applicative pour l’espace utilisateur fourni par le noyau Linux et la bibliothèque GNU C.
Le projet fournit donc la plupart des pages de la section 2, de nombreuses pages
apparaissant dans les sections 3, 4, 5 et 7, et quelques pages apparaissant dans les
sections 1, 5 et 8 des pages de manuel sur un système Linux. Les conventions décrites dans
cette page peuvent aussi être utiles aux auteurs de pages de manuel pour d'autres projets.
Sections des pages de manuel
Les sections du manuel sont traditionnellement les suivantes :
1 Commandes de l’utilisateur (programmes)
Commandes pouvant être invoquées par l'utilisateur depuis un interpréteur de
commandes.
2 Appels système
Fonctions enveloppant les opérations réalisées par le noyau.
3 Fonctions des bibliothèques
Toutes les fonctions des bibliothèques en excluant les enveloppes d’appel système
(la plupart des fonctions de la libc).
4 Fichiers spéciaux (périphériques)
Fichiers présents dans /dev permettant l’accès aux périphériques par
l’intermédiaire du noyau.
5 Formats de fichier et fichiers de configuration
Descriptions des formats de fichier lisibles par un humain et des fichiers de
configuration.
6 Jeux Jeux et petits programmes amusants disponibles sur le système.
7 Vue d’ensemble, conventions et éléments divers
Vues d’ensemble ou descriptions de divers sujets, des protocoles et conventions,
des jeux de caractères normalisés, de la structure du système de fichiers et
d'autres choses diverses.
8 Commandes d'administration du système
Commandes comme mount(8), la plupart exécutables uniquement par le
superutilisateur.
Paquet de macros
Les nouvelles pages de manuel devraient être mises en forme en utilisant le paquet an.tmac
de groff 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 la présentation des fichiers 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
courriel lorsque des modifications sont soumises par ce moyen.
Ligne de titre
La première commande d'une page de manuel devrait être une commande TH :
.TH titre section date source section_manuel
Les arguments de cette commande sont les suivants :
titre Le titre de la page de manuel, en majuscules (par exemple MAN-PAGES).
section
Le numéro de section dans laquelle la page devrait être placée (par exemple, 7).
date La date du dernier changement non trivial effectué sur cette page de manuel. Au
sein du projet man-pages, les mises à jour des étiquettes temporelles sont
automatiquement effectuées par des scripts, de sorte qu'il n'est pas nécessaire de
les mettre à jour lors la fourniture d'un correctif. Les dates devraient être
écrites sous la forme AAAA-MM-JJ.
source Le nom et la version du projet fournissant la page de manuel (pas nécessairement le
paquet fournissant la fonctionnalité).
section_manuel
Normalement cela devrait être vide puisque la valeur par défaut devrait être la
bonne.
Sections dans une page de manuel
La liste ci-dessous indique les sections classiques 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 (NOM)
BIBLIOTHÈQUE [Normalement seulement dans les Sections 2 et 3]
SYNOPSIS
CONFIGURATION [Normalement seulement dans la Section 4]
DESCRIPTION
OPTIONS [Normalement seulement dans les Sections 1 et 8]
CODE DE RETOUR [Normalement seulement dans les Sections 1 et 8]
VALEUR RENVOYÉE [Normalement seulement dans les Sections 2 et 3]
ERREURS [Typiquement seulement dans les Sections 2 et 3]
ENVIRONNEMENT
FICHIERS
VERSIONS [Normalement seulement dans les Sections 2 et 3]
ATTRIBUTS [Normalement seulement dans les Sections 2 et 3]
STANDARDS
NOTES
AVERTISSEMENTS
BOGUES
EXEMPLES
AUTEURS [Déconseillé]
SIGNALER DES BOGUES [Non utilisé dans man-pages]
COPYRIGHT [Non utilisé dans man-pages]
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 section 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
titre de section traditionnel ne peut être utilisé avec des sous-sections (.SS) dans
celle-ci.
La liste suivante décrit le contenu de chacune des sections ci-dessus.
NAME (NOM)
Nom de cette page de manuel
D'importantes précisions sur les lignes qui devraient 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
minuscules, sauf si l'anglais ou la convention terminologique technique impose
autre chose.
BIBLIOTHÈQUE
Bibliothèque fournissant un symbole.
Cela montre le nom courant de la bibliothèque et, entre parenthèses, le nom du
fichier de la bibliothèque et, si nécessaire, l'indicateur nécessaire à l’éditeur
de liens pour lier un programme avec elle : (libfoo[, -lfoo]).
SYNOPSIS
Bref résumé de l’interface de la commande ou de la fonction.
Pour les commandes, ce paragraphe montre la syntaxe et les arguments de la commande
(y compris les options). Les caractères en gras marquent le texte invariable et
ceux en italique indiquent les arguments remplaçables. Les crochets « [] »
encadrent les arguments facultatifs, les barres verticales « | » séparent les
alternatives et les points de suspension « ... » peuvent être des arguments
répétés. Pour les fonctions, cela contient toutes les déclarations de données ou
les 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 devrait 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
Explication sur ce que le programme, la fonction ou le format réalise.
Cette section décrit les interactions avec les fichiers et l'entrée standard, et ce
qui est produit sur la sortie standard ou d'erreur. Les détails d'implémentation
internes sont omis sauf s'ils sont critiques pour comprendre l'interface.
L’utilisation habituelle est décrite et la section OPTIONS est utilisée pour les
détails.
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
d’utiliser d'anciennes versions du noyau ou de la bibliothèque C, ce qui est par
exemple courant dans le cas des systèmes embarqués.
OPTIONS
Descriptions des options de ligne de commande acceptées par un programme et leur
influence sur son comportement.
Cette section ne devrait être utilisée que pour les pages de manuel des sections 1
et 8.
EXIT STATUS (CODE DE RETOUR)
Liste des codes de retour d'un programme et des conditions de renvoi de ces
valeurs.
Cette section ne devrait ê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, cette section 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 section contient une liste des valeurs
possibles de errno en cas d'erreur, avec la description des causes de ces erreurs.
Quand des conditions différentes produisent la même erreur, l’approche à préférer
est de créer plusieurs entrées de liste séparées (avec des noms d’erreur dupliqués)
pour chacune des conditions. Cela clarifie les différences de conditions, rend la
liste plus facile à lire et permet aux méta-informations (par exemple, le numéro de
version du noyau dans laquelle la condition est devenu applicable) d’être plus
facilement caractérisées pour chaque condition.
La liste d’erreurs devrait être triée par ordre alphabétique.
ENVIRONMENT (ENVIRONNEMENT)
Liste de toutes les variables d'environnement affectant le programme ou la
fonction, ainsi que de leurs effets.
FILES (FICHIERS)
Liste de tous les fichiers utilisés par le programme ou la fonction, tels les
fichiers de configuration, les fichiers de démarrage et les fichiers manipulés
directement par le programme.
Le chemin d'accès complet de ces fichiers doit être donné ainsi que le mécanisme
d'installation utilisé pour modifier la partie répertoire afin de satisfaire aux
préférences de l’utilisateur. 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.
ATTRIBUTES (ATTRIBUTS)
Résumé des divers attributs de la ou des fonctions documentées sur cette page.
Consulter attributes(7) pour de plus amples détails.
VERSIONS
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 apparue 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
lorsqu'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 dans celui des 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.
STANDARDS
Descriptions des normes ou conventions liées à la fonction ou à la commande décrite
par la page de manuel.
Les termes privilégiés à utiliser pour les différentes normes sont listés dans les
rubriques de standards(7)
Dans les pages de section 2 ou 3, cette section devrait indiquer les versions de
POSIX.1 auxquelles 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 4.xBSD, sauf si la fonction était présente dans ces
systèmes mais ne l'est plus dans la version actuelle de POSIX.1).
Si la fonction n'est régie 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 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).
Dans la section 2, le titre C library/kernel differences est à utiliser pour
délimiter les notes décrivant les différences (s’il en existe) entre la fonction C
d’enveloppe de bibliothèque pour un appel système et l’interface brute d’appel
système fournie par le noyau.
AVERTISSEMENTS
Avertissements sur une mauvaise utilisation courante d’une API, qui ne constitue
pas un bogue de celle-ci, ni un défaut de conception.
BUGS (BOGUES)
Liste des limitations, des défauts ou des inconvénients recensés, ainsi que des
sujets à débat.
EXAMPLES (EXEMPLES)
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 programme, consultez Exemples de
programme ci-dessous.
AUTHORS (AUTEURS)
Liste des auteurs de la documentation ou du programme.
L'utilisation d'une section AUTHORS est fortement déconseillée. En général, il vaut
mieux ne pas encombrer chaque page 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.
SIGNALER DES BOGUES
Le projet man-pages n’utilise pas de section REPORTING BUGS dans les pages de
manuel. La manière de signaler des bogues est à la place indiquée dans la section
COLOPHON générée par un script. Cependant, divers projets utilisent une section
REPORTING BUGS. Il est recommandé de la placer près de la fin de page.
COPYRIGHT
Le projet man-pages n’utilise pas de section COPYRIGHT dans les pages de manuel.
Les informations de droits d’auteur sont à la place entretenues dans le source de
la page. Dans les pages incluant cette section, il est recommandée de la placer en
bas de page, juste au-dessus de la section SEE ALSO.
SEE ALSO (VOIR AUSSI)
Liste des pages de manuel (séparées par des virgules) ayant un rapport,
éventuellement suivie par d’autres pages ou documents ayant un rapport.
La liste devrait être classée selon l'ordre des sections puis de façon
alphabétique. Ne terminez pas la liste par un point.
Quand la liste SEE ALSO contient plusieurs noms longs de page de manuel, pour
améliorer l'apparence de la sortie, il peut être utile d'utiliser les directives
.ad l (pas de justification à droite) 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
« \% ».
Étant donné la nature indépendante et distribuée des projets logiciels au code
source ouvert (FOSS) et de leur documentation, il est parfois nécessaire (et dans
de nombreux cas souhaitable) que la section SEE ALSO inclut des références vers des
pages de manuel fournies par d’autres projets.
CONVENTIONS DE FORMATAGE ET DE FORMULATION
Les sous-sections suivantes fournissent quelques indications de préférences de convention
de formatage et de formulation dans diverses sections des pages du projet man-pages.
SYNOPSIS
Entourer le(s) prototype(s) de fonction d'une paire .nf/.fi pour empêcher le remplissage.
En général, lorsque plus d’un prototype de fonction sont indiqués dans le SYNOPSIS,
ceux-ci ne devraient pas être séparés par des lignes blanches. Cependant, des lignes
blanches (ajoutées en utilisant .PP) peuvent être utilisées dans les cas suivants :
- pour la séparation de longues listes de prototypes de fonctions en groupes de même
sujet (consulter par exemple list(3));
- dans d’autres cas pouvant améliorer la lisibilité.
Dans le SYNOPSIS, un prototype de fonction long peut nécessiter d’être continué dans une
nouvelle ligne. Celle-ci sera indentée selon les règles suivantes :
(1) S’il existe un seul prototype devant être continué, alors la ligne de continuation
doit être alignée de façon à ce que lorsque la page est rendue dans un périphérique
dont la fonte est de largeur fixe (par exemple, xterm), la ligne de continuation
débute juste en dessous du début de la liste d’arguments de la ligne au-dessus
(exception : l’indentation peut être ajustée si nécessaire pour empêcher une très
longue ligne de continuation ou une autre ligne de continuation si le prototype est
très long). Un exemple :
int tcsetattr(int fd, int optional_actions,
const struct termios *termios_p);
(2) Mais, quand plusieurs fonctions dans le SYNOPSIS nécessitent des lignes de
continuation alors que les noms de fonction sont de différentes longueurs, alors
l’alignement des lignes de continuation doit débuter dans la même colonne. Cela
fournit un rendu plus agréable dans une sortie PDF (parce que le SYNOPSIS utilise une
fonte de taille variable où le rendu des espaces est plus étroit que celui de la
plupart des caractères). Un exemple :
int getopt(int argc, char * const argv[],
const char *optstring);
int getopt_long(int argc, char * const argv[],
const char *optstring,
const struct option *longopts, int *longindex);
VALEUR RENVOYÉE
La formulation préférée pour décrire comment errno est définie est « errno is set to
indicate the error » ou similaire. Cela s’accorde avec celle utilisée dans POSIX.1 et
FreeBSD.
ATTRIBUTS
Il est à noter que :
- entourer la table dans cette section d'une paire .ad l/.ad pour désactiver le
remplissage de texte et d'une paire .nh/.hy pour désactiver la coupure des mots en fin
de ligne ;
- s'assurer que la table occupe toute la largeur de la page à l’aide de la description
lbx pour une des colonnes (habituellement la première colonne, bien que dans certains
cas ce soit la dernière colonne si elle contient beaucoup de texte) ;
- ne pas hésiter à utiliser la paire de macros T{/T} pour permettre aux cellules de la
table d’être découpées en plusieurs lignes (en gardant en tête que les pages peuvent
quelquefois être rendues en moins de 80 colonnes.
Pour des exemples de tout cela, consultez le code source de diverses pages.
GUIDE DE STYLE
Les sous-sections suivantes décrivent le style privilégié pour le projet man-pages. Pour
des précisions sur les points non couverts ci-dessous, le « Chicago Manual of Style » est
généralement une source de qualité. Essayez également de parcourir les pages existantes
dans l’arborescence des sources du projet pour prendre connaissance des habitudes
courantes.
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 typographiques pour les pages de manuel décrivant des commandes
Pour les pages de manuel décrivant une commande (généralement dans les sections 1 et 8)
les arguments sont toujours indiqués en italique, même dans la section SYNOPSIS.
Le nom de la commande et de ses options devraient toujours être en caractères gras.
Conventions typographiques pour les pages de manuel décrivant des fonctions
Pour les pages de manuel décrivant une fonction (généralement dans les sections 2 et 3)
les arguments sont toujours indiqués en italique, même dans la section SYNOPSIS, où le
reste de la fonction est indiqué en caractères gras.
int mafonction(int argc, char **argv);
Les noms de variables devraient, tout comme les noms de paramètres, être indiqués en
italique.
Toute référence au sujet de la page de manuel courante devrait être écrite avec le nom en
caractères gras suivi par 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 devrait être écrites
fcntl(). La façon privilégiée d'écrire cela dans le fichier source est :
.BR fcntl ()
(L’utilisation de ce format, plutôt que celle de « \fB...\fP() », facilite l’écriture
d’outils qui analysent les sources des pages de manuel.)
Utilisation de nouvelles lignes sémantiques
Dans le code source d’une page de manuel, les nouvelles phrases devraient débuter sur de
nouvelles lignes et les phrases longues découpées en lignes selon les changements de
proposition (virgules, deux-points, points-virgules, etc.), et les propositions devraient
être coupées aux limites de phrase. Cette convention, parfois appelée « nouvelles lignes
sémantiques », facilite la visualisation de l'effet des correctifs qui opèrent au niveau
des lignes, propositions ou phrases individuelles.
Listes
Différentes sortes de liste existent :
Paragraphes avec étiquettes
Ils sont utilisés pour une liste d’étiquettes et leurs descriptions. Quand les
étiquettes sont des constantes (soit des macros ou des nombres), elles sont en
gras. Utilisez la macro .TP.
Cette sous-section « Paragraphes avec étiquettes » constitue elle-même un exemple.
Listes ordonnées
Les éléments sont précédés par un nombre entre parenthèses (1), (2). Ces derniers
représentent un succession d’étapes qui ont un ordre.
S’il existe des sous-étapes, elles seront numérotées comme (4.2).
Listes positionnelles
Les éléments sont précédés par un nombre (indice) entre crochets [4], [5]. Ces
derniers représentent des champs dans un ensemble. Le premier indice sera :
0 quand il représente des champs dans une structure de données en C, pour être
cohérent avec les tableaux ;
1 quand il représente des champs d’un fichier, pour être cohérent avec des
outils comme cut(1).
Liste d’alternatives
Les éléments sont précédés par une lettre entre parenthèses (a), (b). Ces dernières
représentent une liste d’alternatives exclusives (normalement).
Listes à puces
Les éléments sont précédés par une puce (\[bu]). Tout ce qui ne convient pas autre
part est habituellement couvert par ce type de liste.
Notes numérotées
Ce ne sont pas réellement des listes, mais leur syntaxe est identique à celle des
« listes positionnelles ».
Il devrait toujours y avoir exactement deux espaces entre le symbole de la liste et les
éléments. Cela ne s’applique pas aux « paragraphes avec étiquettes » qui utilisent les
règles d’indentation par défaut.
Conventions typographiques (générales)
Les paragraphes devraient être séparés par des marqueurs adaptés (habituellement soit .PP
ou .IP). Ne pas séparer les paragraphes en utilisant des lignes blanches, car cela aboutit
à un rendu médiocre dans certains formats de sortie (tels que PostScript et PDF).
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 la section SYNOPSIS où les
fichiers inclus sont en caractères 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é de
chevrons, de la même manière que dans un fichier source C (par exemple, <stdio.h>).
Les macros spéciales, généralement en majuscules, sont en caractères gras (par exemple
MAXINT). Exception : NULL ne doit pas être en gras.
Dans l'énumération d'une liste de codes d'erreur, les codes sont en caractères gras, et la
liste utilise normalement la macro .TP.
Les commandes complètes devraient, si elles sont longues, être écrites sous une 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 (\[ti]) pourraient être utilisées aux
endroits appropriés dans la commande. Les options des commandes devraient elles aussi être
écrites en italique (par exemple, -l).
Les expressions, si elles ne sont pas écrites sur une ligne séparée 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.
Pour montrer des sessions d’interpréteur de commandes, les saisies de l’utilisateur
devraient être écrites en caractères gras.
$ date
Thu Jul 7 13:01:27 CEST 2016
Toute référence à une autre page de manuel devrait être écrite avec le nom en caractères
gras toujours suivi du numéro de section en caractères romains (normaux), sans espace
intermédiaire (par exemple intro(2)). Dans le source, la façon préconisée est :
.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 hypertextes 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 suivant
ces conventions.
En plus des différences d’orthographe 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.
- Les avis divergent entre « acknowledgement » et « acknowledgment ». Ce dernier
prédomine, mais n’est pas toujours utilisé en anglais-américain. POSIX et la licence
BSD utilisent la première orthographe. Dans le projet man-pages de Linux, c'est
« acknowledgement » qui est utilisé.
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.
Capitalisation
Dans les titres de sous-section (« SS »), le premier mot commence par une capitale, mais
le reste devrait être en minuscule, sauf si l'anglais (par exemple les noms propres) ou
les exigences du langage de programmation imposent autre chose (par exemple, les noms
d’identificateur). Par exemple :
.SS Unicode sous Linux
Indentation des définitions de structure, des journaux d’interpréteur, etc.
Lorsque des définitions de structure, des journaux de session d'interpréteur, etc., sont
inclus dans le corps de texte, indentez-les avec quatre espaces (c'est-à-dire un bloc
entouré par .in +4n et .in), formatez-les en utilisant les macros .EX et .EE et
entourez-les avec les marqueurs de paragraphe adaptés (soit .PP ou .IP). Par exemple :
.PP
.in +4n
.EX
int
main(int argc, char *argv[])
{
return 0;
}
.EE
.in
.PP
Termes privilégiés
Le tableau suivant indique les termes à privilégier dans les pages anglaises de manuel,
principalement pour assurer une cohérence entres les pages.
Terme Utilisation à éviter Notes
───────────────────────────────────────────────────────────────────
bit mask bitmask
built-in builtin
Epoch epoch Pour l’époque
d’UNIX (00:00:00, 1
Jan 1970 UTC)
filename file name
filesystem file system
hostname host name
inode i-node
lowercase lower case, lower-case
nonzero non-zero
pathname path name
pseudoterminal pseudo-terminal
privileged port reserved port, system
port
real-time realtime, real time
run time runtime
saved set-group-ID saved group ID, saved
set-GID
saved set-user-ID saved user ID, saved
set-UID
set-group-ID set-GID, setgid
set-user-ID set-UID, setuid
superuser super user, super-user
superblock super block,
super-block
lien symbolique symlink
timestamp time stamp
timezone time zone
uppercase upper case, upper-case
usable useable
user space userspace
username user name
x86-64 x86_64 Excepté si cela se
réfère à « uname -m
» ou similaire
zeros zeroes
Consultez la section Écriture des mots composés épithètes ci-dessous.
Termes à éviter
Le tableau suivant indique les termes à éviter dans les pages anglaises de manuel, avec
quelques suggestions d’alternatives, principalement pour assurer la cohérence entres les
pages.
Avoid Use instead Notes
─────────────────────────────────────────────────────────────────
32bit 32-bit de même pour 8-bit,
16-bit, etc.
current process calling process Une erreur commune des
programmeurs du noyau
qui écrivent des pages
de manuel
manpage man page, manual page
minus infinity negative infinity
non-root unprivileged user
non-superuser unprivileged user
nonprivileged unprivileged
OS operating system
plus infinity positive infinity
pty pseudoterminal
tty terminal
Unices UNIX systems
Unixes 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 octet 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 « null pointer » (pointeur NULL) ou simplement
« NULL ». Éviter d’écrire « NULL pointer ».
Le terme à préférer pour l’octet est « null byte » (octet NULL). Évitez d’écrire « NUL »
car cela pourrait être facilement confondu avec « NULL ». Évitez aussi les termes « zero
byte » (octet zéro) et « null character » (caractère NULL). L’octet qui termine une chaîne
en C devrait être décrit comme « the terminating null byte » (l’octet NULL final). Les
chaînes peuvent être décrites comme « null-terminated » (terminées par NULL), mais évitez
« NUL-terminated » (terminées par NUL).
Liens hypertextes
Pour les liens hypertextes, utilisez la paire de macros .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 nom_de_page
Utilisation de e.g., i.e., etc., a.k.a., et autres
En général, l’utilisation d’abréviations comme « e.g. », « i.e. », « etc. », « cf. » et
« a.k.a. » devrait être évitée, en faveur d’une écriture complète (« for example », « that
is », « and so on », « compare to », « also known as ») (Idem pour les traductions
françaises des pages de manuel).
Le seul endroit où ce genre d’abréviation pourrait être acceptable est dans les
parenthèses courtes (e.g., like this one).
Toujours inclure les points dans ces abréviations comme ici. De plus en anglais, « e.g. »
et « i.e. » devraient toujours êtres suivies d’une virgule.
Tirets longs
La façon d’écrire un tiret cadratin « em-dash », le glyphe apparaissant à chaque extrémité
d’une proposition incise, est dans *roff la macro « \[em] ». (Sur un terminal ASCII, un
tiret long est vu comme deux tirets courts, mais dans des contextes typographiques il
apparait comme un tiret long.) Les « em-dash » devraient être écrits sans espaces
avoisinantes.
Écriture des mot composés épithètes
Les mots composés devraient être reliés par un tiret lorsqu’utilisés comme attributs
(c'est-à-dire pour qualifier un nom suivant). Quelques exemples :
32-bit value
command-line argument
floating-point number
run-time check
user-space function
wide-character string
Séparation des mots 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 manuel
devraient normalement suivre cette règle 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ée :
interprocess
multithreaded
multiprocess
nonblocking
nondefault
nonempty
noninteractive
nonnegative
nonportable
nonzero
preallocated
precreate
prerecorded
reestablished
reinitialize
rearm
reread
subcomponent
subdirectory
subsystem
Les tirets sont gardés en anglais lorsque les préfixes sont utilisés dans des mots anglais
non standard, avec les marques déposées, les noms propres, les acronymes ou les mots
composés. Quelques exemples :
non-ASCII
non-English
non-NULL
non-real-time
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.
Génération des glyphes optimaux
Quand un véritable caractère moins est nécessaire (par exemple pour les nombres comme -1,
pour des références croisées de pages de manuel telles que utf-8(7) ou pour écrire des
options qui commencent par un tiret comme dans ls -l), utilisez la forme suivante dans le
source de la page de manuel :
\-
Ce guide s’applique aussi aux exemples de code.
L’utilisation d’un vrai signe moins a pour buts :
- fourniture d’un meilleur rendu dans diverses cibles autres que les terminaux ASCII,
particulièrement pour les PDF et les terminaux adaptés à l’Unicode/UTF-8 ;
- pour créer des glyphes qui, s’ils sont copiés depuis des rendus de page, produiront un
vrai signe moins s’ils sont collés dans un terminal.
Pour produire des guillemets simples qui rendront aussi bien en ASCII qu’en UTF-8,
utilisez « \[aq] » (« apostrophe quote »). Par exemple :
\[aq]C\[aq]
où C est le caractère protégé. Ce guide s’applique aussi aux constantes caractère
utilisées dans les exemples de code. Dans la traduction en français, si possible, préférez
la forme typographique en vigueur (par exemple : « C »).
Lorsque qu’un caret approprié (^) dont un bon rendu dans un terminal et en PDF est
nécessaire, utilisez « \[ha] ». Cela est particulièrement nécessaire dans les exemples de
code, pour obtenir un rendu élégant du caret en PDF.
L’utilisation d’un caractère nu « ~ » aboutit à un mauvais rendu en PDF. Utilisez plutôt
« \[ti] ». Cela est particulièrement nécessaire dans les exemples de code, pour obtenir un
rendu élégant du tilde en PDF.
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 devraient ê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 textuelle 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 devraient idéalement être courts (par exemple, un bon
programme peut être souvent fourni avec moins de 100 lignes de code), quoique dans
certains cas un programme plus long soit nécessaire pour illustrer convenablement
l’utilisation d’une API.
- Du code expressif est apprécié.
- Des commentaires devraient être inclus là où c’est utile. Les phrases complètes dans
les commentaires autonomes devraient être terminées par un point. Les points devraient
être généralement omis dans les commentaires « d’étiquettes » (c’est-à-dire des
commentaires qui sont placés sur la même ligne de code) — dans tous les cas de tels
commentaires sont typiquement de courtes phrases plutôt que des phrases complètes.
- Les programmes d'exemple devraient faire une vérification d’erreurs après les appels
système et les appels de fonction de bibliothèque.
- Les programmes d'exemple devraient ê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). La commande suivante peut être utilisée pour mettre en forme le
code source vers quelque chose proche du style préféré :
indent -npro -kr -i4 -ts4 -sob -l72 -ss -nut -psl prog.c
- Par cohérence, tous les programmes d’exemple devraient 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 complète 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).
EXEMPLES
Pour des exemples canoniques de pages de manuel se conformant au paquet man-pages,
consultez pipe(2) et fcntl(2).
VOIR AUSSI
man(1), man2html(1), attributes(7), groff(7), groff_man(7), man(7), mdoc(7)
TRADUCTION
La traduction française de cette page de manuel a été créée par Christophe Blaess
<https://www.blaess.fr/christophe/>, Stéphan Rafin <stephan.rafin@laposte.net>, Thierry
Vignaud <tvignaud@mandriva.com>, François Micaux, Alain Portal <aportal@univ-montp2.fr>,
Jean-Philippe Guérard <fevrier@tigreraye.org>, Jean-Luc Coulon (f5ibh) <jean-
luc.coulon@wanadoo.fr>, Julien Cristau <jcristau@debian.org>, Thomas Huriaux
<thomas.huriaux@gmail.com>, Nicolas François <nicolas.francois@centraliens.net>, Florentin
Duneau <fduneau@gmail.com>, Simon Paillard <simon.paillard@resel.enst-bretagne.fr>, Denis
Barbier <barbier@debian.org>, David Prévot <david@tilapin.org> et Jean-Paul Guillonneau
<guillonneau.jeanpaul@free.fr>
Cette traduction est une documentation libre ; veuillez vous reporter à la GNU General
Public License version 3 ⟨https://www.gnu.org/licenses/gpl-3.0.html⟩ concernant les
conditions de copie et de distribution. Il n'y a aucune RESPONSABILITÉ LÉGALE.
Si vous découvrez un bogue dans la traduction de cette page de manuel, veuillez envoyer un
message à ⟨debian-l10n-french@lists.debian.org⟩.