Provided by: manpages-fr_4.19.0-7_all bug

NOM

       man-pages - Conventions pour l'écriture des pages de manuel Linux

SYNOPSIS

       man [section] titre

DESCRIPTION

       Cette  page  décrit les conventions qui devraient être utilisées pour l’écriture des pages
       de manuel du projet  man-pages  de  Linux,  qui  documente  l'interface  de  programmation
       applicative  pour l’espace utilisateur fourni par le noyau Linux et la bibliothèque GNU C.
       Le projet fournit donc  la  plupart  des  pages  de  la  section 2,  de  nombreuses  pages
       apparaissant  dans  les  sections 3,  4,  5  et 7, et quelques pages apparaissant dans les
       sections 1, 5 et 8 des pages de manuel sur un système Linux. Les conventions décrites dans
       cette page peuvent aussi être utiles aux auteurs de pages de manuel pour d'autres projets.

   Sections des pages de manuel
       Les sections du manuel sont traditionnellement les suivantes :

       1 Commandes de l’utilisateur (programmes)
              Commandes  pouvant  être  invoquées  par  l'utilisateur  depuis  un interpréteur de
              commandes.

       2 Appels système
              Fonctions enveloppant les opérations réalisées par le noyau.

       3 Fonctions des bibliothèques
              Toutes les fonctions des bibliothèques en excluant les enveloppes  d’appel  système
              (la plupart des fonctions de la libc).

       4 Fichiers spéciaux (périphériques)
              Fichiers   présents   dans   /dev   permettant   l’accès   aux   périphériques  par
              l’intermédiaire du noyau.

       5 Formats de fichier et fichiers de configuration
              Descriptions des formats de fichier lisibles par  un  humain  et  des  fichiers  de
              configuration.

       6 Jeux Jeux et petits programmes amusants disponibles sur le système.

       7 Vue d’ensemble, conventions et éléments divers
              Vues  d’ensemble  ou  descriptions de divers sujets, des protocoles et conventions,
              des jeux de caractères normalisés, de  la  structure  du  système  de  fichiers  et
              d'autres choses diverses.

       8 Commandes d'administration du système
              Commandes    comme   mount(8),   la   plupart   exécutables   uniquement   par   le
              superutilisateur.

   Paquet de macros
       Les nouvelles pages de manuel devraient être mises en forme en utilisant le paquet an.tmac
       de groff décrit dans man(7). Ce choix est principalement destiné à assurer une cohérence :
       la plupart des pages de manuel Linux sont mises en forme avec ces macros.

   Conventions pour la présentation des fichiers sources
       Veuillez limiter la longueur des lignes dans le source à environ 75 caractères, autant que
       faire  se  peut.  Cela  permet  d'éviter les retours à la ligne ajoutés par les clients de
       courriel lorsque des modifications sont soumises par ce moyen.

   Ligne de titre
       La première commande d'une page de manuel devrait être une commande TH :

              .TH titre section date source section_manuel

       Les arguments de cette commande sont les suivants :

       titre  Le titre de la page de manuel, en majuscules (par exemple MAN-PAGES).

       section
              Le numéro de section dans laquelle la page devrait être placée (par exemple, 7).

       date   La date du dernier changement non trivial effectué sur cette  page  de  manuel.  Au
              sein  du  projet  man-pages,  les  mises  à  jour  des  étiquettes temporelles sont
              automatiquement effectuées par des scripts, de sorte qu'il n'est pas nécessaire  de
              les  mettre  à  jour  lors  la  fourniture d'un correctif. Les dates devraient être
              écrites sous la forme AAAA-MM-JJ.

       source Le nom et la version du projet fournissant la page de manuel (pas nécessairement le
              paquet fournissant la fonctionnalité).

       section_manuel
              Normalement  cela  devrait  être  vide puisque la valeur par défaut devrait être la
              bonne.

   Sections dans une page de manuel
       La liste ci-dessous indique les sections classiques ou suggérées.  La  plupart  des  pages
       devraient  contenir  au  moins les sections mises en évidence. Dans les nouvelles pages de
       manuel, placez les sections dans l'ordre indiqué dans la liste.

              NAME (NOM)
              BIBLIOTHÈQUE            [Normalement seulement dans les Sections 2 et 3]
              SYNOPSIS
              CONFIGURATION           [Normalement seulement dans la Section 4]
              DESCRIPTION
              OPTIONS                 [Normalement seulement dans les Sections 1 et 8]
              CODE DE RETOUR          [Normalement seulement dans les Sections 1 et 8]
              VALEUR RENVOYÉE         [Normalement seulement dans les Sections 2 et 3]
              ERREURS                 [Typiquement seulement dans les Sections 2 et 3]
              ENVIRONNEMENT
              FICHIERS
              VERSIONS                [Normalement seulement dans les Sections 2 et 3]
              ATTRIBUTS               [Normalement seulement dans les Sections 2 et 3]
              STANDARDS
              NOTES
              AVERTISSEMENTS
              BOGUES
              EXEMPLES
              AUTEURS                 [Déconseillé]
              SIGNALER DES BOGUES     [Non utilisé dans man-pages]
              COPYRIGHT               [Non utilisé dans man-pages]
              SEE ALSO (VOIR AUSSI)

       Lorsque l'une des sections traditionnelles s'applique, utilisez-la ; cette cohérence  rend
       l'information  plus  facile  à  comprendre.  Si cela est nécessaire, vous pouvez créer vos
       propres titres de section si cela rend les choses plus  compréhensibles  (particulièrement
       pour  les  pages  des  sections 4 et 5). Cependant, avant de faire cela, vérifiez qu'aucun
       titre de section traditionnel ne peut être  utilisé  avec  des  sous-sections  (.SS)  dans
       celle-ci.

       La liste suivante décrit le contenu de chacune des sections ci-dessus.

       NAME (NOM)
              Nom de cette page de manuel

              D'importantes  précisions  sur les lignes qui devraient suivre la commande .SH NAME
              sont disponibles dans la page man(7). Tous les mots de cette ligne  (y  compris  le
              mot  suivant immédiatement le « \- », sauf en français, dans les traductions, où la
              convention est de commencer le premier mot par une  majuscule)  devraient  être  en
              minuscules,  sauf  si  l'anglais  ou  la convention terminologique technique impose
              autre chose.

       BIBLIOTHÈQUE
              Bibliothèque fournissant un symbole.

              Cela montre le nom courant de la bibliothèque et,  entre  parenthèses,  le  nom  du
              fichier  de  la bibliothèque et, si nécessaire, l'indicateur nécessaire à l’éditeur
              de liens pour lier un programme avec elle : (libfoo[, -lfoo]).

       SYNOPSIS
              Bref résumé de l’interface de la commande ou de la fonction.

              Pour les commandes, ce paragraphe montre la syntaxe et les arguments de la commande
              (y  compris  les  options).  Les caractères en gras marquent le texte invariable et
              ceux  en  italique  indiquent  les  arguments  remplaçables.  Les  crochets  « [] »
              encadrent  les  arguments  facultatifs,  les  barres  verticales « | » séparent les
              alternatives et les  points  de  suspension  « ... »  peuvent  être  des  arguments
              répétés.  Pour  les  fonctions, cela contient toutes les déclarations de données ou
              les directives #include, suivies de la déclaration de fonction.

              Si une  macro  de  test  de  fonctionnalité  doit  être  définie  pour  obtenir  la
              déclaration  d'une fonction (ou d'une variable) dans un fichier d'en-tête, alors la
              section SYNOPSIS devrait l'indiquer, comme décrit dans feature_test_macros(7).

       CONFIGURATION
              Détails de configuration pour un périphérique.

              Cette section est présente normalement que dans les pages de la section 4.

       DESCRIPTION
              Explication sur ce que le programme, la fonction ou le format réalise.

              Cette section décrit les interactions avec les fichiers et l'entrée standard, et ce
              qui  est  produit  sur la sortie standard ou d'erreur. Les détails d'implémentation
              internes  sont  omis  sauf  s'ils  sont  critiques  pour  comprendre   l'interface.
              L’utilisation  habituelle  est  décrite et la section OPTIONS est utilisée pour les
              détails.

              La description d'un nouveau comportement ou de nouveaux drapeaux d'un appel système
              ou  d'une  fonction  d'une  bibliothèque doit préciser la version du noyau ou de la
              bibliothèque C qui a introduit ce changement. Il  est  recommandé  de  noter  cette
              information  à  propos des drapeaux sous la forme d'une liste .TP, comme ci-dessous
              dans le cas d'un drapeau d'appel système :

                       XYZ_FLAG (depuis Linux 3.7)
                              Description du drapeau...

              Préciser la version est particulièrement utile aux utilisateurs qui sont contraints
              d’utiliser  d'anciennes  versions  du noyau ou de la bibliothèque C, ce qui est par
              exemple courant dans le cas des systèmes embarqués.

       OPTIONS
              Descriptions des options de ligne de commande acceptées par un  programme  et  leur
              influence sur son comportement.

              Cette  section ne devrait être utilisée que pour les pages de manuel des sections 1
              et 8.

       EXIT STATUS (CODE DE RETOUR)
              Liste des codes de retour d'un  programme  et  des  conditions  de  renvoi  de  ces
              valeurs.

              Cette  section ne devrait être utilisée que pour les pages de manuel des sections 1
              et 8.

       RETURN VALUE (VALEUR RENVOYÉE)
              Pour les pages des sections 2 et 3, cette  section  donne  une  liste  des  valeurs
              qu'une  routine  de  bibliothèque  renverra  à  l'appelant  et  les  conditions qui
              provoquent ces retours.

       ERRORS (ERREURS)
              Pour les pages des sections 2 et 3, cette section contient une  liste  des  valeurs
              possibles de errno en cas d'erreur, avec la description des causes de ces erreurs.

              Quand  des  conditions différentes produisent la même erreur, l’approche à préférer
              est de créer plusieurs entrées de liste séparées (avec des noms d’erreur dupliqués)
              pour  chacune  des conditions. Cela clarifie les différences de conditions, rend la
              liste plus facile à lire et permet aux méta-informations (par exemple, le numéro de
              version  du  noyau  dans  laquelle  la condition est devenu applicable) d’être plus
              facilement caractérisées pour chaque condition.

              La liste d’erreurs devrait être triée par ordre alphabétique.

       ENVIRONMENT (ENVIRONNEMENT)
              Liste de  toutes  les  variables  d'environnement  affectant  le  programme  ou  la
              fonction, ainsi que de leurs effets.

       FILES (FICHIERS)
              Liste  de  tous  les  fichiers  utilisés  par le programme ou la fonction, tels les
              fichiers de configuration, les fichiers de  démarrage  et  les  fichiers  manipulés
              directement par le programme.

              Le  chemin  d'accès  complet de ces fichiers doit être donné ainsi que le mécanisme
              d'installation utilisé pour modifier la partie répertoire afin  de  satisfaire  aux
              préférences  de  l’utilisateur.  Pour la plupart des programmes, l'installation par
              défaut se fait dans /usr/local,  aussi,  votre  page  de  manuel  de  base  devrait
              utiliser /usr/local comme base.

       ATTRIBUTES (ATTRIBUTS)
              Résumé  des  divers  attributs  de  la ou des fonctions documentées sur cette page.
              Consulter attributes(7) pour de plus amples détails.

       VERSIONS
              Court résumé de la version du noyau Linux ou de la glibc où l'appel système  ou  la
              fonction  de  bibliothèque  est  apparue  ou  dont le fonctionnement est modifié de
              manière significative.

              De manière générale, la page de manuel de chaque nouvelle interface devrait inclure
              une  section  VERSIONS.  Malheureusement,  bien  des  pages  de  manuel  existantes
              n'incluent pas cette information (car il n'y avait pas de politique pour  le  faire
              lorsqu'elles  ont été rédigées). Les correctifs pour y remédier sont les bienvenus.
              Dans la perspective d'écriture de nouveau code, cette information n'a de  sens  que
              dans  le  cas  d'interface  noyau  ajoutée à Linux 2.4 ou suivant (c'est-à-dire les
              modifications depuis la version 2.2 du noyau), et dans celui des  fonctions  de  la
              bibliothèque   ajoutées   dans   glibc  depuis  la  version 2.1  (c'est-à-dire  les
              modifications depuis la version 2.0 de la glibc).

              La page de manuel syscalls(2) fournit également des  informations  de  versions  de
              noyau dans lesquelles sont apparus les appels système.

       STANDARDS
              Descriptions des normes ou conventions liées à la fonction ou à la commande décrite
              par la page de manuel.

              Les termes privilégiés à utiliser pour les différentes normes sont listés dans  les
              rubriques de standards(7)

              Dans  les  pages  de section 2 ou 3, cette section devrait indiquer les versions de
              POSIX.1 auxquelles l'appel se conforme et s'il est spécifié par C99 (pas  la  peine
              de  trop  se  préoccuper  des  autres  normes  comme  SUS,  SUSv2  ou  XPG,  ni des
              implémentations SVr4 ou 4.xBSD,  sauf  si  la  fonction  était  présente  dans  ces
              systèmes mais ne l'est plus dans la version actuelle de POSIX.1).

              Si  la  fonction  n'est  régie par aucune norme, mais existe sur d'autres systèmes,
              mentionnez-les. Si elle est spécifique à Linux, notez-le.

              Si cette section ne consiste qu'en une liste de normes (ce qui  est  d'habitude  le
              cas), terminez la liste par un point (« . »).

       NOTES  Notes diverses

              Pour les pages des sections 2 et 3, il peut être utile d'utiliser des sous-sections
              (SS) appelées Linux Notes (Notes sur Linux) ou glibc Notes (Notes sur la glibc).

              Dans la section 2, le titre  C  library/kernel  differences  est  à  utiliser  pour
              délimiter  les notes décrivant les différences (s’il en existe) entre la fonction C
              d’enveloppe de bibliothèque pour un appel  système  et  l’interface  brute  d’appel
              système fournie par le noyau.

       AVERTISSEMENTS
              Avertissements  sur  une  mauvaise utilisation courante d’une API, qui ne constitue
              pas un bogue de celle-ci, ni un défaut de conception.

       BUGS (BOGUES)
              Liste des limitations, des défauts ou des inconvénients  recensés,  ainsi  que  des
              sujets à débat.

       EXAMPLES (EXEMPLES)
              Un  ou  plusieurs  exemples  d'utilisation  de  la  fonction,  du  fichier ou de la
              commande.

              Pour plus de détails sur l'écriture d'exemples de programme, consultez Exemples  de
              programme ci-dessous.

       AUTHORS (AUTEURS)
              Liste des auteurs de la documentation ou du programme.

              L'utilisation d'une section AUTHORS est fortement déconseillée. En général, il vaut
              mieux ne pas encombrer chaque  page  de  manuel  avec  une  liste  (potentiellement
              longue)  d'auteurs.  Si  vous  écrivez  ou  modifiez  de façon importante une page,
              ajoutez une notice de copyright en commentaire dans le fichier source. Si vous êtes
              l'auteur  d'un  pilote  de périphérique et voulez inclure une adresse pour signaler
              les bogues, placez-la dans la section BUGS.

       SIGNALER DES BOGUES
              Le projet man-pages n’utilise pas de section  REPORTING  BUGS  dans  les  pages  de
              manuel.  La  manière de signaler des bogues est à la place indiquée dans la section
              COLOPHON générée par un script. Cependant, divers  projets  utilisent  une  section
              REPORTING BUGS. Il est recommandé de la placer près de la fin de page.

       COPYRIGHT
              Le  projet  man-pages  n’utilise pas de section COPYRIGHT dans les pages de manuel.
              Les informations de droits d’auteur sont à la place entretenues dans le  source  de
              la  page. Dans les pages incluant cette section, il est recommandée de la placer en
              bas de page, juste au-dessus de la section SEE ALSO.

       SEE ALSO (VOIR AUSSI)
              Liste  des  pages  de  manuel  (séparées  par  des  virgules)  ayant  un   rapport,
              éventuellement suivie par d’autres pages ou documents ayant un rapport.

              La   liste   devrait  être  classée  selon  l'ordre  des  sections  puis  de  façon
              alphabétique. Ne terminez pas la liste par un point.

              Quand la liste SEE ALSO contient plusieurs noms  longs  de  page  de  manuel,  pour
              améliorer  l'apparence  de  la sortie, il peut être utile d'utiliser les directives
              .ad l (pas de justification à droite) et .nh (pas de césure). La césure d'un nom de
              page  en  particulier  peut-être  évitée  en  faisant précéder son nom de la chaîne
              « \% ».

              Étant donné la nature indépendante et distribuée  des  projets  logiciels  au  code
              source  ouvert  (FOSS) et de leur documentation, il est parfois nécessaire (et dans
              de nombreux cas souhaitable) que la section SEE ALSO inclut des références vers des
              pages de manuel fournies par d’autres projets.

CONVENTIONS DE FORMATAGE ET DE FORMULATION

       Les  sous-sections suivantes fournissent quelques indications de préférences de convention
       de formatage et de formulation dans diverses sections des pages du projet man-pages.

   SYNOPSIS
       Entourer le(s) prototype(s) de fonction d'une paire .nf/.fi pour empêcher le remplissage.

       En général, lorsque plus d’un prototype  de  fonction  sont  indiqués  dans  le  SYNOPSIS,
       ceux-ci  ne  devraient  pas  être  séparés  par des lignes blanches. Cependant, des lignes
       blanches (ajoutées en utilisant .PP) peuvent être utilisées dans les cas suivants :

       •  pour la séparation de longues listes de prototypes de  fonctions  en  groupes  de  même
          sujet (consulter par exemple list(3));

       •  dans d’autres cas pouvant améliorer la lisibilité.

       Dans  le  SYNOPSIS, un prototype de fonction long peut nécessiter d’être continué dans une
       nouvelle ligne. Celle-ci sera indentée selon les règles suivantes :

       (1)  S’il existe un seul prototype devant être continué, alors la  ligne  de  continuation
            doit  être  alignée de façon à ce que lorsque la page est rendue dans un périphérique
            dont la fonte est de largeur fixe (par exemple,  xterm),  la  ligne  de  continuation
            débute  juste  en  dessous  du  début  de  la liste d’arguments de la ligne au-dessus
            (exception : l’indentation peut être ajustée si nécessaire  pour  empêcher  une  très
            longue  ligne  de continuation ou une autre ligne de continuation si le prototype est
            très long). Un exemple :

                int tcsetattr(int fd, int optional_actions,
                              const struct termios *termios_p);

       (2)  Mais,  quand  plusieurs  fonctions  dans  le  SYNOPSIS  nécessitent  des  lignes   de
            continuation  alors  que  les  noms  de fonction sont de différentes longueurs, alors
            l’alignement des lignes de continuation doit  débuter  dans  la  même  colonne.  Cela
            fournit un rendu plus agréable dans une sortie PDF (parce que le SYNOPSIS utilise une
            fonte de taille variable où le rendu des espaces est plus  étroit  que  celui  de  la
            plupart des caractères). Un exemple :

                int getopt(int argc, char * const argv[],
                           const char *optstring);
                int getopt_long(int argc, char * const argv[],
                           const char *optstring,
                           const struct option *longopts, int *longindex);

   VALEUR RENVOYÉE
       La  formulation  préférée  pour  décrire  comment  errno est définie est « errno is set to
       indicate the error » ou similaire. Cela s’accorde avec  celle  utilisée  dans  POSIX.1  et
       FreeBSD.

   ATTRIBUTS
       Il est à noter que :

       •  entourer  la  table  dans  cette  section  d'une  paire  .ad l/.ad  pour  désactiver le
          remplissage de texte et d'une paire .nh/.hy pour désactiver la coupure des mots en  fin
          de ligne ;

       •  s'assurer  que  la  table occupe toute la largeur de la page à l’aide de la description
          lbx pour une des colonnes (habituellement la première colonne, bien que  dans  certains
          cas ce soit la dernière colonne si elle contient beaucoup de texte) ;

       •  ne  pas  hésiter  à utiliser la paire de macros T{/T} pour permettre aux cellules de la
          table d’être découpées en plusieurs lignes (en gardant en tête que  les  pages  peuvent
          quelquefois être rendues en moins de 80 colonnes.

       Pour des exemples de tout cela, consultez le code source de diverses pages.

GUIDE DE STYLE

       Les  sous-sections  suivantes décrivent le style privilégié pour le projet man-pages. Pour
       des précisions sur les points non couverts ci-dessous, le « Chicago Manual of Style »  est
       généralement  une  source  de qualité. Essayez également de parcourir les pages existantes
       dans l’arborescence  des  sources  du  projet  pour  prendre  connaissance  des  habitudes
       courantes.

   Utilisation de formulation neutre
       Autant  que  possible,  utilisez le pluriel de genre neutre (en anglais) dans le texte des
       pages de manuel. L’utilisation de « they » (« them », « themself », « their ») en tant que
       pronom singulier de genre neutre est acceptable.

   Conventions typographiques pour les pages de manuel décrivant des commandes
       Pour  les  pages  de manuel décrivant une commande (généralement dans les sections 1 et 8)
       les arguments sont toujours indiqués en italique, même dans la section SYNOPSIS.

       Le nom de la commande et de ses options devraient toujours être en caractères gras.

   Conventions typographiques pour les pages de manuel décrivant des fonctions
       Pour les pages de manuel décrivant une fonction (généralement dans  les  sections 2  et 3)
       les  arguments  sont  toujours  indiqués en italique, même dans la section SYNOPSIS, où le
       reste de la fonction est indiqué en caractères gras.

        int mafonction(int argc, char **argv);

       Les noms de variables devraient, tout comme les  noms  de  paramètres,  être  indiqués  en
       italique.

       Toute  référence au sujet de la page de manuel courante devrait être écrite avec le nom en
       caractères gras suivi par une paire de parenthèses en caractères  romains  (normaux).  Par
       exemple,  dans  la  page fcntl(2), les références au sujet de la page devrait être écrites
       fcntl(). La façon privilégiée d'écrire cela dans le fichier source est :

           .BR fcntl ()

       (L’utilisation de ce format, plutôt que  celle  de  « \fB...\fP() »,  facilite  l’écriture
       d’outils qui analysent les sources des pages de manuel.)

   Utilisation de nouvelles lignes sémantiques
       Dans  le  code source d’une page de manuel, les nouvelles phrases devraient débuter sur de
       nouvelles lignes et les phrases longues découpées  en  lignes  selon  les  changements  de
       proposition  (virgules, deux-points, points-virgules, etc.), et les propositions devraient
       être coupées aux limites de phrase. Cette convention, parfois appelée  « nouvelles  lignes
       sémantiques »,  facilite  la visualisation de l'effet des correctifs qui opèrent au niveau
       des lignes, propositions ou phrases individuelles.

   Listes
       Différentes sortes de liste existent :

       Paragraphes avec étiquettes
              Ils sont utilisés pour une liste d’étiquettes  et  leurs  descriptions.  Quand  les
              étiquettes  sont  des  constantes  (soit  des macros ou des nombres), elles sont en
              gras. Utilisez la macro .TP.

              Cette sous-section « Paragraphes avec étiquettes » constitue elle-même un exemple.

       Listes ordonnées
              Les éléments sont précédés par un nombre entre parenthèses (1), (2).  Ces  derniers
              représentent un succession d’étapes qui ont un ordre.

              S’il existe des sous-étapes, elles seront numérotées comme (4.2).

       Listes positionnelles
              Les  éléments  sont  précédés  par  un nombre (indice) entre crochets [4], [5]. Ces
              derniers représentent des champs dans un ensemble. Le premier indice sera :

              0      quand il représente des champs dans une structure de données en C, pour être
                     cohérent avec les tableaux ;
              1      quand  il  représente  des  champs d’un fichier, pour être cohérent avec des
                     outils comme cut(1).

       Liste d’alternatives
              Les éléments sont précédés par une lettre entre parenthèses (a), (b). Ces dernières
              représentent une liste d’alternatives exclusives (normalement).

       Listes à puces
              Les  éléments sont précédés par une puce (\[bu]). Tout ce qui ne convient pas autre
              part est habituellement couvert par ce type de liste.

       Notes numérotées
              Ce ne sont pas réellement des listes, mais leur syntaxe est identique à  celle  des
              « listes positionnelles ».

       Il  devrait  toujours  y avoir exactement deux espaces entre le symbole de la liste et les
       éléments. Cela ne s’applique pas aux « paragraphes avec  étiquettes »  qui  utilisent  les
       règles d’indentation par défaut.

   Conventions typographiques (générales)
       Les  paragraphes devraient être séparés par des marqueurs adaptés (habituellement soit .PP
       ou .IP). Ne pas séparer les paragraphes en utilisant des lignes blanches, car cela aboutit
       à un rendu médiocre dans certains formats de sortie (tels que PostScript et PDF).

       Les  noms de fichiers, que ce soit des chemins ou des références à des fichiers d’en-tête,
       sont toujours en italique (par exemple <stdio.h>), sauf dans la section  SYNOPSIS  où  les
       fichiers  inclus  sont  en  caractères gras (par exemple #include <stdio.h>). Lorsque vous
       faites référence à un fichier d'en-tête standard, indiquez le fichier d'en-tête entouré de
       chevrons, de la même manière que dans un fichier source C (par exemple, <stdio.h>).

       Les  macros  spéciales,  généralement  en majuscules, sont en caractères gras (par exemple
       MAXINT). Exception : NULL ne doit pas être en gras.

       Dans l'énumération d'une liste de codes d'erreur, les codes sont en caractères gras, et la
       liste utilise normalement la macro .TP.

       Les  commandes  complètes  devraient,  si  elles sont longues, être écrites sous une forme
       indentée, précédées et suivies d’une ligne vide, par exemple :

           man 7 man-pages

       Si la commande est courte, elle peut être incluse dans le texte, en italique, par exemple,
       man 7 man-pages. Dans ce cas, des espaces insécables (\[ti]) pourraient être utilisées aux
       endroits appropriés dans la commande. Les options des commandes devraient elles aussi être
       écrites en italique (par exemple, -l).

       Les  expressions,  si  elles ne sont pas écrites sur une ligne séparée indentée, devraient
       être mises en italique. Ici aussi, l'utilisation d'espaces insécables  est  appropriée  si
       l'expression est mélangée à du texte normal.

       Pour  montrer  des  sessions  d’interpréteur  de  commandes,  les saisies de l’utilisateur
       devraient être écrites en caractères gras.

           $ date
           Thu Jul  7 13:01:27 CEST 2016

       Toute référence à une autre page de manuel devrait être écrite avec le nom  en  caractères
       gras  toujours  suivi  du  numéro  de section en caractères romains (normaux), sans espace
       intermédiaire (par exemple intro(2)). Dans le source, la façon préconisée est :

           .BR intro (2)

       (Inclure le numéro de section dans les références  croisées  permet  à  des  outils  comme
       man2html(1) de créer des liens hypertextes appropriés)

       Les   caractères  de  contrôle  devraient  être  écrits  en  gras,  sans  guillemets.  Par
       exemple : ^X.

   Orthographe
       Depuis  la  version 2.59,  la  version  anglaise  de  man-pages   suit   les   conventions
       orthographiques  américaines (auparavant, un mélange aléatoire de conventions britanniques
       et américaines existait). Veuillez écrire les nouvelles pages et les correctifs en suivant
       ces conventions.

       En  plus  des  différences  d’orthographe  bien connues, quelques autres subtilités sont à
       surveiller :

       •  L’anglais  américain  a  tendance  à  utiliser  les  formes  « backward »,  « upward »,
          « toward », etc.,   au   lieu   des  formes  britanniques  « backwards »,  « upwards »,
          « towards », etc.

       •  Les  avis  divergent  entre  « acknowledgement »  et  « acknowledgment ».  Ce   dernier
          prédomine,  mais  n’est  pas toujours utilisé en anglais-américain. POSIX et la licence
          BSD utilisent la première  orthographe.  Dans  le  projet  man-pages  de  Linux,  c'est
          « acknowledgement » qui est utilisé.

   Numéros de version BSD
       Le schéma classique d’écriture des numéros de version BSD est x.yBSD, où x.y est un numéro
       de version (par exemple 4.2BSD). Éviter les formes du genre BSD 4.3.

   Capitalisation
       Dans les titres de sous-section (« SS »), le premier mot commence par une  capitale,  mais
       le  reste  devrait  être en minuscule, sauf si l'anglais (par exemple les noms propres) ou
       les exigences du langage de programmation imposent autre  chose  (par  exemple,  les  noms
       d’identificateur). Par exemple :

           .SS Unicode sous Linux

   Indentation des définitions de structure, des journaux d’interpréteur, etc.
       Lorsque  des  définitions de structure, des journaux de session d'interpréteur, etc., sont
       inclus dans le corps de texte, indentez-les avec  quatre  espaces  (c'est-à-dire  un  bloc
       entouré  par  .in +4n  et  .in),  formatez-les  en  utilisant  les  macros  .EX  et .EE et
       entourez-les avec les marqueurs de paragraphe adaptés (soit .PP ou .IP). Par exemple :

           .PP
           .in +4n
           .EX
           int
           main(int argc, char *argv[])
           {
               return 0;
           }
           .EE
           .in
           .PP

   Termes privilégiés
       Le tableau suivant indique les termes à privilégier dans les pages  anglaises  de  manuel,
       principalement pour assurer une cohérence entres les pages.

       Terme                Utilisation à éviter     Notes
       ───────────────────────────────────────────────────────────────────
       bit mask             bitmask
       built-in             builtin
       Epoch                epoch                    Pour l’époque
                                                     d’UNIX (00:00:00, 1
                                                     Jan 1970 UTC)
       filename             file name
       filesystem           file system
       hostname             host name
       inode                i-node
       lowercase            lower case, lower-case
       nonzero              non-zero
       pathname             path name
       pseudoterminal       pseudo-terminal
       privileged port      reserved port, system
                            port
       real-time            realtime, real time

       run time             runtime
       saved set-group-ID   saved group ID, saved
                            set-GID
       saved set-user-ID    saved user ID, saved
                            set-UID
       set-group-ID         set-GID, setgid
       set-user-ID          set-UID, setuid
       superuser            super user, super-user
       superblock           super block,
                            super-block
       lien symbolique      symlink
       timestamp            time stamp
       timezone             time zone
       uppercase            upper case, upper-case
       usable               useable
       user space           userspace
       username             user name
       x86-64               x86_64                   Excepté si cela se
                                                     réfère à « uname -m
                                                     » ou similaire
       zeros                zeroes

       Consultez la section Écriture des mots composés épithètes ci-dessous.

   Termes à éviter
       Le tableau suivant indique les termes à éviter dans les pages anglaises de manuel, avec
       quelques suggestions d’alternatives, principalement pour assurer la cohérence entres les
       pages.

       Avoid             Use instead             Notes
       ─────────────────────────────────────────────────────────────────

       32bit             32-bit                  de même pour 8-bit,
                                                 16-bit, etc.
       current process   calling process         Une erreur commune des
                                                 programmeurs du noyau
                                                 qui écrivent des pages
                                                 de manuel
       manpage           man page, manual page
       minus infinity    negative infinity
       non-root          unprivileged user
       non-superuser     unprivileged user
       nonprivileged     unprivileged
       OS                operating system
       plus infinity     positive infinity
       pty               pseudoterminal
       tty               terminal
       Unices            UNIX systems
       Unixes            UNIX systems

   Marques déposées
       Utiliser  l’orthographe  et  la casse adéquates pour les marques déposées. Voici une liste
       des orthographes adéquates de quelques marques déposées parfois mal orthographiées :

              DG/UX
              HP-UX
              UNIX
              UnixWare

   NULL, NUL, pointeur NULL et octet NULL
       Un pointeur NULL est un pointeur qui ne pointe nulle part, et est  habituellement  indiqué
       par  la  constante NULL. D’un autre côté, NUL est l’octet NULL : un octet de valeur nulle,
       représenté en C à l’aide de la constante caractère « \0 ».

       Le terme à préférer pour le pointeur est « null pointer » (pointeur  NULL)  ou  simplement
       « NULL ». Éviter d’écrire « NULL pointer ».

       Le  terme  à préférer pour l’octet est « null byte » (octet NULL). Évitez d’écrire « NUL »
       car cela pourrait être facilement confondu avec « NULL ». Évitez aussi les  termes  « zero
       byte » (octet zéro) et « null character » (caractère NULL). L’octet qui termine une chaîne
       en C devrait être décrit comme « the terminating null byte »  (l’octet  NULL  final).  Les
       chaînes  peuvent être décrites comme « null-terminated » (terminées par NULL), mais évitez
       « NUL-terminated » (terminées par NUL).

   Liens hypertextes
       Pour  les  liens  hypertextes,  utilisez  la  paire  de  macros  .UR  et  .UE   (consultez
       groff_man(7)).  Cela  produit  des  liens  propres  qui  peuvent  être  utilisés  dans des
       navigateurs web, lors du rendu de pages, avec par exemple :

           BROWSER=firefox man -H nom_de_page

   Utilisation de e.g., i.e., etc., a.k.a., et autres
       En général, l’utilisation d’abréviations comme « e.g. », « i.e. »,  « etc. »,  « cf. »  et
       « a.k.a. » devrait être évitée, en faveur d’une écriture complète (« for example », « that
       is », « and so on », « compare  to »,  « also  known  as »)  (Idem  pour  les  traductions
       françaises des pages de manuel).

       Le  seul  endroit  où  ce  genre  d’abréviation  pourrait  être  acceptable  est  dans les
       parenthèses courtes (e.g., like this one).

       Toujours inclure les points dans ces abréviations comme ici. De plus en anglais,  « e.g. »
       et « i.e. » devraient toujours êtres suivies d’une virgule.

   Tirets longs
       La façon d’écrire un tiret cadratin « em-dash », le glyphe apparaissant à chaque extrémité
       d’une proposition incise, est dans *roff la macro « \[em] ». (Sur un  terminal  ASCII,  un
       tiret  long  est  vu  comme  deux tirets courts, mais dans des contextes typographiques il
       apparait comme un  tiret  long.)  Les  « em-dash »  devraient  être  écrits  sans  espaces
       avoisinantes.

   Écriture des mot composés épithètes
       Les  mots  composés  devraient  être  reliés  par un tiret lorsqu’utilisés comme attributs
       (c'est-à-dire pour qualifier un nom suivant). Quelques exemples :

              32-bit value
              command-line argument
              floating-point number
              run-time check
              user-space function
              wide-character string

   Séparation des mots avec les préfixes multi, non, pre, re, sub, etc.
       La tendance générale en anglais moderne est  de  ne  pas  utiliser  de  tirets  après  les
       préfixes  comme  « multi »,  « non »,  « pre »,  « re », « sub », etc. Les pages de manuel
       devraient normalement suivre cette  règle  quand  ces  préfixes  sont  utilisés  dans  des
       constructions  anglaises  naturelles avec de simples suffixes. La liste suivante donne des
       exemples de forme préférée :

              interprocess
              multithreaded
              multiprocess
              nonblocking
              nondefault
              nonempty
              noninteractive
              nonnegative
              nonportable
              nonzero
              preallocated
              precreate
              prerecorded
              reestablished
              reinitialize
              rearm
              reread

              subcomponent
              subdirectory
              subsystem

       Les tirets sont gardés en anglais lorsque les préfixes sont utilisés dans des mots anglais
       non  standard,  avec  les  marques  déposées,  les noms propres, les acronymes ou les mots
       composés. Quelques exemples :

              non-ASCII
              non-English
              non-NULL
              non-real-time

       Enfin, remarquez qu’en anglais « re-create »(recréer) et « recreate » (s’amuser) sont deux
       mots différents et que c’est sans doute le premier qu’il faut utiliser.

   Génération des glyphes optimaux
       Quand  un véritable caractère moins est nécessaire (par exemple pour les nombres comme -1,
       pour des références croisées de pages de manuel telles que utf-8(7)  ou  pour  écrire  des
       options  qui commencent par un tiret comme dans ls -l), utilisez la forme suivante dans le
       source de la page de manuel :

           \-

       Ce guide s’applique aussi aux exemples de code.

       L’utilisation d’un vrai signe moins a pour buts :

       •  fourniture d’un meilleur rendu dans diverses cibles autres  que  les  terminaux  ASCII,
          particulièrement pour les PDF et les terminaux adaptés à l’Unicode/UTF-8 ;

       •  pour  créer des glyphes qui, s’ils sont copiés depuis des rendus de page, produiront un
          vrai signe moins s’ils sont collés dans un terminal.

       Pour produire des guillemets simples  qui  rendront  aussi  bien  en  ASCII  qu’en  UTF-8,
       utilisez « \[aq] » (« apostrophe quote »). Par exemple :

           \[aq]C\[aq]

       où  C  est  le  caractère  protégé.  Ce  guide  s’applique  aussi aux constantes caractère
       utilisées dans les exemples de code. Dans la traduction en français, si possible, préférez
       la forme typographique en vigueur (par exemple : « C »).

       Lorsque  qu’un  caret  approprié  (^)  dont  un  bon  rendu dans un terminal et en PDF est
       nécessaire, utilisez « \[ha] ». Cela est particulièrement nécessaire dans les exemples  de
       code, pour obtenir un rendu élégant du caret en PDF.

       L’utilisation  d’un  caractère nu « ~ » aboutit à un mauvais rendu en PDF. Utilisez plutôt
       « \[ti] ». Cela est particulièrement nécessaire dans les exemples de code, pour obtenir un
       rendu élégant du tilde en PDF.

   Programmes d'exemples et sessions d’interpréteur.
       Les pages de manuel peuvent contenir des programmes permettant de montrer comment utiliser
       un appel système ou une fonction de bibliothèque. Cependant, veuillez respecter les points
       suivants.

       •  Les programmes d'exemple devraient être écrits en C.

       •  Un  programme  d'exemple n'est nécessaire et utile que s'il montre quelque chose qui ne
          peut pas être fourni facilement dans  une  description  textuelle  de  l'interface.  Un
          programme d'exemple qui ne fait qu'appeler une fonction ne sert en général à rien.

       •  Les  programmes  d’exemple  devraient  idéalement  être  courts  (par  exemple,  un bon
          programme peut être souvent fourni avec moins de  100 lignes  de  code),  quoique  dans
          certains  cas  un  programme  plus  long  soit nécessaire pour illustrer convenablement
          l’utilisation d’une API.

       •  Du code expressif est apprécié.

       •  Des commentaires devraient être inclus là où c’est utile. Les  phrases  complètes  dans
          les  commentaires autonomes devraient être terminées par un point. Les points devraient
          être  généralement  omis  dans  les  commentaires  « d’étiquettes »  (c’est-à-dire  des
          commentaires  qui  sont  placés  sur la même ligne de code) — dans tous les cas de tels
          commentaires sont typiquement de courtes phrases plutôt que des phrases complètes.

       •  Les programmes d'exemple devraient faire une vérification d’erreurs  après  les  appels
          système et les appels de fonction de bibliothèque.

       •  Les  programmes  d'exemple devraient être complets et compiler sans avertissements avec
          cc -Wall.

       •  Si possible et raisonnable, les programmes d'exemples doivent permettre d'expérimenter,
          en changeant de comportement en fonction des entrées (arguments de ligne de commande ou
          entrées lues par le programme).

       •  Les programmes d'exemple doivent être mis en  forme  dans  le  style  de  Kernighan  et
          Ritchie,  avec  des indentations de quatre espaces (évitez le caractère tabulation dans
          les fichiers source). La commande suivante peut être utilisée pour mettre en  forme  le
          code source vers quelque chose proche du style préféré :

              indent -npro -kr -i4 -ts4 -sob -l72 -ss -nut -psl prog.c

       •  Par  cohérence,  tous  les  programmes d’exemple devraient se terminer par une des deux
          formes suivantes :

              exit(EXIT_SUCCESS);
              exit(EXIT_FAILURE);

          Évitez d’utiliser les formes suivantes pour terminer un programme :

              exit(0);
              exit(1);
              return n;

       •  Si un texte d’explication complète précède le code source  du  programme,  indiquez  le
          code source à l’aide d’un titre de sous-section Source du programme, comme :

              SS Source du programme

          Toujours  faire  comme  cela  si  le texte d’explication contient un journal de session
          d’interpréteur.

       Si vous  incluez  un  journal  de  session  d'interpréteur  de  commandes  pour  démontrer
       l'utilisation d'un programme ou d'autres fonctionnalités système :

       •  placez le journal de session au dessus du code source ;

       •  indentez le journal de session par quatre espaces ;

       •  mettez  le  texte  entré  par  l'utilisateur  en  gras  pour le distinguer de la sortie
          produite par le système.

       Pour voir à quoi les programmes d'exemples  devraient  ressembler,  consultez  wait(2)  et
       pipe(2).

EXEMPLES

       Pour  des  exemples  canoniques  de  pages  de  manuel  se conformant au paquet man-pages,
       consultez pipe(2) et fcntl(2).

VOIR AUSSI

       man(1), man2html(1), attributes(7), groff(7), groff_man(7), man(7), mdoc(7)

TRADUCTION

       La traduction française de cette  page  de  manuel  a  été  créée  par  Christophe  Blaess
       <https://www.blaess.fr/christophe/>,  Stéphan  Rafin  <stephan.rafin@laposte.net>, Thierry
       Vignaud <tvignaud@mandriva.com>, François Micaux, Alain  Portal  <aportal@univ-montp2.fr>,
       Jean-Philippe    Guérard   <fevrier@tigreraye.org>,   Jean-Luc   Coulon   (f5ibh)   <jean-
       luc.coulon@wanadoo.fr>,   Julien    Cristau    <jcristau@debian.org>,    Thomas    Huriaux
       <thomas.huriaux@gmail.com>, Nicolas François <nicolas.francois@centraliens.net>, Florentin
       Duneau <fduneau@gmail.com>, Simon Paillard <simon.paillard@resel.enst-bretagne.fr>,  Denis
       Barbier  <barbier@debian.org>,  David  Prévot <david@tilapin.org> et Jean-Paul Guillonneau
       <guillonneau.jeanpaul@free.fr>

       Cette traduction est une documentation libre ; veuillez vous reporter  à  la  GNU  General
       Public   License   version 3  ⟨https://www.gnu.org/licenses/gpl-3.0.html⟩  concernant  les
       conditions de copie et de distribution. Il n'y a aucune RESPONSABILITÉ LÉGALE.

       Si vous découvrez un bogue dans la traduction de cette page de manuel, veuillez envoyer un
       message à ⟨debian-l10n-french@lists.debian.org⟩.