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 an.tmac (souvent appelé paquet de
       macros man). Ce paquet doit être utilisé par les développeurs pour écrire  ou  porter  des
       pages de manuels. 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 paquetage complètement différent appelé mdoc, consultez 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 paquetage utilisé.

       Les  conventions  utilisées  pour  les pages de manuel du paquet man-pages pour Linux sont
       décrites dans man-pages(7).

   Ligne de titre
       La première commande d'une page de manuel (après des lignes de commentaire, qui commencent
       par .\") doit être

              .TH titre section date source manuel,

       Les détails des arguments passés à la commande TH sont décrits dans man-pages(7).

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

   Sections
       Les sections commencent par .SH suivi du titre de section.

       La  seule section obligatoire est NAME (NOM), qui doit être la première section et dont la
       ligne suivant le titre doit être une description courte du programme :

              .SH NAME
              objet \- description

       Ce format doit absolument être respecté, et le tiret suivant le nom de l'objet  doit  être
       précédé  d'une  barre  oblique  inversée.  Toute la description doit être contenue sur une
       seule ligne. Cette syntaxe est utilisée par le programme mandb(8) pour créer  la  base  de
       données  des  descriptions  courtes  pour les commandes whatis(1) et apropos(1) (consultez
       lexgrog(1) pour de plus amples précisions sur la syntaxe de la section NAME).

       Pour une liste des autres sections pouvant apparaître dans une page de  manuel,  consultez
       man-pages(7).

   Polices
       Les commandes pour sélectionner les polices sont les suivantes.

       .B  Gras.

       .BI Gras alterné avec italique (très utile pour les spécifications de fonctions).

       .BR Gras alterné avec romain (très utile pour les références aux autres pages de manuel).

       .I  Italique.

       .IB Italique alterné avec gras.

       .IR Italique alterné avec romain.

       .RB Romain alterné avec gras.

       .RI Romain alterné avec italique.

       .SB Petit alterné avec gras.

       .SM Petit (utile pour les acronymes).

       Traditionnellement,  chaque  commande  peut avoir jusqu'à six arguments, mais les versions
       GNU  semblent  éliminer  cette  contrainte  (vous  préférerez  sûrement  vous  limiter   à
       6 arguments  pour  des  raisons  de  portabilité).  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  romain.  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 définie 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 suivants 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 d'indentation 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.
                Cela 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
       (Fonctionnalité prise en charge par groff seulement.) Afin d'utiliser les macros de  liens
       hypertexte,  il  est  nécessaire  de charger le paquet macro www.tmac. Utiliser la requète
       .mso www.tmac pour le faire.

       .URL url lien fin
                Insère un lien hypertexte vers l'URI (URL) url, avec lien comme texte du lien. La
                fin  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>fin.

                Les macros d'insertion de liens hypertextes 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), elles peuvent  être  utilisées  sans
                souci.

                Il  peut  être  utile de définir votre propre macro URL dans les pages de manuels
                pour le bénéfice de ceux qui les regarderont avec un visualisateur roff autre que
                groff.  De  cette façon, l'URL, le texte du lien et le texte de fin (s'il y en a)
                restent visibles.

                Voici un exemple :
                      .de URL
                      \\$2 \(laURL: \\$1 \(ra\\$3
                      ..
                      .if \n[.g] .mso www.tmac
                      .TH ...
                      (plus bas dans la page page)
                      Ce logiciel est fournit par le
                      .URL "http://www.gnu.org/" "Projet GNU" " de la"
                      .URL "http://www.fsf.org/" "Free Software Foundation" .

                Dans ce qui précède, si groff est utilisé, la  définition  de  la  macro  URL  du
                paquet macro www.tmac surchargera celle qui est définie localement.

       Un  certain nombre d'autres macros lien sont disponibles. Consultez groff_www(7) pour plus
       de précisions.

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

       .PD d    Définir  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 gauches : “

       \*(rq  Guillemets en chevrons droits : ”

   Sous‐ensemble sûr
       Bien que techniquement man soit un paquet 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ées par les outils) : \", ., 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 suites de protection de troff (celles  qui  commencent  par
       \).  Si  vous  devez insérer une barre oblique inverse 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 suites de protection 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 paquet ou dans celui de mdoc avec une  signification  différente,
       il  est  probable  que  la  définition  en serait ignorée. Toute 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 police (ft et les suites de protection \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.

FICHIERS

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

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 URL, 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éanmoins,  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)

BOGUES

       La plupart des macros décrivent la mise en forme (police,  espacement, etc.)  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.

VOIR AUSSI

       apropos(1),   groff(1),   lexgrog(1),   man(1),   man2html(1),  groff_mdoc(7),  whatis(1),
       groff_man(7), groff_www(7), man-pages(7), mdoc(7)

COLOPHON

       Cette page fait partie de la publication 3.65 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

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

       Christophe   Blaess   <http://www.blaess.fr/christophe/>   (1996-2003),    Alain    Portal
       <http://manpagesfr.free.fr/>  (2003-2006).  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> ».