Provided by: manpages-fr_3.32d0.2p4-1_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 utilisées pour les pages de manuel du projet man-pages
       pour Linux, qui contient les pages de manuel pour Linux dans les sections 2, 3, 4, 5 et 7.
       Les  conventions décrites sur cette page peuvent aussi être utiles aux auteurs de pages de
       manuels pour d'autres projets.

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

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

       2 Appels système
                 Les fonctions fournies par le noyau.

       3 Fonctions de bibliothèques
                 La plupart des fonctions de la bibliothèque C (libc).

       4 Fichiers spéciaux (périphériques)
                 Fichiers spéciaux trouvés dans /dev.

       5 Formats de fichiers et conventions
                 Le format de /etc/passwd et d'autres fichiers lisibles par un humain.

       6 Jeux

       7 Conventions et divers
                 Panorama  de  divers  sujets,  conventions  et  protocoles,  normes  de  jeux de
                 caractères, et diverses autres choses.

       8 Commandes d'administration système
                 Les commandes comme mount(8), que seul root peut exécuter.

   Paquet de macros
       Les nouvelles pages de manuel doivent être mises en forme en  utilisant  le  paquet  groff
       an.tmac  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 l'agencement des 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 mail
       lorsque des patches sont soumis par ce moyen.

       Chaque phrase doit commencer une ligne. Cela permet de voir plus  facilement  l'effet  des
       patches, qui s'appliquent souvent au niveau d'une phrase.

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

              .TH titre section date source manuel,

       où :

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

              section   Le numéro de section dans laquelle placer la page (par exemple 7).

              date      La  date  de  la  dernière  modification.  Pensez à modifier cette date à
                        chaque changement dans la page, car c'est la  manière  la  plus  courante
                        d'avoir  un  contrôle  de  version.  Les  dates  doivent être de la forme
                        AAAA-MM-JJ.

              source    La source de la commande, fonction, ou de l'appel système.

                        Pour les quelques pages de man-pages dans les sections 1  et  8,  il  est
                        conseillé d'écrire GNU.

                        Pour les appels système, écrivez simplement Linux. 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.

                        Pour les fonctions de bibliothèque de glibc ou de l'une des bibliothèques
                        GNU standards, utilisez GNU C Library, GNU, ou une chaîne vide.

                        Pour les pages de la section 4, utilisez Linux.

                        En cas d'hésitation, écrivez Linux ou GNU.

              manuel    Le titre du manuel (par exemple Linux Programmer's Manual pour les  pages
                        des sections 2 et 3 dans le paquet man-pages)

   Sections dans une page de manuel
       La  liste  ci‐dessous  indique les sections habituelles 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.

            Nom anglais     Nom français    Notes
            NAME            NOM
            SYNOPSIS        SYNOPSIS
            CONFIGURATION   CONFIGURATION   [En général seulement section 4]
            DESCRIPTION     DESCRIPTION
            OPTIONS         OPTIONS         [En général seulement sections 1, 8]
            EXIT STATUS     CODE DE RETOUR  [En général seulement sections 1, 8]
            RETURN VALUE    VALEUR RENVOYÉE [En général seulement sections 2, 3]
            ERRORS          ERREURS         [Typiquement uniquement sections 2, 3]
            ENVIRONMENT     ENVIRONNEMENT
            FILES           FICHIERS
            VERSIONS        VERSIONS        [En général seulement sections 2, 3]
            CONFORMING TO   CONFORMITÉ
            NOTES           NOTES
            BUGS            BOGUES
            EXAMPLE         EXEMPLE
            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 sections 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 des
       titres de sections traditionnels ne peut être utilisé, avec des sous‐sections (.SS).

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

       NAME (NOM)    Le nom de cette page. D'importants détails sur les lignes qui doivent suivre
                     la commande .SH NAME se trouvent dans la page man(7).

       SYNOPSIS      Indique brièvement l'interface de la commande ou de la  fonction.  Pour  les
                     commandes,  ce paragraphe montre sa syntaxe et ses arguments. Les caractères
                     gras marquent le  texte  invariable  et  l'italique  indique  les  arguments
                     remplaçables.  Les  crochets  « [] » encadrent les arguments optionnels, les
                     barres verticales « | » séparent les alternatives, et les  ellipses  « ... »
                     signalent  les  répétitions.  Pour  les  fonctions,  on  trouve  toutes  les
                     déclarations et 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   doit   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   Fournit une explication sur ce que la commande, la  fonction  ou  le  format
                     représente.  Décrit les interactions avec les fichiers et l'entrée standard,
                     ou ce qui est produit sur la sortie standard ou d'erreur.  Ne  contient  pas
                     les  détails  d'implémentation  internes,  sauf  s'ils  sont  critique  pour
                     comprendre l'interface. Décrit le cas principal, pour les  détails  sur  les
                     options, on utilise le paragraphe OPTIONS.

       OPTIONS       Décrit  les  options  acceptées  par  le programme et leur influence sur son
                     comportement. Cette section ne doit être utilisée  que  pour  les  pages  de
                     manuel des sections 1 et 8.

       EXIT STATUS (CODE DE RETOUR)
                     Indique  les  codes  de  retour  d'un programme et les conditions associées.
                     Cette section ne doit ê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, 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 partie contient une liste des
                     valeurs possibles de errno en cas d'erreur, avec la description  des  causes
                     de ces erreurs. La liste d'erreurs doit être triée par ordre alphabétique.

       ENVIRONMENT (ENVIRONNEMENT)
                     Décrit toutes les variables d'environnement qui affectent le programme ou la
                     fonction, ainsi que leurs effets.

       FILES (FICHIERS)
                     Liste les fichiers utilisés par  le  programme  ou  la  fonction,  tels  que
                     fichiers   de   configuration,  de  démarrage,  et  les  fichiers  manipulés
                     directement par le programme. Il faut donner le chemin d'accès  complet  des
                     fichiers  et  utiliser le mécanisme d'installation pour modifier le préfixe.
                     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.

       VERSIONS      Un 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 apparu, 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 lors qu'elles
                     ont été rédigées). Les correctifs pour y remédier sont les  bienvenus.  Dans
                     la  perpective 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 les 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.

       CONFORMING TO (CONFORMITÉ)
                     Décrit les normes ou conventions liées  à  la  fonction  ou  à  la  commande
                     décrite  par  la page de manuel. Pour une page dans la section 2 ou 3, cette
                     section doit indiquer la version de POSIX.1 à laquelle l'appel se  conforme,
                     et  s'il  est  spécifié  par  C99. (Il est inutile de trop se préoccuper des
                     autres normes comme SUS, SUSv2  ou  XPG,  ou  des  implémentations  SVr4  ou
                     BSD 4.x, sauf si la fonction était présente dans ces systèmes mais n'est pas
                     dans la version actuelle de POSIX.1, consultez standards(7).)

                     Si la fonction n'est gouvernée 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         Contient des 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).

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

       EXAMPLE (EXEMPLE)
                     Donne 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
                     programmes, consultez la section qui y est consacrée ci‐dessous.

       AUTHORS (AUTEURS)
                     Liste les auteurs de la documentation ou du programme.  L'utilisation  d'une
                     section  AUTHORS  est fortement découragée. En général, il vaut mieux ne pas
                     remplir  les  pages  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.

       SEE ALSO (VOIR AUSSI)
                     Fournit une liste des pages de manuel (séparées par des virgules)  ayant  un
                     rapport,  dans  l'ordre  des  sections puis alphabétique, suivies des autres
                     documents éventuels. Ne terminez pas la liste par un point.

   Conventions de fontes
       Pour les fonctions, les arguments  sont  toujours  indiqués  en  italique,  même  dans  le
       paragraphe SYNOPSIS, où le reste de la fonction est en caractères gras :

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

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

       Les noms de fichiers, que ce soit  des  chemins  ou  des  références  à  des  fichiers  du
       répertoire  /usr/include)  sont toujours en italique (par exemple <stdio.h>), sauf dans le
       paragraphe SYNOPSIS, où les fichiers inclus sont en gras (par exemple #include <stdio.h>).
       Lorsque  vous  faites  référence  à  un fichier d'entête standard situé dans /usr/include,
       spécifiez le fichier d'entête entouré avec les symboles inférieur et supérieur, de la même
       manière que dans un fichier source C (par exemple, <stdio.h>).

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

       Dans l'énumération d'une liste de code d'erreurs, les codes sont  en  gras,  et  la  liste
       utilise normalement la macro .TP.

       Les  commandes  complètes  devraient,  si  elles  sont  longues,  être  écrites sous forme
       indentée, 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, il peut être intéressant d'utiliser des espaces insécables
       (« \  ») aux endroits appropriés dans la commande. Les options des commandes doivent elles
       aussi être formatées en italique, par exemple, -l.

       Les expressions, si elles ne sont pas écrites sur une ligne 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.

       Toute  référence  au  sujet  de la page de manuel courante doit être écrite en gras. Si le
       sujet est une fonction (c'est‐à‐dire s'il s'agit d'une page de section 2  ou  3),  le  nom
       doit  être  suivi  d'une paire de parenthèses en caractères romans (normaux). Par exemple,
       dans la page fcntl(2), les références au sujet de la page sont écrites fcntl().  La  façon
       d'écrire ceci dans le fichier source est :

           .BR fcntl ()

       (avec ce format au lieu de « \fB...\fP() » le travail d'outils qui parsent les sources des
       pages de manuel est plus facile)

       Toute référence à une autre page de manuel, ou au sujet principal de la page en cours, est
       en  gras,  et  toujours  suivi  du  numéro  de section, en fonte normale, sans espace (par
       exemple intro(2)). Dans le source, on l'écrit habituellement de cette façon :

           .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 hypertexte appropriés)

   Orthographe
       À  partir  de  la  version 2.59,  la  version  anglaise  de man-pages suit les conventions
       orthographiques américaines ; veuillez écrire les  nouvelles  pages  et  les  rustines  en
       suivants ces conventions.

   Programmes d'exemples et sessions shell.
       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 noter ceci :

       *  Les programmes d'exemple doivent ê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 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 doivent être plutôt courts (de préférence moins de 100 lignes,
          idéalement moins de 50 lignes).

       *  Les  programmes  d'exemple doivent vérifier les erreurs après les appels système et les
          appels de fonctions de bibliothèque.

       *  Les programmes d'exemple doivent ê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 bien 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 4 espaces (évitez d'utiliser le caractère  tabulation
          dans les fichiers source !).

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

       Si vous incluez une session d'interpréteur de commandes pour démontrer l'utilisation  d'un
       programme  ou d'autres fonctionnalités système, mettez le texte entré par l'utilisateur en
       gras pour le distinguer de la sortie produite par le système.

   Indentation des définitions de structure, session shell, etc.
       Lorsque des définitions de structure, des sorties de session shell, etc. sont inclus  dans
       le texte courant, indentez-les avec 4 espaces (c'est-à-dire un bloc entouré par .in +4n et
       .in).

EXEMPLE

       Pour des exemples canoniques de pages de manuel  du  paquet  man-pages,  voir  pipe(2)  et
       fcntl(2).

VOIR AUSSI

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

COLOPHON

       Cette  page  fait partie de la publication 3.32 du projet man-pages Linux. Une description
       du projet et des  instructions  pour  signaler  des  anomalies  peuvent  être  trouvées  à
       l'adresse <URL:http://www.kernel.org/doc/man-pages/>.

TRADUCTION

       Depuis    2010,    cette   traduction   est   maintenue   à   l'aide   de   l'outil   po4a
       <URL:http://po4a.alioth.debian.org/> par l'équipe de traduction  francophone  au  sein  du
       projet perkamon <URL:http://perkamon.alioth.debian.org/>.

       Julien Cristau et l'équipe francophone de traduction de Debian (2006-2009).

       Veuillez     signaler     toute     erreur     de     traduction     en     écrivant     à
       <debian-l10n-french@lists.debian.org>  ou  par  un  rapport  de  bogue   sur   le   paquet
       manpages-fr.

       Vous  pouvez  toujours  avoir  accès  à la version anglaise de ce document en utilisant la
       commande « man -L C <section> <page_de_man> ».