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