man-pages(7) Miscellaneous Information Manual man-pages(7) NOM man-pages - Conventions pour l'ecriture des pages de manuel Linux SYNOPSIS man [section] titre DESCRIPTION Cette page decrit les conventions qui devraient etre utilisees pour l'ecriture 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 bibliotheque 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 systeme Linux. Les conventions decrites dans cette page peuvent aussi etre 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 etre invoquees par l'utilisateur depuis un interpreteur de commandes. 2 Appels systeme Fonctions enveloppant les operations realisees par le noyau. 3 Fonctions des bibliotheques Toutes les fonctions des bibliotheques en excluant les enveloppes d'appel systeme (la plupart des fonctions de la libc). 4 Fichiers speciaux (peripheriques) Fichiers presents dans /dev permettant l'acces aux peripheriques par l'intermediaire 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 systeme. 7 Vue d'ensemble, conventions et elements divers Vues d'ensemble ou descriptions de divers sujets, des protocoles et conventions, des jeux de caracteres normalises, de la structure du systeme de fichiers et d'autres choses diverses. 8 Commandes d'administration du systeme Commandes comme mount(8), la plupart executables uniquement par le superutilisateur. Paquet de macros Les nouvelles pages de manuel devraient etre mises en forme en utilisant le paquet an.tmac de groff decrit dans man(7). Ce choix est principalement destine a assurer une coherence : la plupart des pages de manuel Linux sont mises en forme avec ces macros. Conventions pour la presentation des fichiers sources Veuillez limiter la longueur des lignes dans le source a environ 75 caracteres, autant que faire se peut. Cela permet d'eviter les retours a la ligne ajoutes par les clients de courriel lorsque des modifications sont soumises par ce moyen. Ligne de titre La premiere commande d'une page de manuel devrait etre 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 numero de section dans laquelle la page devrait etre placee (par exemple, 7). date La date du dernier changement non trivial effectue sur cette page de manuel. Au sein du projet man-pages, les mises a jour des etiquettes temporelles sont automatiquement effectuees par des scripts, de sorte qu'il n'est pas necessaire de les mettre a jour lors la fourniture d'un correctif. Les dates devraient etre ecrites sous la forme AAAA-MM-JJ. source Le nom et la version du projet fournissant la page de manuel (pas necessairement le paquet fournissant la fonctionnalite). section_manuel Normalement cela devrait etre vide puisque la valeur par defaut devrait etre la bonne. Sections dans une page de manuel La liste ci-dessous indique les sections classiques ou suggerees. La plupart des pages devraient contenir au moins les sections mises en evidence. Dans les nouvelles pages de manuel, placez les sections dans l'ordre indique dans la liste. NAME (NOM) BIBLIOTHEQUE [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 RENVOYEE [Normalement seulement dans les Sections 2 et 3] ERREURS [Typiquement seulement dans les Sections 2 et 3] ENVIRONNEMENT FICHIERS ATTRIBUTS [Normalement seulement dans les Sections 2 et 3] VERSIONS [Normalement seulement dans les Sections 2 et 3] STANDARDS HISTORIQUE NOTES AVERTISSEMENTS BOGUES EXEMPLES AUTEURS [Deconseille] SIGNALER DES BOGUES [Non utilise dans man-pages] COPYRIGHT [Non utilise dans man-pages] SEE ALSO (VOIR AUSSI) Lorsque l'une des sections traditionnelles s'applique, utilisez-la ; cette coherence rend l'information plus facile a comprendre. Si cela est necessaire, vous pouvez creer vos propres titres de section si cela rend les choses plus comprehensibles (particulierement pour les pages des sections 4 et 5). Cependant, avant de faire cela, verifiez qu'aucun titre de section traditionnel ne peut etre utilise avec des sous-sections (.SS) dans celle-ci. La liste suivante decrit le contenu de chacune des sections ci-dessus. NAME (NOM) Nom de cette page de manuel See man(7) for important details of the line(s) that should follow the .SH NAME command. All words in this line (including the word immediately following the "\-") should be in lowercase, except where English or technical terminological convention dictates otherwise. BIBLIOTHEQUE Bibliotheque fournissant un symbole. Cela montre le nom courant de la bibliotheque et, entre parentheses, le nom du fichier de la bibliotheque et, si necessaire, l'indicateur necessaire a l'editeur de liens pour lier un programme avec elle : (libfoo[, -lfoo]). SYNOPSIS Bref resume 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 caracteres en gras marquent le texte invariable et ceux en italique indiquent les arguments remplacables. Les crochets << [] >> encadrent les arguments facultatifs, les barres verticales << | >> separent les alternatives et les points de suspension << ... >> peuvent etre des arguments repetes. Pour les fonctions, cela contient toutes les declarations de donnees ou les directives #include, suivies de la declaration de fonction. Si une macro de test de fonctionnalite doit etre definie pour obtenir la declaration d'une fonction (ou d'une variable) dans un fichier d'en-tete, alors la section SYNOPSIS devrait l'indiquer, comme decrit dans feature_test_macros(7). CONFIGURATION Details de configuration pour un peripherique. Cette section est presente normalement que dans les pages de la section 4. DESCRIPTION Explication sur ce que le programme, la fonction ou le format realise. Cette section decrit les interactions avec les fichiers et l'entree standard, et ce qui est produit sur la sortie standard ou d'erreur. Les details d'implementation internes sont omis sauf s'ils sont critiques pour comprendre l'interface. L'utilisation habituelle est decrite et la section OPTIONS est utilisee pour les details. La description d'un nouveau comportement ou de nouveaux drapeaux d'un appel systeme ou d'une fonction d'une bibliotheque doit preciser la version du noyau ou de la bibliotheque C qui a introduit ce changement. Il est recommande de noter cette information a propos des drapeaux sous la forme d'une liste .TP, comme ci-dessous dans le cas d'un drapeau d'appel systeme : XYZ_FLAG (depuis Linux 3.7) Description du drapeau... Preciser la version est particulierement utile aux utilisateurs qui sont contraints d'utiliser d'anciennes versions du noyau ou de la bibliotheque C, ce qui est par exemple courant dans le cas des systemes embarques. OPTIONS Descriptions des options de ligne de commande acceptees par un programme et leur influence sur son comportement. Cette section ne devrait etre utilisee 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 etre utilisee que pour les pages de manuel des sections 1 et 8. RETURN VALUE (VALEUR RENVOYEE) Pour les pages des sections 2 et 3, cette section donne une liste des valeurs qu'une routine de bibliotheque renverra a l'appelant et les conditions qui provoquent ces retours. ERRORS (ERREURS) Pour les pages des sections 2 et 3, cette section contient une liste des valeurs possibles de errno en cas d'erreur, avec la description des causes de ces erreurs. Quand des conditions differentes produisent la meme erreur, l'approche a preferer est de creer plusieurs entrees de liste separees (avec des noms d'erreur dupliques) pour chacune des conditions. Cela clarifie les differences de conditions, rend la liste plus facile a lire et permet aux meta-informations (par exemple, le numero de version du noyau dans laquelle la condition est devenu applicable) d'etre plus facilement caracterisees pour chaque condition. La liste d'erreurs devrait etre triee par ordre alphabetique. 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 utilises par le programme ou la fonction, tels les fichiers de configuration, les fichiers de demarrage et les fichiers manipules directement par le programme. Le chemin d'acces complet de ces fichiers doit etre donne ainsi que le mecanisme d'installation utilise pour modifier la partie repertoire afin de satisfaire aux preferences de l'utilisateur. Pour la plupart des programmes, l'installation par defaut se fait dans /usr/local, aussi, votre page de manuel de base devrait utiliser /usr/local comme base. ATTRIBUTES (ATTRIBUTS) Resume des divers attributs de la ou des fonctions documentees sur cette page. Consulter attributes(7) pour de plus amples details. VERSIONS A summary of systems where the API performs differently, or where there's a similar API. STANDARDS Descriptions des normes ou conventions liees a la fonction ou a la commande decrite par la page de manuel. Les termes privilegies a utiliser pour les differentes normes sont listes dans les rubriques de standards(7) This section should note the current standards to which the API conforms to. If the API is not governed by any standards but commonly exists on other systems, note them. If the call is Linux-specific or GNU-specific, note this. If it's available in the BSDs, note that. Si cette section ne consiste qu'en une liste de normes (ce qui est d'habitude le cas), terminez la liste par un point (<< . >>). HISTORY Court resume de la version du noyau Linux ou de la glibc ou l'appel systeme ou la fonction de bibliotheque est apparue ou dont le fonctionnement est modifie de maniere significative. As a general rule, every new interface should include a HISTORY section in its manual page. Unfortunately, many existing manual pages don't include this information (since there was no policy to do so when they were written). Patches to remedy this are welcome, but, from the perspective of programmers writing new code, this information probably matters only in the case of kernel interfaces that have been added in Linux 2.4 or later (i.e., changes since Linux 2.2), and library functions that have been added to glibc since glibc 2.1 (i.e., changes since glibc 2.0). La page de manuel syscalls(2) fournit egalement des informations de versions de noyau dans lesquelles sont apparus les appels systeme. Old versions of standards should be mentioned here, rather than in STANDARDS, for example, SUS, SUSv2, and XPG, or the SVr4 and 4.xBSD implementation standards. NOTES Notes diverses Pour les pages des sections 2 et 3, il peut etre utile d'utiliser des sous-sections (SS) appelees Linux Notes (Notes sur Linux) ou glibc Notes (Notes sur la glibc). Dans la section 2, le titre C library/kernel differences est a utiliser pour delimiter les notes decrivant les differences (s'il en existe) entre la fonction C d'enveloppe de bibliotheque pour un appel systeme et l'interface brute d'appel systeme 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 defaut de conception. BUGS (BOGUES) Liste des limitations, des defauts ou des inconvenients recenses, ainsi que des sujets a debat. EXAMPLES (EXEMPLES) Un ou plusieurs exemples d'utilisation de la fonction, du fichier ou de la commande. Pour plus de details sur l'ecriture d'exemples de 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 deconseillee. En general, il vaut mieux ne pas encombrer chaque page de manuel avec une liste (potentiellement longue) d'auteurs. Si vous ecrivez ou modifiez de facon importante une page, ajoutez une notice de copyright en commentaire dans le fichier source. Si vous etes l'auteur d'un pilote de peripherique et voulez inclure une adresse pour signaler les bogues, placez-la dans la section BUGS. SIGNALER DES BOGUES Le projet man-pages n'utilise pas de section REPORTING BUGS dans les pages de manuel. La maniere de signaler des bogues est a la place indiquee dans la section COLOPHON generee par un script. Cependant, divers projets utilisent une section REPORTING BUGS. Il est recommande de la placer pres 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 a la place entretenues dans le source de la page. Dans les pages incluant cette section, il est recommandee de la placer en bas de page, juste au-dessus de la section SEE ALSO. SEE ALSO (VOIR AUSSI) Liste des pages de manuel (separees par des virgules) ayant un rapport, eventuellement suivie par d'autres pages ou documents ayant un rapport. La liste devrait etre classee selon l'ordre des sections puis de facon alphabetique. Ne terminez pas la liste par un point. Where the SEE ALSO list contains many long manual page names, to improve the visual result of the output, it may be useful to employ the .ad l (don't right justify) and .nh (don't hyphenate) directives. Hyphenation of individual page names can be prevented by preceding words with the string "\%". Etant donne la nature independante et distribuee des projets logiciels au code source ouvert (FOSS) et de leur documentation, il est parfois necessaire (et dans de nombreux cas souhaitable) que la section SEE ALSO inclut des references vers des pages de manuel fournies par d'autres projets. CONVENTIONS DE FORMATAGE ET DE FORMULATION Les sous-sections suivantes fournissent quelques indications de preferences 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 empecher le remplissage. In general, where more than one function prototype is shown in the SYNOPSIS, the prototypes should not be separated by blank lines. However, blank lines (achieved using .P) may be added in the following cases: - pour la separation de longues listes de prototypes de fonctions en groupes de meme sujet (consulter par exemple list(3)); - dans d'autres cas pouvant ameliorer la lisibilite. Dans le SYNOPSIS, un prototype de fonction long peut necessiter d'etre continue dans une nouvelle ligne. Celle-ci sera indentee selon les regles suivantes : (1) S'il existe un seul prototype devant etre continue, alors la ligne de continuation doit etre alignee de facon a ce que lorsque la page est rendue dans un peripherique dont la fonte est de largeur fixe (par exemple, xterm), la ligne de continuation debute juste en dessous du debut de la liste d'arguments de la ligne au-dessus (exception : l'indentation peut etre ajustee si necessaire pour empecher une tres longue ligne de continuation ou une autre ligne de continuation si le prototype est tres long). Un exemple : int tcsetattr(int fd, int optional_actions, const struct termios *termios_p); (2) Mais, quand plusieurs fonctions dans le SYNOPSIS necessitent des lignes de continuation alors que les noms de fonction sont de differentes longueurs, alors l'alignement des lignes de continuation doit debuter dans la meme colonne. Cela fournit un rendu plus agreable dans une sortie PDF (parce que le SYNOPSIS utilise une fonte de taille variable ou le rendu des espaces est plus etroit que celui de la plupart des caracteres). 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 RENVOYEE La formulation preferee pour decrire comment errno est definie est << errno is set to indicate the error >> ou similaire. Cela s'accorde avec celle utilisee dans POSIX.1 et FreeBSD. ATTRIBUTS Il est a noter que : - entourer la table dans cette section d'une paire .ad l/.ad pour desactiver le remplissage de texte et d'une paire .nh/.hy pour desactiver la coupure des mots en fin de ligne ; - s'assurer que la table occupe toute la largeur de la page a l'aide de la description lbx pour une des colonnes (habituellement la premiere colonne, bien que dans certains cas ce soit la derniere colonne si elle contient beaucoup de texte) ; - ne pas hesiter a utiliser la paire de macros T{/T} pour permettre aux cellules de la table d'etre decoupees en plusieurs lignes (en gardant en tete que les pages peuvent quelquefois etre 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 decrivent le style privilegie pour le projet man-pages. Pour des precisions sur les points non couverts ci-dessous, le << Chicago Manual of Style >> est generalement une source de qualite. Essayez egalement 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 decrivant des commandes Pour les pages de manuel decrivant une commande (generalement dans les sections 1 et 8) les arguments sont toujours indiques en italique, meme dans la section SYNOPSIS. Le nom de la commande et de ses options devraient toujours etre en caracteres gras. Conventions typographiques pour les pages de manuel decrivant des fonctions Pour les pages de manuel decrivant une fonction (generalement dans les sections 2 et 3) les arguments sont toujours indiques en italique, meme dans la section SYNOPSIS, ou le reste de la fonction est indique en caracteres gras. int mafonction(int argc, char **argv); Les noms de variables devraient, tout comme les noms de parametres, etre indiques en italique. Toute reference au sujet de la page de manuel courante devrait etre ecrite avec le nom en caracteres gras suivi par une paire de parentheses en caracteres romains (normaux). Par exemple, dans la page fcntl(2), les references au sujet de la page devrait etre ecrites fcntl(). La facon privilegiee d'ecrire cela dans le fichier source est : .BR fcntl () (Using this format, rather than the use of "\fB...\fP()" makes it easier to write tools that parse man page source files.) Utilisation de nouvelles lignes semantiques Dans le code source d'une page de manuel, les nouvelles phrases devraient debuter sur de nouvelles lignes et les phrases longues decoupees en lignes selon les changements de proposition (virgules, deux-points, points-virgules, etc.), et les propositions devraient etre coupees aux limites de phrase. Cette convention, parfois appelee << nouvelles lignes semantiques >>, facilite la visualisation de l'effet des correctifs qui operent au niveau des lignes, propositions ou phrases individuelles. Listes Differentes sortes de liste existent : Paragraphes avec etiquettes Ils sont utilises pour une liste d'etiquettes et leurs descriptions. Quand les etiquettes sont des constantes (soit des macros ou des nombres), elles sont en gras. Utilisez la macro .TP. Cette sous-section << Paragraphes avec etiquettes >> constitue elle-meme un exemple. Listes ordonnees Les elements sont precedes par un nombre entre parentheses (1), (2). Ces derniers representent un succession d'etapes qui ont un ordre. S'il existe des sous-etapes, elles seront numerotees comme (4.2). Listes positionnelles Les elements sont precedes par un nombre (indice) entre crochets [4], [5]. Ces derniers representent des champs dans un ensemble. Le premier indice sera : 0 quand il represente des champs dans une structure de donnees en C, pour etre coherent avec les tableaux ; 1 quand il represente des champs d'un fichier, pour etre coherent avec des outils comme cut(1). Liste d'alternatives Les elements sont precedes par une lettre entre parentheses (a), (b). Ces dernieres representent une liste d'alternatives exclusives (normalement). Listes a puces Elements are preceded by bullet symbols (\[bu]). Anything that doesn't fit elsewhere is usually covered by this type of list. Notes numerotees Ce ne sont pas reellement des listes, mais leur syntaxe est identique a celle des << listes positionnelles >>. Il devrait toujours y avoir exactement deux espaces entre le symbole de la liste et les elements. Cela ne s'applique pas aux << paragraphes avec etiquettes >> qui utilisent les regles d'indentation par defaut. Conventions typographiques (generales) Paragraphs should be separated by suitable markers (usually either .P or .IP). Do not separate paragraphs using blank lines, as this results in poor rendering in some output formats (such as PostScript and PDF). Les noms de fichiers, que ce soit des chemins ou des references a des fichiers d'en-tete, sont toujours en italique (par exemple ), sauf dans la section SYNOPSIS ou les fichiers inclus sont en caracteres gras (par exemple #include ). Lorsque vous faites reference a un fichier d'en-tete standard, indiquez le fichier d'en-tete entoure de chevrons, de la meme maniere que dans un fichier source C (par exemple, ). Les macros speciales, generalement en majuscules, sont en caracteres gras (par exemple MAXINT). Exception : NULL ne doit pas etre en gras. Dans l'enumeration d'une liste de codes d'erreur, les codes sont en caracteres gras, et la liste utilise normalement la macro .TP. Les commandes completes devraient, si elles sont longues, etre ecrites sous une forme indentee, precedees et suivies d'une ligne vide, par exemple : man 7 man-pages If the command is short, then it can be included inline in the text, in italic format, for example, man 7 man-pages. In this case, it may be worth using nonbreaking spaces (\~) at suitable places in the command. Command options should be written in italics (e.g., -l). Les expressions, si elles ne sont pas ecrites sur une ligne separee indentee, devraient etre mises en italique. Ici aussi, l'utilisation d'espaces insecables est appropriee si l'expression est melangee a du texte normal. Pour montrer des sessions d'interpreteur de commandes, les saisies de l'utilisateur devraient etre ecrites en caracteres gras. $ date Thu Jul 7 13:01:27 CEST 2016 Toute reference a une autre page de manuel devrait etre ecrite avec le nom en caracteres gras toujours suivi du numero de section en caracteres romains (normaux), sans espace intermediaire (par exemple intro(2)). Dans le source, la facon preconisee est : .BR intro (2) (Inclure le numero de section dans les references croisees permet a des outils comme man2html(1) de creer des liens hypertextes appropries) Les caracteres de controle devraient etre ecrits en gras, sans guillemets. Par exemple : ^X. Orthographe Depuis la version 2.59, la version anglaise de man-pages suit les conventions orthographiques americaines (auparavant, un melange aleatoire de conventions britanniques et americaines existait). Veuillez ecrire les nouvelles pages et les correctifs en suivant ces conventions. En plus des differences d'orthographe bien connues, quelques autres subtilites sont a surveiller : - L'anglais americain a tendance a 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 predomine, mais n'est pas toujours utilise en anglais-americain. POSIX et la licence BSD utilisent la premiere orthographe. Dans le projet man-pages de Linux, c'est << acknowledgement >> qui est utilise. Numeros de version BSD Le schema classique d'ecriture des numeros de version BSD est x.yBSD, ou x.y est un numero de version (par exemple 4.2BSD). Eviter 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 etre 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 definitions de structure, des journaux d'interpreteur, etc. When structure definitions, shell session logs, and so on are included in running text, indent them by 4 spaces (i.e., a block enclosed by .in +4n and .in), format them using the .EX and .EE macros, and surround them with suitable paragraph markers (either .P or .IP). For example: .P .in +4n .EX int main(int argc, char *argv[]) { return 0; } .EE .in .P Termes privilegies Le tableau suivant indique les termes a privilegier dans les pages anglaises de manuel, principalement pour assurer une coherence entres les pages. Terme Utilisation a eviter Notes --------------------------------------------------------------------- - bit mask bitmask built-in builtin Epoch epoch Pour l'epoque d'UNIX (00:00:00, 1 Jan 1970 UTC) filename file name systeme de fichiers 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 fonctionnement 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 Excepte si cela se refere a << uname -m >> ou similaire zeros zeroes Consultez la section Ecriture des mots composes epithetes ci-dessous. Termes a eviter Le tableau suivant indique les termes a eviter dans les pages anglaises de manuel, avec quelques suggestions d'alternatives, principalement pour assurer la coherence entres les pages. Avoid Use instead Notes ---------------------------------------------------------- 32bit 32-bit de meme pour 8-bit, 16-bit, etc. current process calling process Une erreur commune des programmeurs du noyau qui ecrivent 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 deposees Utiliser l'orthographe et la casse adequates pour les marques deposees. Voici une liste des orthographes adequates de quelques marques deposees parfois mal orthographiees : DG/UX HP-UX UNIX UnixWare NULL, NUL, pointeur NULL et octet NULL A null pointer is a pointer that points to nothing, and is normally indicated by the constant NULL. On the other hand, NUL is the null byte, a byte with the value 0, represented in C via the character constant '\0'. Le terme a preferer pour le pointeur est << null pointer >> (pointeur NULL) ou simplement << NULL >>. Eviter d'ecrire << NULL pointer >>. Le terme a preferer pour l'octet est << null byte >> (octet NULL). Evitez d'ecrire << NUL >> car cela pourrait etre facilement confondu avec << NULL >>. Evitez aussi les termes << zero byte >> (octet zero) et << null character >> (caractere NULL). L'octet qui termine une chaine en C devrait etre decrit comme << the terminating null byte >> (l'octet NULL final). Les chaines peuvent etre decrites comme << null-terminated >> (terminees par NULL), mais evitez << NUL-terminated >> (terminees 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 etre utilises 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 general, l'utilisation d'abreviations comme << e.g. >>, << i.e. >>, << etc. >>, << cf. >> et << a.k.a. >> devrait etre evitee, en faveur d'une ecriture complete (<< for example >>, << that is >>, << and so on >>, << compare to >>, << also known as >>) (Idem pour les traductions francaises des pages de manuel). Le seul endroit ou ce genre d'abreviation pourrait etre acceptable est dans les parentheses courtes (e.g., like this one). Toujours inclure les points dans ces abreviations comme ici. De plus en anglais, << e.g. >> et << i.e. >> devraient toujours etres suivies d'une virgule. Tirets longs The way to write an em-dash--the glyph that appears at either end of this subphrase--in *roff is with the macro "\[em]". (On an ASCII terminal, an em-dash typically renders as two hyphens, but in other typographical contexts it renders as a long dash.) Em-dashes should be written without surrounding spaces. Ecriture des mot composes epithetes Les mots composes devraient etre relies par un tiret lorsqu'utilises comme attributs (c'est-a-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 Separation des mots avec les prefixes multi, non, pre, re, sub, etc. La tendance generale en anglais moderne est de ne pas utiliser de tirets apres les prefixes comme << multi >>, << non >>, << pre >>, << re >>, << sub >>, etc. Les pages de manuel devraient normalement suivre cette regle quand ces prefixes sont utilises dans des constructions anglaises naturelles avec de simples suffixes. La liste suivante donne des exemples de forme preferee : interprocess multithreaded multiprocess nonblocking nondefault nonempty noninteractive nonnegative nonportable nonzero preallocated precreate prerecorded reestablished reinitialize rearm reread subcomponent subdirectory subsystem Les tirets sont gardes en anglais lorsque les prefixes sont utilises dans des mots anglais non standard, avec les marques deposees, les noms propres, les acronymes ou les mots composes. Quelques exemples : non-ASCII non-English non-NULL non-real-time Enfin, remarquez qu'en anglais << re-create >>(recreer) et << recreate >> (s'amuser) sont deux mots differents et que c'est sans doute le premier qu'il faut utiliser. Generation des glyphes optimaux Quand un veritable caractere moins est necessaire (par exemple pour les nombres comme -1, pour des references croisees de pages de manuel telles que utf-8(7) ou pour ecrire 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, particulierement pour les PDF et les terminaux adaptes a l'Unicode/UTF-8 ; - pour creer des glyphes qui, s'ils sont copies depuis des rendus de page, produiront un vrai signe moins s'ils sont colles dans un terminal. To produce unslanted single quotes that render well in ASCII, UTF-8, and PDF, use "\[aq]" ("apostrophe quote"); for example \[aq]C\[aq] ou C est le caractere protege. Ce guide s'applique aussi aux constantes caractere utilisees dans les exemples de code. Dans la traduction en francais, si possible, preferez la forme typographique en vigueur (par exemple : << C >>). Lorsque qu'un caret approprie (^) dont un bon rendu dans un terminal et en PDF est necessaire, utilisez << \[ha] >>. Cela est particulierement necessaire dans les exemples de code, pour obtenir un rendu elegant du caret en PDF. L'utilisation d'un caractere nu << ~ >> aboutit a un mauvais rendu en PDF. Utilisez plutot << \[ti] >>. Cela est particulierement necessaire dans les exemples de code, pour obtenir un rendu elegant du tilde en PDF. Programmes d'exemples et sessions d'interpreteur. Les pages de manuel peuvent contenir des programmes permettant de montrer comment utiliser un appel systeme ou une fonction de bibliotheque. Cependant, veuillez respecter les points suivants. - Les programmes d'exemple devraient etre ecrits en C. - Un programme d'exemple n'est necessaire et utile que s'il montre quelque chose qui ne peut pas etre fourni facilement dans une description textuelle de l'interface. Un programme d'exemple qui ne fait qu'appeler une fonction ne sert en general a rien. - Les programmes d'exemple devraient idealement etre courts (par exemple, un bon programme peut etre souvent fourni avec moins de 100 lignes de code), quoique dans certains cas un programme plus long soit necessaire pour illustrer convenablement l'utilisation d'une API. - Du code expressif est apprecie. - Des commentaires devraient etre inclus la ou c'est utile. Les phrases completes dans les commentaires autonomes devraient etre terminees par un point. Les points devraient etre generalement omis dans les commentaires << d'etiquettes >> (c'est-a-dire des commentaires qui sont places sur la meme ligne de code) -- dans tous les cas de tels commentaires sont typiquement de courtes phrases plutot que des phrases completes. - Les programmes d'exemple devraient faire une verification d'erreurs apres les appels systeme et les appels de fonction de bibliotheque. - Les programmes d'exemple devraient etre complets et compiler sans avertissements avec cc -Wall. - Si possible et raisonnable, les programmes d'exemples doivent permettre d'experimenter, en changeant de comportement en fonction des entrees (arguments de ligne de commande ou entrees lues par le programme). - Les programmes d'exemple doivent etre mis en forme dans le style de Kernighan et Ritchie, avec des indentations de quatre espaces (evitez le caractere tabulation dans les fichiers source). La commande suivante peut etre utilisee pour mettre en forme le code source vers quelque chose proche du style prefere : indent -npro -kr -i4 -ts4 -sob -l72 -ss -nut -psl prog.c - Par coherence, tous les programmes d'exemple devraient se terminer par une des deux formes suivantes : exit(EXIT_SUCCESS); exit(EXIT_FAILURE); Evitez d'utiliser les formes suivantes pour terminer un programme : exit(0); exit(1); return n; - Si un texte d'explication complete precede le code source du programme, indiquez le code source a 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'interpreteur. Si vous incluez un journal de session d'interpreteur de commandes pour demontrer l'utilisation d'un programme ou d'autres fonctionnalites systeme : - placez le journal de session au dessus du code source ; - indentez le journal de session par quatre espaces ; - mettez le texte entre par l'utilisateur en gras pour le distinguer de la sortie produite par le systeme. Pour voir a 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 francaise de cette page de manuel a ete creee par Christophe Blaess , Stephan Rafin , Thierry Vignaud , Francois Micaux, Alain Portal , Jean-Philippe Guerard , Jean-Luc Coulon (f5ibh) , Julien Cristau , Thomas Huriaux , Nicolas Francois , Florentin Duneau , Simon Paillard , Denis Barbier , David Prevot et Jean-Paul Guillonneau Cette traduction est une documentation libre ; veuillez vous reporter a la GNU General Public License version 3 concernant les conditions de copie et de distribution. Il n'y a aucune RESPONSABILITE LEGALE. Si vous decouvrez un bogue dans la traduction de cette page de manuel, veuillez envoyer un message a . Pages du manuel de Linux 6.9.1 15 juin 2024 man-pages(7)