NOM
man - Macros pour la mise en forme des pages de manuel.
SYNOPSIS
groff -Tascii -man fichier ...
groff -Tps -man fichier ...
man [section] titre
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, 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 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, qui doit être la première
section et dont la ligne suivant le titre doit être une description
courte du programme :
.SH NAME
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).
Pour une liste des autres sections pouvant apparaître dans une page de
manuel, voir man-pages(7).
Fontes
Les commandes pour sélectionner les fontes sont les suivantes :
.B Gras.
.BI Gras alterné avec Italique (très utile pour les spécifications de
fonctions).
.BR Gras alterné avec Roman (très utile 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 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érerer 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 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 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. 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
(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), on peut les utiliser 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. Voir
groff_www(7) pour plus de détails.
Macros diverses
.DT Réinitialiser les tabulations à leurs valeurs par défaut, tous
les 0.5pouces. Ne provoque pas 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 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 séquences d’échappement 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 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 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 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.
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é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)
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.
VOIR AUSSI
apropos(1), groff(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.23 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
Cette page de manuel a été traduite et mise à jour par Christophe
Blaess <http://www.blaess.fr/christophe/> entre 1996 et 2003, puis par
Alain Portal <aportal AT univ-montp2 DOT fr> jusqu’en 2006, et mise à
disposition sur http://manpagesfr.free.fr/.
Les mises à jour et corrections de la version présente dans Debian sont
directement gérées par Julien Cristau <jcristau@debian.org> et l’équipe
francophone de traduction de Debian.
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> ».