| man-pages(7) | Miscellaneous Information Manual | man-pages(7) |
man-pages - Conventions pour l'écriture des pages de manuel Linux
man [section] titre
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.
Les sections du manuel sont traditionnellement les suivantes :
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.
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.
La première commande d'une page de manuel devrait être une commande TH :
Les arguments de cette commande sont les suivants :
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.
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.
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 :
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 :
int tcsetattr(int fd, int optional_actions,
const struct termios *termios_p);
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);
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.
Il est à noter que :
Pour des exemples de tout cela, consultez le code source de diverses pages.
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.
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.
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.
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.)
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.
Différentes sortes de liste existent :
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.
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.
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 :
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.
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
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
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.
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 |
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 |
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).
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
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.
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.
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 |
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.
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 :
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.
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.
indent -npro -kr -i4 -ts4 -sob -l72 -ss -nut -psl prog.c
exit(EXIT_SUCCESS);
exit(EXIT_FAILURE);
exit(0);
exit(1);
return n;
SS Source du programme
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 :
Pour voir à quoi les programmes d'exemples devraient ressembler, consultez wait(2) et pipe(2).
Pour des exemples canoniques de pages de manuel se conformant au paquet man-pages, consultez pipe(2) et fcntl(2).
man(1), man2html(1), attributes(7), groff(7), groff_man(7), man(7), mdoc(7)
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 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.
| 5 février 2023 | Pages du manuel de Linux 6.03 |