Provided by:
manpages-fr_3.32d0.2p4-1_all 
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 appele paquet de macros man). Ce paquet doit etre utilise par
les developpeurs pour ecrire 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 problemes (sauf
pour NET-2 BSD qui utilise un paquetage completement different appele
mdoc, consultez mdoc(7)).
Notez que les pages de manuel NET-2 BSD peuvent etre visualisees avec
groff simplement en specifiant l'option -mdoc a la place de l'option
-man. L'utilisation de l'option -mandoc est neanmoins recommandee
puisqu'il detectera automatiquement le paquetage utilise.
Les conventions utilisees pour les pages de manuel du paquet man-pages
pour Linux sont decrites dans man-pages(7).
Ligne de titre
La premiere commande d'une page de manuel (apres des lignes de
commentaire, qui commencent par .\") doit etre
.TH titre section date source manuel,
Les details des arguments passes a la commande TH sont decrits dans
man-pages(7).
Notez que les pages BSD formatees 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 etre la premiere
section et dont la ligne suivant le titre doit etre une description
courte du programme :
.SH NAME
Il est tres important que ce format soit respecte, et qu'il se trouve
un backslash avant le tiret suivant le nom du programme. Il est
important que toute la description soit placee sur une seule ligne.
Cette syntaxe est utilisee par le programme makewhatis(8) pour creer la
base de donnees des descriptions pour les commandes whatis(1) et
apropos(1).
Pour une liste des autres sections pouvant apparaitre dans une page de
manuel, consultez man-pages(7).
Fontes
Les commandes pour selectionner les fontes sont les suivantes :
.B Gras.
.BI Gras alterne avec Italique (tres utile pour les specifications de
fonctions).
.BR Gras alterne avec Roman (tres utile pour les references aux autres
pages de manuel).
.I Italique.
.IB Italique alterne avec Gras.
.IR Italique alterne avec Roman.
.RB Roman alterne avec Gras.
.RI Roman alterne avec Italique.
.SB Petit alterne avec Gras.
.SM Petit (utile pour les acronymes).
Traditionnellement, chaque commande peut avoir jusqu'a six arguments,
mais les versions GNU semblent eliminer cette contrainte (vous
prefererer surement vous limiter a 6 arguments pour des raisons de
portabilite). Les arguments sont delimites par des espaces. Des
guillemets sont utilises pour encadrer un argument qui contient des
espaces. Tous les arguments seront imprimes les uns apres les autres
sans intercaler d'espace, ainsi la commande .BR peut etre utilisee pour
indiquer un mot en Gras suivi par un signe de ponctuation en Roman. Si
aucun argument n'est fourni, la commande s'applique a la ligne
suivante.
Autres macros et cha^ines
Ci-dessous se trouvent les macros et chaines predefinies. Sauf
indication contraire, toutes les macros declenchent un saut de ligne.
La plupart de ces macros utilisent ou modifient l'indentation courante.
Celle-ci est fixee par toute macro avec le parametre i ci-dessous ; les
macros peuvent omettre le i auquel cas l'indentation courante est
utilisee. En consequence, les paragraphes suivants peuvent utiliser la
meme indentation sans la repeter. Un paragraphe normal, non-indente,
replace l'indentation courante a sa valeur par defaut (0.5 pouces). Par
defaut, les indentations sont mesurees 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 (debute un nouveau paragraphe).
.P Comme .PP (debute un nouveau paragraphe).
.PP Debute un nouveau paragraphe et reinitialise l'indentation
courante.
Indentation Relative
.RS i Debute une indentation relative : deplace la marge gauche de i
vers la droite (si i est absent, la valeur d'indentation
courante est utilisee). Une nouvelle valeur d'indentation est
placee a 0.5 pouces. En consequence, tous les paragraphes
suivants seront indentes jusqu'au .RE correspondant.
.RE Terminer une indentation relative et restituer les valeurs
precedentes d'indentation courante.
Macros d'indentation de paragraphe
.HP i Debute un paragraphe avec une indentation d'accroche (la
premiere ligne du paragraphe est le long de la marge gauche,
et les autres lignes sont indentees).
.IP x i Paragraphe indente avec une balise d'accroche eventuelle. Si
la balise x est omise, tout le paragraphe est indente de i. Si
la balise x est fournie, elle est accrochee le long de la
marge gauche, avant le paragraphe indente (c'est comme .TP
sauf que la balise est incluse avec la commande elle-meme
plutot que d'etre sur la ligne suivante). Si la balise est
trop longue, le texte sera transpose a la ligne suivante (le
texte ne sera ni perdu ni tronque). Pour les listes a puces,
utilisez cette macro avec \(bu (rond) ou \(em (tiret) comme
balise, et pour les listes numerotees utilisez le numero ou la
lettre suivi par un point. Ceci simplifie la traduction dans
d'autres formats.
.TP i Debut d'un paragraphe avec une balise d'accroche. La balise
est donnee sur la ligne suivante, mais le resultat est
identique a celui de la commande .IP.
Macros de liens hypertextes
(Fonctionnalite prise en charge par groff seulement.) Afin d'utiliser
les macros de liens hypertexte, il est necessaire de charger le paquet
macro www.tmac. Utiliser la requete .mso www.tmac pour le faire.
.URL url lien fin
Insere un lien hypertexte vers l'URI (URL) url, avec lien
comme texte du lien. La fin sera affichee immediatement apres.
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
ecriront leur texte), on peut les utiliser sans souci.
Il peut etre utile de definir votre propre macro URL dans les
pages de manuels pour le benefice de ceux qui les regarderont
avec un visualisateur roff autre que groff. De cette facon,
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 precede, si groff est utilise, la definition de la
macro URL du paquet macro www.tmac surchargera celle qui est
definie localement.
Un certain nombre d'autres macros lien sont disponibles. Consultez
groff_www(7) pour plus de details.
Macros diverses
.DT Reinitialiser les tabulations a leurs valeurs par defaut, tous
les 0.5 pouces. Ne provoque pas de saut de ligne.
.PD d Fixer la distance verticale entre paragraphes a 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^ines pr'ed'efinies
Le paquet man contient les chaines predefinies suivantes :
\*R Symbole d'enregistrement : (R)
\*S Taille de police par defaut.
\*(Tm Symbole marque deposee : tm
\*(lq Guillemets en chevrons gauches : "
\*(rq Guillemets en chevrons droits : "
Sous-ensemble s^ur
Bien que techniquement man soit un paquet de macros troff, en realite
un grand nombre d'autres outils traitent les fichiers des pages de
manuel, sans implementer toutes les possibilites de troff. Il vaut donc
mieux eviter certaines fonctionnalites exotiques de troff. Evitez
d'utiliser les preprocesseurs de troff (s'il le faut, utilisez tbl(1),
mais essayez d'employer plutot les commandes IP et TP pour les tableaux
a deux colonnes). Evitez d'utiliser les calculs, la plupart des autres
outils ne les realisent pas. Utilisez des commandes simples facile a
traduire dans d'autres formats. Les macros suivantes sont reconnues
comme sures (meme si elles sont parfois ignorees 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 sequences d'echappement de troff (celles
qui commencent par \). Si vous devez inserer une barre oblique inverse
comme du texte normal, utilisez \e. Les autres sequences que vous
pouvez utiliser, x et xx etant des caracteres quelconques, et N un
chiffre, sont : \', \`, \-, \., \", \%, \*x, \*(xx, \(xx, \$N, \nx,
\n(xx, \fx, et \f(xx. Evitez d'utiliser des sequences d'echappement
pour dessiner des graphiques.
N'utilisez pas les parametres optionnels pour bp (break page). Utilisez
seulement des valeurs positives pour sp (vertical space). Ne definissez
pas de macro (de) avec le meme nom qu'une macro dans ce paquet ou dans
celui de mdoc avec une signification differente, il est probable que la
definition en serait ignoree. Toute indentation positive (in) devrait
etre appariee avec une indentation negative identique (bien que vous
devriez plutot utiliser les macros RS et RE a la place). Les tests
(if,ie) ne devraient avoir que << t >> ou << n >> comme condition.
Seules les traductions (tr) qui peuvent etre ignorees devraient etre
utilisees. Les changement de fontes (ft et les sequences d'echappement
\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 parametre).
Si vous utilisez d'autres fonctionnalites que celles-ci, verifiez le
resultat soigneusement sur divers outils. Une fois que vous avez
confirmation que la nouvelle fonctionnalite est sure, faites-le savoir
au mainteneur de cette page.
FICHIERS
/usr/share/groff/[*/]tmac/an.tmac
/usr/man/whatis
NOTES
Inserez les URLs complets dans le texte lui-meme, 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 inserer
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 caractere non-blanc. Un point ou un apostrophe simple au debut
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 caractere correspond a un texte ASCII simple (par exemple
une sortie << catman >>).
Plusieurs pages commencent avec '\" suivi d'une espace et d'une liste
de caracteres indiquant comment la page doit etre pre-traitee. Pour
ameliorer la portabilite vers des traducteurs non-troff, nous vous
recommandons d'eviter d'utiliser autre chose que tbl(1). Sous Linux, la
detection en est automatique. Nenamoins, vous pouvez inclure cette
information pour que votre page de manuel puisse etre traitee par
d'autres systemes (moins capables). Voici la definition des
preprocesseurs invoques par ces caracteres :
e eqn(1)
g grap(1)
p pic(1)
r refer(1)
t tbl(1)
v vgrind(1)
BOGUES
La plupart des macros decrivent la mise en forme (police,
espacement...) au lieu de marquer le contenu semantique (par exemple
reference vers une autre page) comme le font des formats comme mdoc ou
DocBook (meme l'HTML a des balises plus semantiques). Cette situation
rend le format man difficile a traduire sur differents supports. En se
limitant au sous-ensemble de macros decrites plus haut, il devrait etre
plus facile de basculer automatiquement vers un autre format de page de
reference dans l'avenir.
La macro Sun TX n'est pas implementee.
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.32 du projet man-pages
Linux. Une description du projet et des instructions pour signaler des
anomalies peuvent etre trouvees a l'adresse
<URL:http://www.kernel.org/doc/man-pages/>.
TRADUCTION
Depuis 2010, cette traduction est maintenue a l'aide de l'outil po4a
<URL:http://po4a.alioth.debian.org/> par l'equipe de traduction
francophone au sein du projet perkamon
<URL:http://perkamon.alioth.debian.org/>.
Christophe Blaess <URL:http://www.blaess.fr/christophe/> (1996-2003),
Alain Portal <URL:http://manpagesfr.free.fr/> (2003-2006). Julien
Cristau et l'equipe francophone de traduction de Debian (2006-2009).
Veuillez signaler toute erreur de traduction en ecrivant a
<debian-l10n-french@lists.debian.org> ou par un rapport de bogue sur le
paquet manpages-fr.
Vous pouvez toujours avoir acces a la version anglaise de ce document
en utilisant la commande << man -L C <section> <page_de_man> >>.