Provided by: manpages-fr_2.80.1-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 dadministration 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 lagencement 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èmes,  é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 standard, 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  Programmers
                        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.

            NAME
            SYNOPSIS
            CONFIGURATION   [En général seulement section 4]
            DESCRIPTION
            OPTIONS            [En général seulement sections 1, 8]
            EXIT STATUS        [En général seulement sections 1, 8]
            RETURN VALUE       [En général seulement sections 2, 3]
            ERRORS             [Typiquement uniquement sections 2, 3]
            ENVIRONMENT
            FILES
            VERSIONS           [En général seulement sections 2, 3]
            CONFORMING TO
            NOTES
            BUGS
            EXAMPLE
            SEE ALSO

       Lorsque  lune  des  sections traditionnelles sapplique, 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          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        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
                     derreurs 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 bref résumé des versions de Linux ou de la glibc où un
                     appel  système  est apparu, ou a changé significativement
                     de comportement.

       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. (Voir standards(7).)

                     Si la fonction n’est gouvernée par aucun  standard,  mais
                     existe sur d’autres systèmes, mentionnez‐les. Si elle est
                     spécifique à Linux, notez‐le.

       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 ou Glibc Notes.

       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, voir la
                     section qui y est consacrée ci‐dessous.

       AUTHORS (AUTEURS)
                     Liste les auteurs de la documentation  ou  du  programme.
                     Lutilisation   dune   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 ayant un rapport,
                     dans l’ordre des sections puis alphabétique, suivies  des
                     autres documents éventuels.

   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 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  <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.

       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
       A 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 dexemple
       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 <
          100 lignes, idéalement < 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, voyez
       wait(2) et pipe(2).

   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 2.80 du projet man-pages
       Linux. Une description du projet et des instructions pour signaler  des
       anomalies       peuvent       être       trouvées      à      l’adresse
       http://www.kernel.org/doc/man-pages/.

TRADUCTION

       Cette page de manuel a été traduite et est maintenue par Julien Cristau
       <julien.cristau@ens-lyon.org>  et l’équipe francophone de traduction de
       Debian.

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