Provided by: manpages-fr_1.67.0-1_all bug

NOM

       man - Macros pour la mise en forme des pages de manuel.

SYNOPSIS

       groff -Tascii -man fichier ...

       groff -Tps -man fichier ...

       man [section] titre

DESCRIPTION

       Cette  page  de  manuel  explique  le  contenu  du paquet groff tmac.an
       (souvent appelé paquet man).  Ce  paquet  doit  être  utilisé  par  les
       développeurs  pour écrire ou porter des pages de manuels pour Linux. Il
       est largement compatible avec d’autres versions de ce paquet,  donc  le
       portage  de  pages  pour  Linux ne devrait pas poser de problèmes (sauf
       pour NET-2 BSD qui utilise  un  paquet  complètement  différent  appelé
       mdoc, voir mdoc(7)).

       Notez  que  les pages de manuel NET-2 BSD peuvent être visualisées avec
       groff simplement en spécifiant l’option -mdoc à la  place  de  l’option
       -man.   L’utilisation  de  l’option  -mandoc  est néanmoins recommandée
       puisqu’il détectera automatiquement le paquet utilisé.

PRÉAMBULE

       La première commande d’une page de manuel doit être

              .TH titre section date source manuel,

       avec :

              titre   Le titre de la page de manuel (par exemple MAN).

              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.

              source  La source de la commande

                      Pour les exécutables, utilisez quelque chose comme  GNU,
                      NET-2, SLS Distribution, MCC Distribution.

                      Pour les appels-système, vous pouvez indiquer la version
                      du noyau que vous utilisez : Linux 2.4.19.

                      Pour les fonctions de bibliothèque, utilisez  la  source
                      de la fonction : GNU, BSD 4.3, Linux DLL 4.4.1.

              manuel  Le  titre  du  manuel (par exemple Manuel du programmeur
                      Linux).

       Notez que les pages BSD formatées avec mdoc commencent avec la commande
       Dd et non pas TH.

       Les sections du manuel sont traditionnellement réparties ainsi :

              1 Commandes
                        Les   commandes   qui   peuvent   être  invoquées  par
                        l’utilisateur depuis le shell.

              2 Appel systèmes
                        Les fonctions fournies par le noyau.

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

              4 Périphériques
                        Fichiers spéciaux trouvés dans

              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
                        Une description du système de fichiers standard, cette
                        page   de   manuel,  des  jeux  de  caractères,  entre
                        autres...

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

              9 Routines du noyau
                        Il  s’agit  d’une  section obsolète.  On a jadis pensé
                        qu’il serait bon de documenter  le  noyau  Linux  ici,
                        mais en fait très peu de documentation a été réaliséE,
                        et celle qui existe est déjà dépassée.  Il  existe  de
                        bien   meilleures   sources   d’information  pour  les
                        développeurs du noyau.

SECTIONS (PARAGRAPHES)

       Les sections commencent par .SH suivies de leurs titres.  Si  le  titre
       contient  des  espaces,  l’encadrer  par  des  guillemets.   Les titres
       traditionnels sont : NOM, SYNOPSIS, DESCRIPTION, VALEUR RENVOYÉE,  CODE
       DE   RETOUR,   ERREURS,   OPTIONS,   FICHIERS,   EXEMPLE,  VOIR  AUSSI,
       DIAGNOSTIQUE, BOGUES, ENVIRONNEMENT, SÉCURITÉ, CONFORMITÉ, AUTEUR, VOIR
       AUSSI,  et  TRADUCTION.   Utilisez  de  préférence ces titres s’il vous
       plaît ; cette cohérence  rend  les  pages  de  manuel  plus  faciles  à
       comprendre.  Maintenant,  créez  vos  propres titres si vous pensez que
       c’est nécessaire.  Le seul titre indispensable est NOM, qui  doit  être
       suivi sur la ligne suivante par une courte description du programme :

              .SH NOM
              chess \- Jeu d’échecs

       Il  est  très important que ce format soit respecté, et qu’il se trouve
       un backslash avant le  tiret  suivant  le  nom  du  programme.  Il  est
       important  que  toute  la  description soit placée sur une seule ligne.
       Cette syntaxe est utilisée par le programme makewhatis(8) pour créer la
       base  de  données  des  descriptions  pour  les  commandes whatis(1) et
       apropos(1).

       Ndt :  Vous  vous  doutez  bien  que  la  version  de  distribution  de
       makewhatis(8)  ne  reconnaît  pas  la  section  « NOM » mais la section
       « NAME ». Pour que les commandes whatis(1) et apropos(1)  fonctionnent,
       il  faut  modifier le script makewhatis(8).  La modification à apporter
       est décrite dans le fichier LISEZ_MOI, qui est livré avec l’archive des
       pages de manuel en français.

       Les autres sections contiennent habituellement les éléments suivants :

       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.

       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.  S’il y a une sorte de grammaire
                     d’entrée, ou un jeu de sous-commandes, on peut les placer
                     dans  un  paragraphe  UTILISATION  supplémentaire  (juste
                     après la section DESCRIPTION).

       VALEUR RENVOYÉE
                     donne  une  liste   des   valeurs   qu’une   routine   de
                     bibliothèque  renverra à l’appelant et les conditions qui
                     provoquent ces retours.

       CODE DE RETOUR
                     indique  les  codes  de  retour  d’un  programme  et  les
                     conditions associées.

       OPTIONS       décrit  les options acceptées par le programme et comment
                     son comportement se modifie.

       UITILISATION  décrit la grammaire de tout sous-langage implémenté.

       EXEMPLES      donne  un  ou  plusieurs  exemples  d’utilisation  de  la
                     fonction, du fichier ou de la commande.

       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.

       ENVIRONNEMENT décrit toutes les variables d’environnement qui affectent
                     le programme ou la fonction, ainsi que leurs effets.

       DIAGNOSTIQUE  fournit  un  survol  des  messages  d’erreurs  usuels  et
                     comment   les   considérer.    Il  n’est  pas  nécessaire
                     d’indiquer les messages d’erreur système ou  les  signaux
                     fatals  qui  peuvent  apparaître  durant  l’exécution  du
                     programme, sauf s’ils sont traités spécialement.

       SECURITÉ      concerne les problèmes de sécurité et leurs implications.
                     Doit   contenir   les   avertissements   à   propos   des
                     configurations  ou  des  environnements  à  éviter,   les
                     commandes  ayant  des  répercussions  au niveau sécurité,
                     etc. surtout s’ils ne sont pas évidents.   Il  n’est  pas
                     obligatoire  de  faire  un  paragraphe  spécifique sur la
                     sécurité. Si l’intelligibilité  est  améliorée,  on  peut
                     placer  ces informations dans les autres sections (telles
                     que DESCRIPTION ou  UTILISATION  ).   Néanmoins,  il  est
                     important  de placer les informations de sécurité quelque
                     part.

       CONFORMITÉ    décrit  les  standards  ou  les  conventions  suivis  par
                     l’implémentation.

       NOTES         contient des notes diverses.

       BOGUES        liste  les limitations ou les défauts recensés, ainsi que
                     les sujets à débat.

       AUTEUR        liste les auteurs de la  documentation  ou  du  programme
                     afin de pouvoir leur envoyer les rapports de bogue.

       VOIR AUSSI    fournit  une  liste des pages de manuel ayany un rapport,
                     dans l’ordre alphabétiques, suivies des autres  documents
                     éventuels.

       TRADUCTION    le  nom  du  traducteur.  Si  son  adresse mail n’est pas
                     fournie, vous la  trouverez  dans  le  fichier  LISEZ_MOI
                     fournit  avec  les  pages  de  manuel  en  français.   Le
                     paragraphe "TRADUCTION" n’est pas destiné à flatter l’ego
                     du  traducteur,  mais  à  savoir à qui s’adresser si vous
                     relevez une erreur !

FONTES

       Bien qu’il y ait de nombreuses conventions arbitraires  concernant  les
       pages  de manuel pour UNIX, l’existence de plusieurs centaines de pages
       spécifiques à Linux définit nos propres standards :

              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 mafonction(int argc, char **argv);

              Les noms de fichiers sont  toujours  en  italique  (par  exemple
              /usr/include/stdio.h),  sauf dans le paragraphe SYNOPSIS, où les
              fichiers inclus sont en gras (par exemple #include <stdio.h>).

              Les macros,  généralement  en  majuscules,  sont  en  gras  (par
              exemple MAXINT).

              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  à  une  autre  page  de  manuel,  ou  au  sujet
              principal  de  la  page  en  cours, est en gras. Si le numéro de
              section de manuel est donné, il est en Roman, sans  espace  (par
              exemple man(7)).

              Les commandes pour sélectionner les fontes sont les suivantes :

       .B  Gras

       .BI Gras  alterné  avec  Italique  (surtout  pour les spécifications de
           fonctions)

       .BR Gras alterné avec Roman (surtout pour  les  références  aux  autres
           pages de manuel)

       .I  Italique

       .IB Italique alterné avec Gras

       .IR Italique alterné avec Roman

       .RB Roman alterné avec Gras

       .RI Roman alterné avec Italique

       .SB Petit et Gras

       .SM Petit (utile pour les acronymes)

       Traditionnellement,  chaque  commande peut avoir jusqu’à six arguments,
       mais  les  versions  GNU  semblent  éliminer  cette  contrainte.    Les
       arguments  sont délimités par des espaces. Des guillemets sont utilisés
       pour encadrer un argument qui contient des espaces.  Tous les arguments
       seront  imprimés  les  uns  après  les autres sans intercaler d’espace,
       ainsi la commande .BR peut être utilisée pour indiquer un mot  en  Gras
       suivi  par  un  signe de ponctuation en Roman.  Si aucun argument n’est
       fourni, la commande s’applique à la ligne suivante.

AUTRES MACROS ET CHAÎNES

       Ci-dessous  se  trouvent  les  macros  et  chaînes  prédéfinies.   Sauf
       indication  contraire,  toutes les macros déclenchent un saut de ligne.
       La plupart de ces macros utilisent ou modifient l’indentation courante.
       Celle-ci est fixée par toute macro avec le paramètre i ci-dessous ; les
       macros peuvent omettre le  i  auquel  cas  l’indentation  courante  est
       utilisée.   En  conséquence, les paragraphes sucessifs peuvent utiliser
       la même indentation  sans  la  répéter.   Un  paragraphe  normal,  non-
       indenté,  replace  l’indentation  courante  à sa valeur par défaut (0.5
       pouces).  Par défaut, les indentations sont mesurées  en  ens  (largeur
       d’une  lettre  « n »")  ou  ems (« m »). Ainsi, les largeurs s’ajustent
       automatiquement en cas de changement de police.  Les principales macros
       disponibles sont :

   Paragraphes normaux
       .LP      Comme .PP (débute un nouveau paragraphe).

       .P       Comme .PP (débute un nouveau paragraphe).

       .PP      Débute  un  nouveau  paragraphe  et réinitialise l’indentation
                courante.

   Indentation Relative
       .RS i    Débute une indentation relative - déplace la marge gauche de i
                vers  la  droite  (si  i  est  absent, la valeur d’indentation
                courante est utilisée).  Une nouvelle valeur d’indentation est
                placée  à  0.5  pouces.   En conséquence, tous les paragraphes
                suivants seront indentés jusqu’au RE correspondant.

       .RE      Terminer une indentation relative  et  restituer  les  valeurs
                précédentes d’indentation courante.

   Macros dindentation de paragraphe
       .HP i    Débute  un  paragraphe  avec  une  indentation  d’accroche (la
                première ligne du paragraphe est le long de la  marge  gauche,
                et les autres lignes sont indentées).

       .IP x i  Paragraphe  indenté avec une balise d’accroche éventuelle.  Si
                la balise x est omise, tout le paragraphe est  indenté  de  i.
                Si  la  balise x est fournie, elle est accrochée le long de la
                marge gauche, avant le paragraphe  indenté  (C’est  comme  .TP
                sauf  que  la  balise  est  incluse avec la commande elle-même
                plutôt que d’être sur la ligne suivante).  Si  la  balise  est
                trop  longue,  le texte sera transposé à la ligne suivante (le
                texte ne sera ni perdu ni tronqué).  Pour les listes à  puces,
                utilisez  cette  macro  avec \(bu (rond) ou \(em (tiret) comme
                balise, et pour les listes numérotées utilisez le numéro ou la
                lettre  suivi  par un point. Ceci simplifie la traduction dans
                d’autres formats.

       .TP i    Début d’un paragraphe avec une balise  d’accroche.  La  balise
                est  donnée  sur  la  ligne  suivante,  mais  le  résultat est
                identique à celui de la commande .IP.

   Macros de liens hypertextes
       Afin d’utiliser les liens hypertextes, il est nécessaire de charger  le
       paquetage de macros www.tmac, avec l’aide de la commande .mso www.tmac.

       .URL url lien suite
                Insère un lien hypertexte vers l’URI (URL) url, où lien est le
                texte  du  lien.  La  suite sera affichée immédiatement après.
                Lors d’une  conversion  en  HTML,  cela  se  traduit  par  les
                commandes HTML <A HREF="url">lien</A>suite.

                Ces  macros (et d’autres s’y rapportant) sont nouvelles, et de
                nombreux outils n’en feront  rien.  Mais,  comme  de  nombreux
                outils (y compris troff) les ignoreront simplement (ou au pire
                écriront leur texte), on peut les utiliser sans souci.

       Un certain nombre d’autres macros  sont  disponibles  pour  des  liens,
       veuillez consulter groff_www(7) pour plus d’informations.

   Macros diverses
       .DT      Réinitialiser les tabulations à leurs valeurs par défaut, tous
                les 0.5 pouces sans déclencher de saut de ligne.

       .PD d    Fixer la distance verticale entre paragraphes à  la  valeur  d
                (si absent, d=0.4v).  Ne provoque pas de saut de ligne.

       .SS t    Sous-chapitre  t  (comme  .SH,  mais pour les sous-sections au
                sein d’une section).

   Chaînes prédéfinies
       Le paquet man contient les chaînes prédéfinies suivantes :

       \*R    Symbole d’enregistrement : ®

       \*S    Taille de police par défaut.

       \*(Tm  Symbole marque déposée : ™

       \*(lq  Guillemets en chevrons droits : “

       \*(rq  Guillemets en chevrons gauches : ”

Ensemble de commandes sûres

       Bien que techniquement man  soit  un  paquetage  de  macros  troff,  en
       réalité un grand nombre d’autres outils traitent les fichiers des pages
       de manuel, sans implémenter toutes les possibilités de troff.  Il  vaut
       donc mieux éviter certaines fonctionnalités exotiques de troff.  Évitez
       d’utiliser les préprocesseurs de troff (s’il le faut, utilisez  tbl(1),
       mais essayez d’employer plutôt les commandes IP et TP pour les tableaux
       à deux colonnes).  Évitez d’utiliser les calculs, la plupart des autres
       outils  ne  les  réalisent pas. Utilisez des commandes simples facile à
       traduire dans d’autres formats.  Les macros  suivantes  sont  reconnues
       comme  sûres (même si elles sont parfois ignorés par les traducteurs) :
       \", ., ad, bp, br, ce, de, ds, el, ie, if, fi, ft, hy, ig, in, na,  ne,
       nf, nh, ps, so, sp, ti, tr.

       Vous pouvez aussi employer les séquences d’échappement de troff (celles
       qui commencent par \).  Si vous devez insérer  un  backslash  comme  du
       texte  normal,  utilisez  \e.   Les  autres  séquences  que vous pouvez
       utiliser, x et xx étant des caractères quelconques, et  N  un  chiffre,
       sont :  \’, \‘, \-, \., \", \%, \*x, \*(xx, \(xx, \$N, \nx, \n(xx, \fx,
       et \f(xx.  Évitez d’utiliser des séquences d’échappement pour  dessiner
       des graphiques.

       N’utilisez   pas  les  paramètres  optionnels  pour  bp  (break  page).
       Utilisez seulement des valeurs positives pour sp (vertical space).   Ne
       définissez  pas  de  macro  (de)  avec le même nom qu’une macro dans ce
       paquetage ou dans celui de mdoc avec une signification  différente,  il
       est  probable  que  la  définition en serait ignorée.  Tout indentation
       positive (in) devrait  être  appariée  avec  une  indentation  négative
       identique  (bien que vous devriez plutôt utiliser les macros RS et RE à
       la place).  Les tests (if,ie) ne devraient avoir  que  « t »  ou  « n »
       comme condition.  Seules les traductions (tr) qui peuvent être ignorées
       devraient  être  utilisées.   Les  changement  de  fontes  (ft  et  les
       séquences  d’échappement \f) ne doivent prendre comme valeurs que 1, 2,
       3, 4, R, I, B, P, ou CW  (la  commande  ft  peut  aussi  n’avoir  aucun
       paramètre).

       Si  vous  utilisez  d’autres fonctionnalités que celles-ci, vérifiez le
       résultat soigneusement sur divers  outils.   Une  fois  que  vous  avez
       confirmation  que la nouvelle fonctionnalité est sûre, faites-le savoir
       au mainteneur de cette page.

NOTES

       Insérez les URLs complets dans le texte lui-même, certains outils comme
       man2html(1)   peuvent   les   transformer   automatiquement   en  liens
       hypertextes.  Vous pouvez aussi utiliser la  nouvelle  macro  URL  pour
       associer  les  liens aux informations correspondantes.  Si vous insérer
       des    URLs,    utilisez    des    URL    complets     (par     exemple
       <http://www.kernelnotes.org>)   pour   s’assurer  que  les  outils  les
       trouveront automatiquement.

       Les outils traitant ces fichiers devront  les  ouvrir  et  examiner  le
       premier  caractère non-blanc. Un point ou un apostrophe simple au début
       d’une ligne indiquent un fichier troff (comme man ou mdoc).   Un  angle
       gauche  (<) indique un document SGML/XML comme (HTML ou Docbook).  Tout
       autre caractère correspond à un texte ASCII  simple  (par  exemple  une
       sortie « catman »).

       Plusieurs  pages  commencent avec ’\" suivi d’une espace et d’une liste
       de caractères indiquant comment la page doit  être  pré-traitée.   Pour
       améliorer  la  portabilité  vers  des  traducteurs non-troff, nous vous
       recommandons d’éviter d’utiliser autre chose que tbl(1).   Sous  Linux,
       la  détection en est automatique.  Nénamoins, vous pouvez inclure cette
       information pour que votre page  de  manuel  puisse  être  traitée  par
       d’autres   systèmes   (moins   capables).    Voici  la  définition  des
       préprocesseurs invoqués par ces caractères :

       e  eqn(1)

       g  grap(1)

       p  pic(1)

       r  refer(1)

       t  tbl(1)

       v  vgrind(1)

       [Ndt]  En  français,  nous  utilisons  plus  fréquement  les  « espaces
       insécables » que les anglo-saxons. Pour transformer un espace normal en
       espace insécable, il suffit de le préfixer par « \ ». Si vous traduisez
       des  pages,  essayez de placer ces espaces insécables avant les points-
       virgules, deux-points, point d’exclamation et d’interrogation, et entre
       les nombres et les unités (par exemple 1024 ko, s’écrira 1024\ ko).

FICHIERS

       /usr/share/groff/ [*/] tmac/tmac.an
       /usr/man/whatis

BOGUES

       La   plupart   des   macros   décrivent   la  mise  en  forme  (police,
       espacement...) au lieu de marquer le contenu  sémantique  (par  exemple
       référence  vers une autre page) comme le font des formats comme mdoc ou
       DocBook (même l’HTML a des balises plus sémantiques).  Cette  situation
       rend le format man difficile à traduire sur différents supports.  En se
       limitant au sous-ensemble de macros décrites plus haut, il devrait être
       plus facile de basculer automatiquement vers un autre format de page de
       référence dans l’avenir.

       La macro Sun TX n’est pas implémentée.

AUTEURS

       —  James Clark (jjc@jclark.com) a écrit l’implémentation  du  paquetage
          de macros.

       —  Rickard  E.  Faith (faith@cs.unc.edu) a écrit la version initiale de
          cette page de manuel.

       —  Jens Schweikhardt (schweikh@noc.fdn.de) a écrit le mini HOWTO Linux-
          man-page.  (qui a influencé cette page de manuel).

       —  David  A. Wheeler (dwheeler@ida.org) a largement modifié cette page,
          en ajoutant des détails sur les sections et les macros.

VOIR AUSSI

       apropos(1), groff(1), man(1),  man2html(1),  mdoc(7),  mdoc.samples(7),
       groff_www(7), whatis(1)

TRADUCTION

       Christophe Blaess, 1996-2003.