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 trie par ordre alphabtique.

       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,
       mme 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> ».