Provided by: manpages-fr_3.32d0.2p4-1_all bug

NOM

       man-pages - Conventions pour l'ecriture des pages de manuel Linux

SYNOPSIS

       man [section] titre

DESCRIPTION

       Cette page decrit les conventions utilisees 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 decrites sur
       cette page peuvent aussi etre 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 etre invoquees par l'utilisateur
                 depuis un interpreteur de commandes.

       2 Appels syst`eme
                 Les fonctions fournies par le noyau.

       3 Fonctions de biblioth`eques
                 La plupart des fonctions de la bibliotheque C (libc).

       4 Fichiers sp'eciaux (p'eriph'eriques)
                 Fichiers speciaux trouves 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 caracteres, et diverses autres choses.

       8 Commandes d'administration syst`eme
                 Les commandes comme mount(8), que seul root peut executer.

   Paquet de macros
       Les nouvelles pages de manuel doivent etre mises en forme en  utilisant
       le paquet groff an.tmac decrit dans man(7). Ce choix est principalement
       destine a assurer une coherence : la plupart des pages de manuel  Linux
       sont mises en forme avec ces macros.

   Conventions pour l'agencement des sources
       Veuillez  limiter  la  longueur  des lignes dans le source a environ 75
       caracteres, autant que faire se peut. Cela permet d'eviter les  retours
       a  la  ligne  ajoutes  par les clients de 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 premiere commande d'une page de manuel doit etre une commande TH

              .TH titre section date source manuel,

       ou :

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

              section   Le numero de section dans laquelle placer la page (par
                        exemple 7).

              date      La date de la derniere modification. Pensez a modifier
                        cette date a chaque changement dans la page, car c'est
                        la maniere la plus courante  d'avoir  un  controle  de
                        version.   Les   dates   doivent   etre  de  la  forme
                        AAAA-MM-JJ.

              source    La source de la  commande,  fonction,  ou  de  l'appel
                        systeme.

                        Pour   les   quelques  pages  de  man-pages  dans  les
                        sections 1 et 8, il est conseille d'ecrire GNU.

                        Pour les appels  systeme,  ecrivez  simplement  Linux.
                        Precedemment,  il  etait  courant  d'ecrire  aussi  le
                        numero de version du noyau pour laquelle  la  page  de
                        manuel  etait ecrite. Cependant, cela n'etait pas fait
                        de  facon  systematique,  et  etait  donc   pire   que
                        d'omettre  simplement  le numero de version. N'incluez
                        donc pas de numero de version.

                        Pour les fonctions de  bibliotheque  de  glibc  ou  de
                        l'une  des bibliotheques GNU standards, utilisez GNU C
                        Library, GNU, ou une chaine vide.

                        Pour les pages de la section 4, utilisez Linux.

                        En cas d'hesitation, ecrivez 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  suggerees.  La
       plupart  des  pages  devraient  contenir au moins les sections mises en
       'evidence. Dans les nouvelles pages de manuel, placez les sections  dans
       l'ordre indique dans la liste.

            Nom anglais     Nom francais    Notes
            NAME            NOM
            SYNOPSIS        SYNOPSIS
            CONFIGURATION   CONFIGURATION   [En general seulement section 4]
            DESCRIPTION     DESCRIPTION
            OPTIONS         OPTIONS         [En general seulement sections 1, 8]
            EXIT STATUS     CODE DE RETOUR  [En general seulement sections 1, 8]
            RETURN VALUE    VALEUR RENVOYEE [En general seulement sections 2, 3]
            ERRORS          ERREURS         [Typiquement uniquement sections 2, 3]
            ENVIRONMENT     ENVIRONNEMENT
            FILES           FICHIERS
            VERSIONS        VERSIONS        [En general seulement sections 2, 3]
            CONFORMING TO   CONFORMITE
            NOTES           NOTES
            BUGS            BOGUES
            EXAMPLE         EXEMPLE
            SEE ALSO        VOIR AUSSI

       Lorsque  l'une  des  sections traditionnelles s'applique, utilisez-la ;
       cette coherence rend l'information plus facile a  comprendre.  Si  cela
       est  necessaire,  vous  pouvez  creer vos propres titres de sections si
       cela rend les choses plus comprehensibles  (particulierement  pour  les
       pages  des  sections 4  et 5). Cependant, avant de faire cela, verifiez
       qu'aucun des titres de sections traditionnels  ne  peut  etre  utilise,
       avec des sous-sections (.SS).

       La liste suivante decrit le contenu de chacune des sections ci-dessus.

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

       SYNOPSIS      Indique  brievement  l'interface  de la commande ou de la
                     fonction. Pour les commandes,  ce  paragraphe  montre  sa
                     syntaxe et ses arguments. Les caracteres gras marquent le
                     texte invariable  et  l'italique  indique  les  arguments
                     remplacables.   Les   crochets   << [] >>  encadrent  les
                     arguments  optionnels,  les  barres  verticales   << | >>
                     separent  les  alternatives,  et  les  ellipses << ... >>
                     signalent les repetitions. Pour les fonctions, on  trouve
                     toutes  les  declarations et directives #include, suivies
                     de la declaration de fonction.

                     Si une macro de test de fonctionnalite doit etre  definie
                     pour  obtenir  la  declaration  d'une  fonction (ou d'une
                     variable) dans un fichier  d'en-tete,  alors  la  section
                     SYNOPSIS    doit    l'indiquer,    comme    decrit   dans
                     feature_test_macros(7).

       CONFIGURATION Details de  configuration  pour  un  peripherique.  Cette
                     section est presente normalement que dans les pages de la
                     section 4.

       DESCRIPTION   Fournit une  explication  sur  ce  que  la  commande,  la
                     fonction ou le format represente. Decrit les interactions
                     avec les fichiers et l'entree standard,  ou  ce  qui  est
                     produit  sur  la sortie standard ou d'erreur. Ne contient
                     pas les details  d'implementation  internes,  sauf  s'ils
                     sont  critique pour comprendre l'interface. Decrit le cas
                     principal, pour les details sur les options,  on  utilise
                     le paragraphe OPTIONS.

       OPTIONS       Decrit  les  options  acceptees  par le programme et leur
                     influence sur son comportement.  Cette  section  ne  doit
                     etre utilisee 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 associees. Cette section ne doit etre utilisee
                     que pour les pages de manuel des sections 1 et 8.

       RETURN VALUE (VALEUR RENVOY'EE)
                     Pour les pages des sections 2 et 3, donne une  liste  des
                     valeurs   qu'une   routine  de  bibliotheque  renverra  a
                     l'appelant et les conditions qui provoquent ces retours.

       ERRORS (ERREURS)
                     Pour les pages des sections 2 et 3, cette 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 ^etre tri'ee par ordre alphab'etique.

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

       FILES (FICHIERS)
                     Liste les  fichiers  utilises  par  le  programme  ou  la
                     fonction,   tels   que   fichiers  de  configuration,  de
                     demarrage, et les fichiers manipules directement  par  le
                     programme.  Il  faut donner le chemin d'acces complet des
                     fichiers et utiliser  le  mecanisme  d'installation  pour
                     modifier  le  prefixe.  Pour  la  plupart des programmes,
                     l'installation par defaut se fait dans /usr/local, aussi,
                     votre  page de manuel de base devrait utiliser /usr/local
                     comme base.

       VERSIONS      Un court resume de la version du noyau  Linux  ou  de  la
                     glibc  ou  l'appel systeme ou la fonction de bibliotheque
                     est apparu, ou dont  le  fonctionnement  est  modifie  de
                     maniere  significative.  De  maniere generale, 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 ete redigees). Les correctifs pour  y  remedier  sont
                     les  bienvenus.  Dans la perpective d'ecriture de nouveau
                     code, cette information n'a  de  sens  que  dans  le  cas
                     d'interface   noyau   ajoutee   a  Linux 2.4  ou  suivant
                     (c'est-a-dire les modifications depuis la version 2.2  du
                     noyau), et les fonctions de la bibliotheque ajoutees dans
                     glibc   depuis   la   version 2.1    (c'est-a-dire    les
                     modifications depuis la version 2.0 de la glibc).

                     La  page  de  manuel  syscalls(2)  fournit  egalement des
                     informations de versions de noyau  dans  lesquelles  sont
                     apparus les appels systeme.

       CONFORMING TO (CONFORMIT'E)
                     Decrit les normes ou conventions liees a la fonction ou a
                     la commande decrite par la page de manuel. Pour une  page
                     dans  la  section 2  ou 3, cette section doit indiquer la
                     version de POSIX.1 a laquelle  l'appel  se  conforme,  et
                     s'il  est  specifie  par  C99. (Il est inutile de trop se
                     preoccuper des autres normes comme SUS, SUSv2 ou XPG,  ou
                     des  implementations SVr4 ou BSD 4.x, sauf si la fonction
                     etait presente dans ces systemes mais n'est pas  dans  la
                     version actuelle de POSIX.1, consultez standards(7).)

                     Si  la  fonction  n'est  gouvernee par aucune norme, mais
                     existe sur d'autres systemes, mentionnez-les. Si elle est
                     specifique a 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 etre utile d'utiliser des  sous-
                     sections  (SS)  appelees Linux Notes (Notes sur Linux) ou
                     Glibc Notes (Notes sur la glibc).

       BUGS (BOGUES) Liste les limitations ou les defauts recenses, ainsi  que
                     les sujets a debat.

       EXAMPLE (EXEMPLE)
                     Donne  un  ou  plusieurs  exemples  d'utilisation  de  la
                     fonction, du fichier ou de  la  commande.  Pour  plus  de
                     details   sur   l'ecriture   d'exemples   de  programmes,
                     consultez la section qui y est consacree ci-dessous.

       AUTHORS (AUTEURS)
                     Liste les auteurs de la documentation  ou  du  programme.
                     L'utilisation   d'une   section   AUTHORS  est  fortement
                     d'ecourag'ee. En general, il vaut mieux ne pas remplir  les
                     pages  de  manuel avec une liste (potentiellement longue)
                     d'auteurs ;  si  vous  ecrivez  ou  modifiez   de   facon
                     importante  une  page, ajoutez une notice de copyright en
                     commentaire dans le fichier source. Si vous etes l'auteur
                     d'un pilote de peripherique et voulez inclure une adresse
                     pour signaler les bogues, placez-la dans la section BUGS.

       SEE ALSO (VOIR AUSSI)
                     Fournit une liste des pages de manuel (separees  par  des
                     virgules)  ayant  un  rapport,  dans l'ordre des sections
                     puis   alphabetique,   suivies   des   autres   documents
                     eventuels. Ne terminez pas la liste par un point.

   Conventions de fontes
       Pour  les  fonctions, les arguments sont toujours indiques en italique,
       m^eme dans le paragraphe SYNOPSIS, ou le reste de  la  fonction  est  en
       caracteres gras :

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

       Les  noms  de  variables  devraient, tout comme les noms de parametres,
       etre formates en italique.

       Les noms de fichiers, que ce soit des chemins ou des references  a  des
       fichiers  du  repertoire  /usr/include)  sont toujours en italique (par
       exemple <stdio.h>), sauf dans le paragraphe SYNOPSIS, ou  les  fichiers
       inclus  sont  en  gras  (par  exemple #include <stdio.h>). Lorsque vous
       faites  reference  a  un   fichier   d'entete   standard   situe   dans
       /usr/include,  specifiez  le fichier d'entete entoure avec les symboles
       inferieur et superieur, de la meme maniere que dans un fichier source C
       (par exemple, <stdio.h>).

       Les  macros,  generalement  en  majuscules,  sont  en gras (par exemple
       MAXINT). Exception : NULL ne doit pas etre en gras.

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

       Les  commandes completes devraient, si elles sont longues, etre ecrites
       sous forme indentee, par exemple

           man 7 man-pages

       Si la commande est courte, elle peut etre incluse  dans  le  texte,  en
       italique,  par  exemple,  man  7  man-pages.  Dans ce cas, il peut etre
       interessant d'utiliser des espaces insecables (<< \  >>)  aux  endroits
       appropries  dans  la  commande. Les options des commandes doivent elles
       aussi etre formatees en italique, par exemple, -l.

       Les expressions, si elles ne sont pas ecrites sur une  ligne  indentee,
       devraient  etre  mises  en italique. Ici aussi, l'utilisation d'espaces
       insecables est appropriee si  l'expression  est  melangee  a  du  texte
       normal.

       Toute reference au sujet de la page de manuel courante doit etre ecrite
       en gras. Si le sujet est une fonction (c'est-a-dire s'il  s'agit  d'une
       page  de  section 2  ou  3),  le  nom  doit  etre  suivi d'une paire de
       parentheses en caracteres romans (normaux). Par exemple, dans  la  page
       fcntl(2),  les  references au sujet de la page sont ecrites fcntl(). La
       facon d'ecrire 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 reference a une autre page de manuel, ou au sujet principal de la
       page en cours, est en gras, et toujours suivi du numero de section,  en
       fonte  normale,  sans espace (par exemple intro(2)). Dans le source, on
       l'ecrit habituellement de cette facon :

           .BR intro (2)

       (inclure le numero de section dans les references croisees permet a des
       outils comme man2html(1) de creer des liens hypertexte appropries)

   Orthographe
       A  partir de la version 2.59, la version anglaise de man-pages suit les
       conventions orthographiques americaines ; veuillez ecrire 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  systeme  ou  une   fonction   de
       bibliotheque. Cependant, veuillez noter ceci :

       *  Les programmes d'exemple doivent etre ecrits en C.

       *  Un  programme  d'exemple  n'est  necessaire et utile que s'il montre
          quelque chose qui ne  peut  pas  etre  fourni  facilement  dans  une
          description  de  l'interface.  Un  programme  d'exemple  qui ne fait
          qu'appeler une fonction ne sert en general a rien.

       *  Les programmes d'exemple doivent etre plutot courts  (de  preference
          moins de 100 lignes, idealement moins de 50 lignes).

       *  Les  programmes  d'exemple  doivent  verifier  les erreurs apres les
          appels systeme et les appels de fonctions de bibliotheque.

       *  Les programmes d'exemple doivent  etre  complets  et  compiler  sans
          avertissements avec cc -Wall.

       *  Si  possible  et  raisonnable,  les  programmes  d'exemples  doivent
          permettre d'experimenter, en changeant de comportement  en  fonction
          des  entrees  (arguments  de ligne de commande, ou bien entrees lues
          par le programme).

       *  Les programmes d'exemple doivent etre mis en forme dans le style  de
          Kernighan  et  Ritchie,  avec  des indentations de 4 espaces (evitez
          d'utiliser le caractere tabulation dans les fichiers source !).

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

       Si  vous incluez une session d'interpreteur de commandes pour demontrer
       l'utilisation  d'un  programme  ou  d'autres  fonctionnalites  systeme,
       mettez  le  texte entre par l'utilisateur en gras pour le distinguer de
       la sortie produite par le systeme.

   Indentation des d'efinitions de structure, session shell, etc.
       Lorsque des definitions de structure, des  sorties  de  session  shell,
       etc.  sont  inclus  dans  le texte courant, indentez-les avec 4 espaces
       (c'est-a-dire un bloc entoure 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       etre       trouvees      a      l'adresse
       <URL:http://www.kernel.org/doc/man-pages/>.

TRADUCTION

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

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

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

       Vous pouvez toujours avoir acces a la version anglaise de  ce  document
       en utilisant la commande << man -L C <section> <page_de_man> >>.