.\" -*- coding: UTF-8 -*- .\" (C) Copyright 1992-1999 Rickard E. Faith and David A. Wheeler .\" (faith@cs.unc.edu and dwheeler@ida.org) .\" and (C) Copyright 2007 Michael Kerrisk .\" .\" %%%LICENSE_START(VERBATIM) .\" Permission is granted to make and distribute verbatim copies of this .\" manual provided the copyright notice and this permission notice are .\" preserved on all copies. .\" .\" Permission is granted to copy and distribute modified versions of this .\" manual under the conditions for verbatim copying, provided that the .\" entire resulting derived work is distributed under the terms of a .\" permission notice identical to this one. .\" .\" Since the Linux kernel and libraries are constantly changing, this .\" manual page may be incorrect or out-of-date. The author(s) assume no .\" responsibility for errors or omissions, or for damages resulting from .\" the use of the information contained herein. The author(s) may not .\" have taken the same level of care in the production of this manual, .\" which is licensed free of charge, as they might when working .\" professionally. .\" .\" Formatted or processed versions of this manual, if unaccompanied by .\" the source, must acknowledge the copyright and authors of this work. .\" %%%LICENSE_END .\" .\" 2007-05-30 created by mtk, using text from old man.7 plus .\" rewrites and additional text. .\" .\"******************************************************************* .\" .\" This file was generated with po4a. Translate the source file. .\" .\"******************************************************************* .TH MAN\-PAGES 7 "13 août 2020" Linux "Manuel du programmeur Linux" .SH NOM man\-pages \- Conventions pour l'écriture des pages de manuel Linux .SH SYNOPSIS \fBman\fP [\fIsection\fP] \fItitre\fP .SH DESCRIPTION Cette page décrit les conventions qui devraient être utilisées pour l’écriture des pages de manuel du projet \fIman\-pages\fP 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. .SS "Sections des pages de manuel" Les sections du manuel sont traditionnellement les suivantes\ : .TP \fB1 Commandes de l’utilisateur (programmes)\fP Commandes pouvant être invoquées par l'utilisateur depuis un interpréteur de commandes. .TP \fB2 Appels système\fP Fonctions enveloppant les opérations réalisées par le noyau. .TP \fB3 Fonctions des bibliothèques\fP Toutes les fonctions des bibliothèques en excluant les enveloppes d’appel système (la plupart des fonctions de la \fIlibc\fP). .TP \fB4 Fichiers spéciaux (périphériques)\fP Fichiers présents dans \fI/dev\fP permettant l’accès aux périphériques par l’intermédiaire du noyau. .TP \fB5 Formats de fichier et fichiers de configuration\fP Descriptions des formats de fichier lisibles par un humain et des fichiers de configuration. .TP \fB6 Jeux\fP Jeux et petits programmes amusants disponibles sur le système. .TP \fB7 Vue d’ensemble, conventions et éléments divers\fP 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. .TP \fB8 Commandes d'administration du système\fP .\" .TP .\" .B 9 Kernel routines .\" This is an obsolete manual section. .\" Once it was thought a good idea to document the Linux kernel here, .\" but in fact very little has been documented, and the documentation .\" that exists is outdated already. .\" There are better sources of .\" information for kernel developers. Commandes comme \fBmount\fP(8), la plupart exécutables uniquement par le superutilisateur. .SS "Paquet de macros" Les nouvelles pages de manuel devraient être mises en forme en utilisant le paquet \fBan.tmac\fP de \fBgroff\fP décrit dans \fBman\fP(7). Ce choix est principalement destiné à assurer une cohérence\ : la plupart des pages de manuel Linux sont mises en forme avec ces macros. .SS "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. .SS "Ligne de titre" La première commande d'une page de manuel devrait être une commande \fBTH\fP\ : .PP .RS \fB\&.TH\fP \fItitre section date source manuel\fP .RE .PP Les arguments de cette commande sont les suivants\ : .TP \fItitre\fP Le titre de la page de manuel, en majuscules (par exemple \fIMAN\-PAGES\fP). .TP \fIsection\fP Le numéro de section dans laquelle la page devrait être placée (par exemple,\ \fI7\fP). .TP \fIdate\fP La date du dernier changement non trivial effectué sur cette page de manuel. Au sein du projet \fIman\-pages\fP, 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. .TP \fIsource\fP L’origine de la commande, de la fonction ou de l'appel système. .IP Pour les quelques pages de \fIman\-pages\fP dans les sections\ 1 et\ 8, il est conseillé d'écrire \fIGNU\fP. .IP Pour les appels système, écrivez simplement \fILinux\fP. 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. .IP Pour les fonctions de bibliothèque glibc ou de l'une des bibliothèques GNU standard, utilisez \fIGNU C Library\fP, \fIGNU\fP ou une chaîne vide. .IP Pour les pages de la section\ 4, utilisez \fILinux\fP. .IP En cas d'hésitation, écrivez \fILinux\fP ou \fIGNU\fP. .TP \fImanuel\fP .\" Le titre du manuel (par exemple \fILinux Programmer's Manual\fP pour les pages des sections\ 2 et\ 3 dans le paquet \fIman\-pages\fP) .SS "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 \fBmises en évidence\fP. Dans les nouvelles pages de manuel, placez les sections dans l'ordre indiqué dans la liste. .PP .RS .TS l l. \fBNAME\fP (\fBNOM\fP) \fBSYNOPSIS\fP CONFIGURATION [Normally only in Section 4] \fBDESCRIPTION\fP OPTIONS [Normally only in Sections 1, 8] CODE DE RETOUR [Normally only in Sections 1, 8] VALEUR RENVOYÉE [Normally only in Sections 2, 3] .\" May 07: Few current man pages have an ERROR HANDLING section,,, .\" ERROR HANDLING, ERREURS [Typically only in Sections 2, 3] .\" May 07: Almost no current man pages have a USAGE section,,, .\" USAGE, .\" DIAGNOSTICS, .\" May 07: Almost no current man pages have a SECURITY section,,, .\" SECURITY, ENVIRONNEMENT FICHIERS VERSIONS [Normally only in Sections 2, 3] ATTRIBUTS [Normally only in Sections 2, 3] CONFORMITÉ NOTES BOGUES EXEMPLES .\" AUTHORS sections are discouraged AUTEURS [Discouraged] SIGNALER DES BOGUES [Not used in man\-pages] COPYRIGHT [Not used in man\-pages] \fBSEE ALSO\fP (\fBVOIR AUSSI\fP) .TE .RE .PP \fILorsque l'une des sections traditionnelles s'applique\fP, \fIutilisez\-la\fP\ ; 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 (\fI.SS\fP) dans celle\-ci. .PP La liste suivante décrit le contenu de chacune des sections ci\-dessus. .TP \fBNAME\fP (\fBNOM\fP) Nom de cette page de manuel .IP D'importantes précisions sur les lignes qui devraient suivre la commande \&\fB.SH NAME\fP sont disponibles dans la page \fBman\fP(7). Tous les mots de cette ligne (y compris le mot suivant immédiatement le «\ \e\-\ », 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. .TP \fBSYNOPSIS\fP Bref résumé de l’interface de la commande ou de la fonction. .IP 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 \fB#include\fP, suivies de la déclaration de fonction. .IP .\" FIXME . Say something here about compiler options 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 \fBfeature_test_macros\fP(7). .TP \fBCONFIGURATION\fP Détails de configuration pour un périphérique. .IP Cette section est présente normalement que dans les pages de la section\ 4. .TP \fBDESCRIPTION\fP Explication sur ce que le programme, la fonction ou le format réalise. .IP .\" If there is some kind of input grammar or complex set of subcommands, .\" consider describing them in a separate .\" .B USAGE .\" section (and just place an overview in the .\" .B DESCRIPTION .\" section). 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 \fBOPTIONS\fP est utilisée pour les détails. .IP 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 \fB.TP\fP, comme ci\-dessous dans le cas d'un drapeau d'appel système\ : .RS 16 .TP \fBXYZ_FLAG\fP (depuis Linux 3.7) Description du drapeau... .RE .IP 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. .TP \fBOPTIONS\fP Descriptions des options de ligne de commande acceptées par un programme et leur influence sur son comportement. .IP .\" .TP .\" .B USAGE .\" describes the grammar of any sublanguage this implements. Cette section ne devrait être utilisée que pour les pages de manuel des sections\ 1 et\ 8. .TP \fBEXIT STATUS\fP (\fBCODE DE RETOUR\fP) Liste des codes de retour d'un programme et des conditions de renvoi de ces valeurs. .IP Cette section ne devrait être utilisée que pour les pages de manuel des sections\ 1 et\ 8. .TP \fBRETURN VALUE\fP (\fBVALEUR RENVOYÉE\fP) 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. .TP \fBERRORS\fP (\fBERREURS\fP) Pour les pages des sections\ 2 et 3, cette section contient une liste des valeurs possibles de \fIerrno\fP en cas d'erreur, avec la description des causes de ces erreurs. .IP 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. .IP \fILa liste d’erreurs devrait être triée par ordre alphabétique\fP. .TP \fBENVIRONMENT\fP (\fBENVIRONNEMENT\fP) Liste de toutes les variables d'environnement affectant le programme ou la fonction, ainsi que de leurs effets. .TP \fBFILES\fP (\fBFICHIERS\fP) 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. .IP .\" May 07: Almost no current man pages have a DIAGNOSTICS section; .\" "RETURN VALUE" or "EXIT STATUS" is preferred. .\" .TP .\" .B DIAGNOSTICS .\" gives an overview of the most common error messages and how to .\" cope with them. .\" You don't need to explain system error messages .\" or fatal signals that can appear during execution of any program .\" unless they're special in some way to the program. .\" .\" May 07: Almost no current man pages have a SECURITY section. .\".TP .\".B SECURITY .\"discusses security issues and implications. .\"Warn about configurations or environments that should be avoided, .\"commands that may have security implications, and so on, especially .\"if they aren't obvious. .\"Discussing security in a separate section isn't necessary; .\"if it's easier to understand, place security information in the .\"other sections (such as the .\" .B DESCRIPTION .\" or .\" .B USAGE .\" section). .\" However, please include security information somewhere! 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 \fI/usr/local\fP, aussi, votre page de manuel de base devrait utiliser \fI/usr/local\fP comme base. .TP \fBATTRIBUTES\fP (\fBATTRIBUTS\fP) Résumé des divers attributs de la ou des fonctions documentées sur cette page. Consulter \fBattributes\fP(7) pour de plus amples détails. .TP \fBVERSIONS\fP 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. .IP 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). .IP La page de manuel \fBsyscalls\fP(2) fournit également des informations de versions de noyau dans lesquelles sont apparus les appels système. .TP \fBCONFORMING TO\fP (\fBCONFORMITÉ\fP) Descriptions des normes ou conventions liées à la fonction ou à la commande décrite par la page de manuel. .IP Les termes privilégiés à utiliser pour les différentes normes sont listés dans les rubriques de \fBstandards\fP(7) .IP 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). .IP 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. .IP Si cette section ne consiste qu'en une liste de normes (ce qui est d'habitude le cas), terminez la liste par un point («\ .\ »). .TP \fBNOTES\fP Notes diverses .IP Pour les pages des sections\ 2 et 3, il peut être utile d'utiliser des sous\-sections (\fBSS\fP) appelées \fILinux Notes\fP (\fINotes sur Linux\fP) ou \fIGlibc Notes\fP (\fINotes sur la glibc\fP). .IP Dans la section\ 2, le titre \fIC library/kernel differences\fP 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. .TP \fBBUGS\fP (\fBBOGUES\fP) Liste des limitations, des défauts ou des inconvénients recensés, ainsi que des sujets à débat. .TP \fBEXAMPLES\fP (\fBEXEMPLES\fP) Un ou plusieurs exemples d'utilisation de la fonction, du fichier ou de la commande. .IP Pour plus de détails sur l'écriture d'exemples de programme, consultez \fIExemples de programme\fP ci\-dessous. .TP \fBAUTHORS\fP (\fBAUTEURS\fP) Liste des auteurs de la documentation ou du programme. .IP \fBL'utilisation d'une section AUTHORS est fortement déconseillée\fP. 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. .TP \fBSIGNALER DES BOGUES\fP Le projet \fIman\-pages\fP 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. .TP \fBCOPYRIGHT\fP Le projet \fIman\-pages\fP 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. .TP \fBSEE ALSO\fP (\fBVOIR AUSSI\fP) 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. .IP 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. .IP 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 \fI.ad l\fP (pas de justification à droite) et \fI.nh\fP (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 «\ \e%\ ». .IP É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. .SH "GUIDE DE STYLE" Les sous\-sections suivantes décrivent le style privilégié pour le projet \fIman\-pages\fP. 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. .SS "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. .SS "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, \fImême dans la section SYNOPSIS\fP. .PP .\" Le nom de la commande et de ses options devraient toujours être en caractères gras. .SS "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, \fImême dans la section SYNOPSIS\fP, où le reste de la fonction est indiqué en caractères gras. .PP \fB int mafonction(int \fP\fIargc\fP\fB, char **\fP\fIargv\fP\fB);\fP .PP Les noms de variables devraient, tout comme les noms de paramètres, être indiqués en italique. .PP 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 \fBfcntl\fP(2), les références au sujet de la page devrait être écrites \fBfcntl\fP(). La façon privilégiée d'écrire cela dans le fichier source est\ : .PP .EX .BR fcntl () .EE .PP .\" (L’utilisation de ce format, plutôt que celle de «\ \efB...\efP()\ », facilite l’écriture d’outils qui analysent les sources des pages de manuel.) .SS "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.) Cette convention, parfois appelée «\ nouvelles lignes sémantiques\ », facilite la visualisation des effets de correctif qui opère au niveau de lignes spécifiques ou de propositions de phrases. .SS "Conventions typographiques (générales)" Les paragraphes devraient être séparés par des marqueurs adaptés (habituellement soit \fI.PP\fP ou \fI.IP\fP). \fINe pas\fP 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). .PP 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 \fI\fP), sauf dans la section SYNOPSIS où les fichiers inclus sont en caractères gras (par exemple \fB#include \fP). 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, \fI\fP). .PP Les macros spéciales, généralement en majuscules, sont en caractères gras (par exemple \fBMAXINT\fP). Exception\ : NULL ne doit pas être en gras. .PP 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 \fB\&.TP\fP. .PP 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\ : .PP .in +4n .EX man 7 man\-pages .EE .in .PP Si la commande est courte, elle peut être incluse dans le texte, en italique, par exemple, \fIman\ 7\ man\-pages\fP. Dans ce cas, des espaces insécables («\ \e\ \ ») pourraient être utilisées aux endroits appropriés dans la commande. Les options des commandes devraient elles aussi être écrites en italique (par exemple,\ \fI\-l\fP). .PP 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. .PP Pour montrer des sessions d’interpréteur de commandes, les saisies de l’utilisateur devraient être écrites en caractères gras. .PP .in +4n .EX $ \fBdate\fP Thu Jul 7 13:01:27 CEST 2016 .EE .in .PP Toute référence à une autre page de manuel devrait être écrite avec le nom en caractères gras \fItoujours\fP suivi du numéro de section en caractères romains (normaux), sans espace intermédiaire (par exemple \fBintro\fP(2)). Dans le source, la façon préconisée est\ : .PP .EX .BR intro (2) .EE .PP (Inclure le numéro de section dans les références croisées permet à des outils comme \fBman2html\fP(1) de créer des liens hypertextes appropriés) .PP Les caractères de contrôle devraient être écrits en gras, sans guillemets. Par exemple\ :\ \fB\(haX\fP. .SS Orthographe Depuis la version\ 2.59, la version anglaise de \fIman\-pages\fP 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. .PP En plus des différences d’orthographe bien connues, quelques autres subtilités sont à surveiller\ : .IP * 3 L’anglais américain a tendance à utiliser les formes «\ backward\ », «\ upward\ », «\ toward\ »,\ etc., au lieu des formes britanniques «\ backwards\ », «\ upwards\ », «\ towards\ »,\ etc. .SS "Numéros de version BSD" Le schéma classique d’écriture des numéros de version BSD est \fIx.yBSD\fP, où \fIx.y\fP est un numéro de version (par exemple 4.2BSD). Éviter les formes du genre \fIBSD\ 4.3\fP. .SS Majuscules Dans les titres de sous\-section («\ SS\ »), le premier mot commence par une majuscule, 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\ : .PP .EX .SS Unicode sous Linux .EE .\" .SS "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 \fI.in\ +4n\fP et \fI.in\fP), formatez\-les en utilisant les macros \fI.EX\fP et \fIEE\fP et entourez\-les avec les marqueurs de paragraphe adaptés (soit \fI.PP\fP ou \fI.IP\fP). Par exemple\ : .PP .in +4n .EX .PP .in +4n .EX int main(int argc, char *argv[]) { return 0; } .EE .in .PP .EE .in .SS "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. .TS l l l --- l l l. Terme Utilisation à éviter Notes bit mask bitmask built\-in builtin Epoch epoch T{ Pour l’époque d’UNIX (00:00:00, 1 Jan 1970 UTC) T} 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 T{ reserved port, system port T} real\-time T{ realtime, real time T} run time runtime saved set\-group\-ID T{ saved group ID, saved set\-GID T} saved set\-user\-ID T{ saved user ID, saved set\-UID T} set\-group\-ID set\-GID, setgid set\-user\-ID set\-UID, setuid superuser T{ super user, super\-user T} superblock T{ super block, super\-block T} timestamp time stamp timezone time zone uppercase upper case, upper\-case usable useable user space userspace username user name x86\-64 x86_64 T{ Excepté si cela se réfère à « uname\ \-m » ou similaire T} zeros zeroes .TE .PP Consultez la section \fIÉcriture des mots composés épithètes\fP ci\-dessous. .SS "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. .TS l l l --- l l l. Avoid Use instead Notes 32bit 32\-bit T{ de même pour 8\-bit, 16\-bit, etc. T} current process calling process T{ Une erreur commune des programmeurs du noyau qui écrivent des pages de manuel T} manpage T{ man page, manual page T} 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 .TE .SS "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\ : .PP DG/UX HP\-UX UNIX UnixWare .SS "NULL, NUL, pointeur NULL, et caractères NULL" Un \fIpointeur NULL\fP est un pointeur qui ne pointe nulle part, et est habituellement indiqué par la constante \fINULL\fP. D’un autre côté, \fINUL\fP est l’\fIoctet NULL\fP\ : un octet de valeur nulle, représenté en\ C à l’aide de la constante caractère \fI«\ \e0\ »\fP. .PP Le terme à préférer pour le pointeur est «\ null pointer\ » (pointeur NULL) ou simplement «\ NULL\ ». Éviter d’écrire «\ NULL pointer\ ». .PP 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). .SS "Liens hypertextes" Pour les liens hypertextes, utilisez la paire de macros \fI.UR\fP et \fI.UE\fP (consultez \fBgroff_man\fP(7)). Cela produit des liens propres qui peuvent être utilisés dans des navigateurs web, lors du rendu de pages, avec par exemple\ : .PP BROWSER=firefox man \-H nom_de_page .SS "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). .PP Le seul endroit où ce genre d’abréviation pourrait être acceptable est dans les parenthèses \fIcourtes\fP (e.g., like this one). .PP 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. .SS "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 «\ \e(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 \fIsans\fP espaces avoisinantes. .SS "É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\ : .PP 32\-bit value command\-line argument floating\-point number run\-time check user\-space function wide\-character string .SS "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\ : .PP interprocess multithreaded multiprocess nonblocking nondefault nonempty noninteractive nonnegative nonportable nonzero preallocated precreate prerecorded reestablished reinitialize rearm reread subcomponent subdirectory subsystem .PP 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\ : .PP non\-ASCII non\-English non\-NULL non\-real\-time .PP .\" 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. .SS "Génération des glyphes optimaux" Quand un véritable caractère moins est nécessaire (par exemple pour les nombres comme \fB\-1\fP, pour des références croisées de pages de manuel telles que \fButf\-8\fP(7) ou pour écrire des options qui commencent par un tiret comme dans \fIls\ \-l\fP), utilisez la forme suivante dans le source de la page de manuel\ : .PP \e\- .PP Ce guide s’applique aussi aux exemples de code. .PP Pour produire des guillemets simples qui rendront aussi bien en ASCII qu’en UTF\-8, utilisez «\ \e(aq\ » («\ apostrophe quote\ »). Par exemple\ : .PP \e(aqC\e(aq .PP où \fIC\fP 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\ »). .PP Lorsque qu’un caret approprié (\(ha) dont un bon rendu dans un terminal comme en PDF est nécessaire, «\ \e(ha\ » est à utiliser. Cela est particulièrement nécessaire dans les exemples de code, pour obtenir un rendu élégant du caret en PDF. .PP .\" L’utilisation d’un caractère nu «\ \(ti\ » aboutit à un mauvais rendu en PDF. Utilisez «\ \e(ti\ ». Cela est particulièrement nécessaire dans les exemples de code, pour obtenir un rendu élégant du tilde en PDF. .SS "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. .IP * 3 Les programmes d'exemple devraient être écrits en\ C. .IP * 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. .IP * Example programs should ideally be short (e.g., a good example can often be provided in less than 100 lines of code), though in some cases longer programs may be necessary to properly illustrate the use of an API. .IP * Expressive code and useful comments are appreciated. .IP * 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. .IP * Les programmes d'exemple devraient être complets et compiler sans avertissements avec \fIcc\ \-Wall\fP. .IP * 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). .IP * 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é\ : .IP indent \-npro \-kr \-i4 \-ts4 \-sob \-l72 \-ss \-nut \-psl prog.c .IP * Par cohérence, tous les programmes d’exemple devraient se terminer par une des deux formes suivantes\ : .IP exit(EXIT_SUCCESS); exit(EXIT_FAILURE); .IP Évitez d’utiliser les formes suivantes pour terminer un programme\ : .IP exit(0); exit(1); return n; .IP * 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 \fISource du programme\fP, comme\ : .IP \&.SS Source du programme .IP Toujours faire comme cela si le texte d’explication contient un journal de session d’interpréteur. .PP 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\ : .IP * 3 placez le journal de session au dessus du code source\ ; .IP * indentez le journal de session par quatre espaces\ ; .IP * mettez le texte entré par l'utilisateur en gras pour le distinguer de la sortie produite par le système. .PP Pour voir à quoi les programmes d'exemples devraient ressembler, consultez \fBwait\fP(2) et \fBpipe\fP(2). .SH EXEMPLES Pour des exemples canoniques de pages de manuel se conformant au paquet \fIman\-pages\fP, consultez \fBpipe\fP(2) et \fBfcntl\fP(2). .SH "VOIR AUSSI" \fBman\fP(1), \fBman2html\fP(1), \fBattributes\fP(7), \fBgroff\fP(7), \fBgroff_man\fP(7), \fBman\fP(7), \fBmdoc\fP(7) .SH COLOPHON Cette page fait partie de la publication\ 5.10 du projet \fIman\-pages\fP Linux. Une description du projet et des instructions pour signaler des anomalies et la dernière version de cette page peuvent être trouvées à l'adresse \%https://www.kernel.org/doc/man\-pages/. .SH TRADUCTION La traduction française de cette page de manuel a été créée par Christophe Blaess , Stéphan Rafin , Thierry Vignaud , François Micaux, Alain Portal , Jean-Philippe Guérard , Jean-Luc Coulon (f5ibh) , Julien Cristau , Thomas Huriaux , Nicolas François , Florentin Duneau , Simon Paillard , Denis Barbier , David Prévot et Jean-Paul Guillonneau . Cette traduction est une documentation libre ; veuillez vous reporter à la .UR https://www.gnu.org/licenses/gpl-3.0.html GNU General Public License version 3 .UE 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 à .MT debian-l10n-french@lists.debian.org .ME .