Loading

NOM

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

SYNOPSIS

       man [section] titre

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

                     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 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 (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
       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 dexemples 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,  voyez
       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.23 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> ».