Ubuntu Manpage: man - Macros pour la mise en forme des pages de manuel

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 manuel. 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 de macros 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 puisque cela détectera automatiquement le paquet de macros
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).

Fontes
Les commandes pour sélectionner le type de caractère 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 Minuscule alterné avec gras.

.SM Minuscule (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.
Pour les macros qui produisent des types de caractère différents, 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 d’autres macros importantes et des chaînes prédéfinies. Sauf
indication contraire, toutes les macros déclenchent un saut de ligne. La plupart de ces
macros définissent ou modifient « l'indentation prévalente ». 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 prévalente courante est utilisée. En conséquence, les paragraphes suivants
peuvent utiliser la même indentation sans redéfinir la valeur de l’indentation. Un
paragraphe normal, non indenté, redéfinit l'indentation prévalente à sa valeur par défaut
(0,5 pouce). Par défaut, les indentations sont mesurées en « en » (largeur d'une lettre
« n »") ou « em » (largeur d’une lettre « m »). Essayez d’utiliser en ou em comme unité
pour les indentations, ainsi les largeurs s'ajustent automatiquement en cas de changement
de taille de fonte. Les autres principales macros disponibles sont :

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

.P Comme .PP (début d’un nouveau paragraphe).

.PP Début d’un nouveau paragraphe et réinitialisation de l'indentation prévalente.

Indentation relative de marge
.RS i Début d’une indentation relative : déplacement de la marge gauche de i vers la
droite (si i est absent, la valeur d'indentation prévalente est utilisée). Une
nouvelle valeur d'indentation prévalente est placée à 0,5 pouce. En conséquence,
tous les paragraphes suivants seront indentés jusqu'au .RE correspondant.

.RE Fin d’une indentation relative et restauration de la valeur précédente
d'indentation prévalente

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

.IP x i Indentation de paragraphe 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
.UR url
Insertion d’un lien hypertexte vers l’URI (URL) url, avec tout le texte jusqu’à la
macro .UE suivante comme texte du lien.

.UE .RI [ trailer ]
Fin du texte du lien de la macro .UR précédente avec le caractère final trailer (si
présent, habituellement une parenthèse fermante ou une ponctuation de fin de
phrase) en suite immédiate. Pour les dispositifs de sortie non HTML (par exemple,
man -Tutf8), le texte du lien est suivi par l’URL encadré de chevrons. S’il n’y a
pas de texte de lien, l’URL est affiché comme son propre texte de lien, entouré de
chevrons (les chevrons peuvent ne pas être disponibles dans tous les dispositifs de
sortie). Pour les dispositifs de sortie HTML, le texte de sortie sert d’hypertexte
pour l’URL. S’il n’y a pas de texte de lien, l’URL est affiché comme son propre
texte de lien.

Ces macros sont prises en charge depuis GNU Troff 1.20 (5 janvier 2009) et Heirloom
Doctools Troff depuis 160217 (17 février 2016).

Macros diverses
.DT Réinitialisation des tabulations à leurs valeurs par défaut, tous les
demi-pouces. Ne provoque pas de saut de ligne.

.PD d Définition de la distance verticale entre paragraphes à la valeur d (si absente,
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 de marque déposée : ®

\*S Taille de la fonte par défaut.

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

\*(lq Double guillemet-virgule gauche : “

\*(rq Double guillemet-virgule droit : ”

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 faciles à 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 séquences 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 les séquences de protection pour dessiner des graphiques.

N'utilisez pas les paramètres optionnels pour bp (break page). Utilisez seulement des
valeurs positives pour sp (espace vertical). 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 changements de fonte (ft et les séquences 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

       Par tous les moyens, insérez les URL complets dans  le  texte  lui-même,  certains  outils
       comme  man2html(1)  peuvent  les  transformer  automatiquement  en liens hypertextes. Vous
       pouvez aussi utiliser les macros UR  et  UE  pour  associer  les  liens  aux  informations
       correspondantes.  Si  vous  insérez  des  URL,  utilisez  des  URL  complets  (par exemple
       ⟨http://www.kernel.org⟩) pour s'assurer que ces outils les trouveront automatiquement.

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

       Beaucoup de pages de manuel 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 (fonte, 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 à diversifier pour différents médias,  pour  rendre
       le  formatage  cohérent pour un média donné et pour insérer automatiquement des références
       croisées. En se limitant au sous-ensemble de macros sûres décrites plus haut,  il  devrait
       être  plus  facile  de  basculer automatiquement vers un autre format de référence de page
       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 5.10 du projet man-pages Linux. Une description
       du projet et des instructions pour signaler des anomalies et la dernière version de  cette
       page peuvent être trouvées à l'adresse https://www.kernel.org/doc/man-pages/.

TRADUCTION

       La  traduction  française  de  cette  page  de  manuel  a  été créée par Christophe Blaess
       <https://www.blaess.fr/christophe/>, Stéphan  Rafin  <stephan.rafin@laposte.net>,  Thierry
       Vignaud  <tvignaud@mandriva.com>,  François Micaux, Alain Portal <aportal@univ-montp2.fr>,
       Jean-Philippe   Guérard   <fevrier@tigreraye.org>,   Jean-Luc   Coulon   (f5ibh)    <jean-
       luc.coulon@wanadoo.fr>,    Julien    Cristau    <jcristau@debian.org>,    Thomas   Huriaux
       <thomas.huriaux@gmail.com>, Nicolas François <nicolas.francois@centraliens.net>, Florentin
       Duneau  <fduneau@gmail.com>, Simon Paillard <simon.paillard@resel.enst-bretagne.fr>, Denis
       Barbier <barbier@debian.org>, David Prévot <david@tilapin.org>  et  Jean-Paul  Guillonneau
       <guillonneau.jeanpaul@free.fr>

       Cette  traduction  est  une  documentation libre ; veuillez vous reporter à la GNU General
       Public  License  version 3  ⟨https://www.gnu.org/licenses/gpl-3.0.html⟩   concernant   les
       conditions de copie et de distribution. Il n'y a aucune RESPONSABILITÉ LÉGALE.

       Si vous découvrez un bogue dans la traduction de cette page de manuel, veuillez envoyer un
       message à debian-l10n-french@lists.debian.org ⟨⟩.