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
Below are other relevant macros and predefined strings.
Unless noted otherwise, all macros cause a break (end the
current line of text). Many of these macros set or use the
"prevailing indent." The "prevailing
indent" value is set by any macro with the parameter
i below; macros may omit i in which case the
current prevailing indent will be used. As a result,
successive indented paragraphs can use the same indent
without respecifying the indent value. A normal
(nonindented) paragraph resets the prevailing indent value
to its default value (0.5 inches). By default, a given
indent is measured in ens; try to use ens or ems as units
for indents, since these will automatically adjust to font
size changes. The other key macro definitions are:
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
.UR url
Insert a hypertext link to the URI (URL) url, with all text up to the following .UE macro as the link text.
.UE [ trailer ]
Terminate the link text of the preceding .UR macro, with the optional trailer (if present, usually a closing parenthesis and/or end-of-sentence punctuation) immediately following. For non-HTML output devices (e.g., man -Tutf8), the link text is followed by the URL in angle brackets; if there is no link text, the URL is printed as its own link text, surrounded by angle brackets. (Angle brackets may not be available on all output devices.) For the HTML output device, the link text is hyperlinked to the URL; if there is no link text, the URL is printed as its own link text.
These macros have been supported since GNU Troff 1.20 (2009-01-05) and Heirloom Doctools Troff since 160217 (2016-02-17).
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.
You may also use many troff escape sequences (those sequences beginning with \). When you need to include the backslash character as normal text, use \e. Other sequences you may use, where x or xx are any characters and N is any digit, include: \', \`, \-, \., \", \%, \*x, \*(xx, \(xx, \$N, \nx, \n(xx, \fx, and \f(xx. Avoid using the escape sequences for drawing graphics.
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
By all means include full URLs (or URIs) in the text itself; some tools such as man2html(1) can automatically turn them into hypertext links. You can also use the UR and UE macros to identify links to related information. If you include URLs, use the full URL (e.g., http://www.kernel.org">http://www.kernel.org) to ensure that tools can automatically find the URLs.
Tools processing these files should open the file and examine the first nonwhitespace character. A period (.) or single quote (') at the beginning of a line indicates a troff-based file (such as man or mdoc). A left angle bracket (<) indicates an SGML/XML-based file (such as HTML or Docbook). Anything else suggests simple ASCII text (e.g., a "catman" result).
Many man pages begin with '\" followed by a space and a list of characters, indicating how the page is to be preprocessed. For portability’s sake to non-troff translators we recommend that you avoid using anything other than tbl(1), and Linux can detect that automatically. However, you might want to include this information so your man page can be handled by other (less capable) systems. Here are the definitions of the preprocessors invoked by these characters:
|
e |
||||
|
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 5.07 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 [AT] laposte.net>, Thierry Vignaud <tvignaud [AT] mandriva.com>, François Micaux, Alain Portal <aportal [AT] univ-montp2.fr>, Jean-Philippe Guérard <fevrier [AT] tigreraye.org>, Jean-Luc Coulon (f5ibh) <jean-luc.coulon [AT] wanadoo.fr>, Julien Cristau <jcristau [AT] debian.org>, Thomas Huriaux <thomas.huriaux [AT] gmail.com>, Nicolas François <nicolas.francois [AT] centraliens.net>, Florentin Duneau <fduneau [AT] gmail.com>, Simon Paillard <simon.paillard [AT] resel.fr>, Denis Barbier <barbier [AT] debian.org> et David Prévot <david [AT] tilapin.org>
Cette traduction est une documentation libre ; veuillez vous reporter à la GNU General Public License version 3 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 [AT] lists.org>.