Provided by:
manpages-fr_1.67.0-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 tmac.an
(souvent appelé paquet man). Ce paquet doit être utilisé par les
développeurs pour écrire ou porter des pages de manuels pour Linux. 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 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 paquet utilisé.
PRÉAMBULE
La première commande d’une page de manuel doit être
.TH titre section date source manuel,
avec :
titre Le titre de la page de manuel (par exemple MAN).
section Le numéro de section dans laquelle placer la page (par
exemple 7).
date La date de la dernière modification. Pensez à modifier
cette date à chaque changement dans la page, car c’est
la manière la plus courante d’avoir un contrôle de
version.
source La source de la commande
Pour les exécutables, utilisez quelque chose comme GNU,
NET-2, SLS Distribution, MCC Distribution.
Pour les appels-système, vous pouvez indiquer la version
du noyau que vous utilisez : Linux 2.4.19.
Pour les fonctions de bibliothèque, utilisez la source
de la fonction : GNU, BSD 4.3, Linux DLL 4.4.1.
manuel Le titre du manuel (par exemple Manuel du programmeur
Linux).
Notez que les pages BSD formatées avec mdoc commencent avec la commande
Dd et non pas TH.
Les sections du manuel sont traditionnellement réparties ainsi :
1 Commandes
Les commandes qui peuvent être invoquées par
l’utilisateur depuis le shell.
2 Appel systèmes
Les fonctions fournies par le noyau.
3 Fonctions de bibliothèques
La plupart des fonctions de la bibliothque C telles
que qsort(3).
4 Périphériques
Fichiers spéciaux trouvés dans
5 Formats de fichiers et conventions
Le format de /etc/passwd et d’autres fichiers lisibles
par un humain.
6 Jeux
7 Conventions et divers
Une description du système de fichiers standard, cette
page de manuel, des jeux de caractères, entre
autres...
8 Commandes d’administration système.
Les commandes comme mount(8), que seul root peut
exécuter.
9 Routines du noyau
Il s’agit d’une section obsolète. On a jadis pensé
qu’il serait bon de documenter le noyau Linux ici,
mais en fait très peu de documentation a été réaliséE,
et celle qui existe est déjà dépassée. Il existe de
bien meilleures sources d’information pour les
développeurs du noyau.
SECTIONS (PARAGRAPHES)
Les sections commencent par .SH suivies de leurs titres. Si le titre
contient des espaces, l’encadrer par des guillemets. Les titres
traditionnels sont : NOM, SYNOPSIS, DESCRIPTION, VALEUR RENVOYÉE, CODE
DE RETOUR, ERREURS, OPTIONS, FICHIERS, EXEMPLE, VOIR AUSSI,
DIAGNOSTIQUE, BOGUES, ENVIRONNEMENT, SÉCURITÉ, CONFORMITÉ, AUTEUR, VOIR
AUSSI, et TRADUCTION. Utilisez de préférence ces titres s’il vous
plaît ; cette cohérence rend les pages de manuel plus faciles à
comprendre. Maintenant, créez vos propres titres si vous pensez que
c’est nécessaire. Le seul titre indispensable est NOM, qui doit être
suivi sur la ligne suivante par une courte description du programme :
.SH NOM
chess \- Jeu d’échecs
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).
Ndt : Vous vous doutez bien que la version de distribution de
makewhatis(8) ne reconnaît pas la section « NOM » mais la section
« NAME ». Pour que les commandes whatis(1) et apropos(1) fonctionnent,
il faut modifier le script makewhatis(8). La modification à apporter
est décrite dans le fichier LISEZ_MOI, qui est livré avec l’archive des
pages de manuel en français.
Les autres sections contiennent habituellement les éléments suivants :
SYNOPSIS indique brièvement l’interface de la commande ou de la
fonction. Pour les commandes, ce paragraphe montre sa
syntaxe et ses arguments. Les caractères gras marquent
le texte invariable et l’italique indique les arguments
remplaçables. Les crochets « [] » encadrent les arguments
optionnels, les barres verticales « | » séparent les
alternatives, et les ellipses « ... » signalent les
répétitions. Pour les fonctions, on trouve toutes les
déclarations et directives #include, suivies de la
déclaration de fonction.
DESCRIPTION fournit une explication sur ce que la commande, la
fonction ou le format représente. Décrit les interactions
avec les fichiers et l’entrée standard, ou ce qui est
produit sur la sortie standard ou d’erreur. Ne contient
pas les détails d’implémentation internes, sauf s’ils
sont critique pour comprendre l’interface. Décrit le cas
principal, pour les détails sur les options, on utilise
le paragraphe OPTIONS. S’il y a une sorte de grammaire
d’entrée, ou un jeu de sous-commandes, on peut les placer
dans un paragraphe UTILISATION supplémentaire (juste
après la section DESCRIPTION).
VALEUR RENVOYÉE
donne une liste des valeurs qu’une routine de
bibliothèque renverra à l’appelant et les conditions qui
provoquent ces retours.
CODE DE RETOUR
indique les codes de retour d’un programme et les
conditions associées.
OPTIONS décrit les options acceptées par le programme et comment
son comportement se modifie.
UITILISATION décrit la grammaire de tout sous-langage implémenté.
EXEMPLES donne un ou plusieurs exemples d’utilisation de la
fonction, du fichier ou de la commande.
FICHIERS liste les fichiers utilisés par le programme ou la
fonction, tels que fichiers de configuration, de
démarrage, et les fichiers manipulés directement par le
programme. Il faut donner le chemin d’accès complet des
fichiers et utiliser le mécanisme d’installation pour
modifier le préfixe. Pour la plupart des programmes,
l’installation par défaut se fait dans /usr/local, aussi,
votre page de manuel de base devrait utiliser /usr/local
comme base.
ENVIRONNEMENT décrit toutes les variables d’environnement qui affectent
le programme ou la fonction, ainsi que leurs effets.
DIAGNOSTIQUE fournit un survol des messages d’erreurs usuels et
comment les considérer. Il n’est pas nécessaire
d’indiquer les messages d’erreur système ou les signaux
fatals qui peuvent apparaître durant l’exécution du
programme, sauf s’ils sont traités spécialement.
SECURITÉ concerne les problèmes de sécurité et leurs implications.
Doit contenir les avertissements à propos des
configurations ou des environnements à éviter, les
commandes ayant des répercussions au niveau sécurité,
etc. surtout s’ils ne sont pas évidents. Il n’est pas
obligatoire de faire un paragraphe spécifique sur la
sécurité. Si l’intelligibilité est améliorée, on peut
placer ces informations dans les autres sections (telles
que DESCRIPTION ou UTILISATION ). Néanmoins, il est
important de placer les informations de sécurité quelque
part.
CONFORMITÉ décrit les standards ou les conventions suivis par
l’implémentation.
NOTES contient des notes diverses.
BOGUES liste les limitations ou les défauts recensés, ainsi que
les sujets à débat.
AUTEUR liste les auteurs de la documentation ou du programme
afin de pouvoir leur envoyer les rapports de bogue.
VOIR AUSSI fournit une liste des pages de manuel ayany un rapport,
dans l’ordre alphabétiques, suivies des autres documents
éventuels.
TRADUCTION le nom du traducteur. Si son adresse mail n’est pas
fournie, vous la trouverez dans le fichier LISEZ_MOI
fournit avec les pages de manuel en français. Le
paragraphe "TRADUCTION" n’est pas destiné à flatter l’ego
du traducteur, mais à savoir à qui s’adresser si vous
relevez une erreur !
FONTES
Bien qu’il y ait de nombreuses conventions arbitraires concernant les
pages de manuel pour UNIX, l’existence de plusieurs centaines de pages
spécifiques à Linux définit nos propres standards :
Pour les fonctions, les arguments sont toujours indiqués en
italique, mme dans le paragraphe SYNOPSIS, où le reste de la
fonction est en caractères gras:
int mafonction(int argc, char **argv);
Les noms de fichiers sont toujours en italique (par exemple
/usr/include/stdio.h), sauf dans le paragraphe SYNOPSIS, où les
fichiers inclus sont en gras (par exemple #include <stdio.h>).
Les macros, généralement en majuscules, sont en gras (par
exemple MAXINT).
Dans l’énumération d’une liste de code d’erreurs, les codes sont
en gras, et la liste utilise normalement la macro .TP.
Toute référence à une autre page de manuel, ou au sujet
principal de la page en cours, est en gras. Si le numéro de
section de manuel est donné, il est en Roman, sans espace (par
exemple man(7)).
Les commandes pour sélectionner les fontes sont les suivantes :
.B Gras
.BI Gras alterné avec Italique (surtout pour les spécifications de
fonctions)
.BR Gras alterné avec Roman (surtout 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 et Gras
.SM Petit (utile pour les acronymes)
Traditionnellement, chaque commande peut avoir jusqu’à six arguments,
mais les versions GNU semblent éliminer cette contrainte. 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 sucessifs 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
Afin d’utiliser les liens hypertextes, il est nécessaire de charger le
paquetage de macros www.tmac, avec l’aide de la commande .mso www.tmac.
.URL url lien suite
Insère un lien hypertexte vers l’URI (URL) url, où lien est le
texte du lien. La suite 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>suite.
Ces macros (et d’autres s’y rapportant) 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.
Un certain nombre d’autres macros sont disponibles pour des liens,
veuillez consulter groff_www(7) pour plus d’informations.
Macros diverses
.DT Réinitialiser les tabulations à leurs valeurs par défaut, tous
les 0.5 pouces sans déclencher 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 droits : “
\*(rq Guillemets en chevrons gauches : ”
Ensemble de commandes sûres
Bien que techniquement man soit un paquetage 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és par les traducteurs) :
\", ., 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 un backslash 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
paquetage ou dans celui de mdoc avec une signification différente, il
est probable que la définition en serait ignorée. Tout 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.
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 URLs, 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)
[Ndt] En français, nous utilisons plus fréquement les « espaces
insécables » que les anglo-saxons. Pour transformer un espace normal en
espace insécable, il suffit de le préfixer par « \ ». Si vous traduisez
des pages, essayez de placer ces espaces insécables avant les points-
virgules, deux-points, point d’exclamation et d’interrogation, et entre
les nombres et les unités (par exemple 1024 ko, s’écrira 1024\ ko).
FICHIERS
/usr/share/groff/ [*/] tmac/tmac.an
/usr/man/whatis
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.
AUTEURS
— James Clark (jjc@jclark.com) a écrit l’implémentation du paquetage
de macros.
— Rickard E. Faith (faith@cs.unc.edu) a écrit la version initiale de
cette page de manuel.
— Jens Schweikhardt (schweikh@noc.fdn.de) a écrit le mini HOWTO Linux-
man-page. (qui a influencé cette page de manuel).
— David A. Wheeler (dwheeler@ida.org) a largement modifié cette page,
en ajoutant des détails sur les sections et les macros.
VOIR AUSSI
apropos(1), groff(1), man(1), man2html(1), mdoc(7), mdoc.samples(7),
groff_www(7), whatis(1)
TRADUCTION
Christophe Blaess, 1996-2003.