> Linux Reviews > man >

man

formate et affiche les pages du manuel en ligne

man.1.man
man.7.man

1. man.1.man

Manpage of MAN

MAN

Section: Commandes utilisateur (1)
Updated: 19 septembre 2005
Index Return to Main Contents

NOM

man - formate et affiche les pages du manuel en ligne

SYNOPSIS

man [-acdfFhkKtwW] [--path] [-m système] [-p chaîne] [-C fichier_config] [-M chemin] [-P visualiseur] [-B navigateur] [-H visualiseur] [-S liste_sections] [section] nom ...

DESCRIPTION

man formate et affiche les pages du manuel en ligne. Si section est spécifiée, man ne recherchera que dans cette section du manuel. nom est le nom de la page qui est généralement le nom d'une commande, d'une fonction ou d'un fichier. Toutefois, si nom contient une barre oblique « / », il sera d'abord considéré en tant que nom de fichier, vous pouvez donc faire : man ./toto.5 ou même man /truc/machin/bidule.1.gz.

Voir plus loin pour une description sur la façon dont man cherche les fichiers pages de manuel.

OPTIONS

-C fichier_config: Spécifie le fichier de configuration à utiliser ; par défaut il s'agit de /etc/man.conf. (Voir man.conf(5).)
-M chemin: Indique la liste des répertoires dans lesquels la recherche des pages sera effectuée. Veuillez séparer les répertoires par le symbole deux points « : ». Une liste vide est équivalent à ne pas spécifier l'option -M. Voir CHEMIN DE RECHERCHE POUR LES PAGES DE MANUEL.
-P visualiseur: Indique le programme de visualisation des pages à employer. Cette option a priorité sur la variable d'environnement MANPAGER, qui, à son tour, a priorité sur la variable d'environnement PAGER. Par défaut, man utilisera /usr/bin/less -is.
-B: Spécifie quel navigateur utiliser pour les fichiers HTML. Cette option supplante la variable d'environnement BROWSER Par défaut, man utilise /usr/bin/lynx.
-H: Spécifie une commande qui produit un fichier texte à partir du fichier HTML. Cette option supplante la variable d'environnement HTMLPAGER Par défaut, man utilise /usr/bin/lynx-dump.
-S liste_sections: Il s'agit d'une liste de sections, séparées par le symbole deux points « : », dans lesquelles les pages seront recherchées. Elle a priorité sur la variable d'environnement MANSECT.
-a: Par défaut, man s'arrête après avoir affiché la première page de manuel trouvée. Cette option permet de l'obliger à afficher toutes les pages correspondant à la requête « nom » de l'utilisateur, s'il y en a plusieurs, et pas seulement la première trouvée.
-c: Reformater la page de manuel, même si une version préformatée à jour existe. Cela peut être utile si cette dernière a été prévue pour un écran de taille différente ou bien si elle est abîmée.
-d: Ne pas afficher les pages de manuel, mais fournir une grande quantité d'informations de débogage.
-D: Afficher à la fois les pages de manuel et les informations de débogage.
-f: Équivalent à whatis.
-h: Afficher un court message d'aide et quitter.
-k: Équivalent à apropos.
-K: Chercher la chaîne spécifiée dans *toutes* les pages de manuel. Attention : cela peut être très long ! Et il peut être utile de spécifier une section. (Pour donner une vague idée, sur ma machine, il faut environ une minute pour 500 pages de manuel.)
-m système: Demander l'utilisation d'un autre jeu de pages de manuel, en fonction du nom de système indiqué.
-p chaîne: Spécifie la séquence de préprocesseurs à exécuter avant nroff ou troff. Selon votre installation de Linux, vous ne disposerez pas forcément de tous les programmes possibles. Voici les plus courants et les lettres qui les désignent : eqn (e), grap (g), pic (p), tbl (t), vgrind (v), refer (r). Cette option a priorité sur la variable d'environnement MANROFFSEQ.
-t: Utiliser /usr/bin/groff -Tps -mandoc pour formater la page de manuel, la sortie se faisant sur stdout. La sortie de /usr/bin/groff -Tps -mandoc peut nécessiter un passage par certains filtres avant de pouvoir être affichée ou imprimée.
-w ou --path: Ne pas afficher les pages de manuel, mais les emplacements des fichiers qui auraient été formatés ou affichés. Si aucun argument n'est précisé, indique sur la sortie standard la liste des répertoires dans lesquels man recherche les pages. Si manpath est un lien sur le programme man, alors « manpath » est équivalent à la commande « man --path ».
-W: Comme -w, mais affiche les noms de fichiers, un par ligne, sans aucune autre information. Très utile dans des commandes shell du genre : man -aW man | xargs ls -l

PAGES FORMATÉES

Afin de gagner du temps, man tente de sauvegarder les pages formatées au lieu de les interpréter chaque fois qu'elles sont demandées. Traditionnellement, les versions formatées des pages de REP/manX sont enregistrées dans REP/catX, mais d'autres correspondances entre les répertoires man et les répertoires cat peuvent être indiquées dans le fichier /etc/man.conf. Aucune page formatée n'est enregistrée si le répertoire « cat » correspondant n'existe pas. Aucune page formatée n'est enregistrée si elle est formatée avec une longueur de ligne différente de 80. Aucune page formatée n'est enregistrée si le fichier /etc/man.conf contient la ligne NOCACHE.

Il est possible de rendre man suid utilisateur man. Dans ce cas, si un répertoire « cat » appartient à man et a le mode 0755 (seul man peut l'écrire), et que les fichiers formatés appartiennent eux aussi à man et ont le mode 0644 ou 0444 (seul man peut les écrire, voire personne), aucun utilisateur normal ne pourra modifier les pages formatées ou mettre d'autre fichiers dans le répertoire correspondant. Si man n'est pas suid, les répertoires « cat » devront avoir le mode 0777 afin que tout utilisateur puisse y laisser le résultat des formatages lors des consultations du manuel.

L'option -c force le reformatage d'une page, même si un fichier cat plus récent que le fichier source existe.

CHEMIN DE RECHERCHE POUR LES PAGES DE MANUEL

man utilise une méthode sophistiquée pour chercher les pages de manuels, basée sur l'invocation d'options et de variables d'environnement, le fichier de configuration /etc/man.conf, des heuristiques et conventions prédéfinies.

En premier lieu, lorsque l'argument nom de man contient une barre oblique « / », man suppose qu'il s'agit d'un fichier et aucune recherche complexe n'est lancée.

Mais dans la plupart des cas où nom ne contient pas de barre oblique, man recherche dans plusieurs répertoires un fichier qui pourrait être une page de manuel pour le sujet nommé.

Si vous spécifiez l'option -M liste_chemins, liste_chemins est une liste de répertoires, séparés par le symbole deux points « : », dans lesquels man effectuera sa recherche.

Si vous ne spécifiez pas -M mais que vous positionniez la variable d'environnement MANPATH, la valeur de cette variable est la liste des répertoires dans lesquels man effectuera sa recherche.

Si vous ne spécifiez pas une liste de chemins explicite avec -M ou MANPATH, man développe sa propre liste de chemins basée sur le contenu du fichier de configuration /etc/man.conf. Les déclarations MANPATH dans le fichier de configuration identifient des répertoires particuliers à inclure dans le chemin de recherche.

Qui plus est, les déclarations MANPATH_MAP complètent le chemin de recherche en fonction du chemin de recherche de vos commandes (autrement dit, de votre variable d'environnement PATH). La déclaration MANPATH_MAP indique, pour chacun des répertoires pouvant se trouver dans le chemin de recherche des commandes, un répertoire qui devrait être ajouté au chemin de recherche des pages de manuel. man scrute la variable PATH et ajoute au chemin de recherche des pages de manuel les répertoires correspondants. Ainsi, avec une utilisation correcte de MANPATH_MAP, lorsque vous tapez la commande man xyz, vous obtenez la page de manuel du programme que vous lanceriez si vous tapiez la commande xyz.

De plus, pour chacun des répertoires situés dans le chemin de recherche des commandes (nous l'appellerons « répertoire commandes ») pour lequel vous n'avez pas d'instruction MANPATH_MAP, man cherchera automatiquement un répertoire de pages de manuel à proximité, à savoir un sous-répertoire du « répertoire commandes » lui-même ou dans le répertoire parent du « répertoire commandes ».

Vous pouvez désactiver la recherche automatique de proximité en incluant l'instruction NOAUTOPATH dans le fichier de configuration /etc/man.conf.

Dans chaque répertoire du chemin de recherche décrit plus haut, man cherche un fichier nommé sujet.section, avec un suffixe optionnel sur le numéro de section et un possible suffixe de compression. S'il ne peut trouver un tel fichier, il regarde alors dans tous les sous-répertoires nommés manN ou catN où N est le numéro de la section du manuel. Si le fichier se trouve dans le sous-répertoire cat N, man suppose qu'il s'agit d'une page de manuel formatée (page cat). Autrement, man suppose qu'elle n'est pas formatée. Dans tous les cas, si le nom de fichier comporte une extension indiquant une compression connue (comme .gz), man suppose que le fichier est gzippé.

Si vous vouloir savoir où (ou si) man peut trouver une page de manuel sur un sujet particulier, utilisez l'option --path (-w).

ENVIRONNEMENT

MANPATH: Si la variable MANPATH est positionnée, man utilisera sa valeur comme chemin de recherche des pages de manuel. Cette variable est prioritaire sur le fichier de configuration et le chemin de recherche automatique, mais cède cette priorité si l'option -M est utilisée. Voir CHEMIN DE RECHERCHE POUR LES PAGES DE MANUEL.
MANPL: Si la variable MANPL est positionnée, sa valeur servira à définir la longueur de l'affichage de la page. Autrement, la page entière est affichée sur une seule et longue page.
MANROFFSEQ: Si MANROFFSEQ est positionnée, sa valeur servira à déterminer le jeu de préprocesseurs à exécuter avant de lancer nroff ou troff. Par défaut, les pages sont passées dans le processeur de tableaux avant nroff.
MANSECT: Si MANSECT est positionnée, sa valeur déterminera les sections du manuel dans lesquelles les pages seront recherchées.
MANWIDTH: Si MANWIDTH est positionnée, sa valeur servira à définir la largeur de l'affichage de la page. Autrement, la page sera affichée sur toute la largeur de l'écran.
MANPAGER: Si MANPAGER est positionnée, sa valeur sera considérée comme le nom du programme à utiliser pour visualiser la page de manuel. Dans le cas contraire, PAGER sera utilisée. Si aucune des deux variables n'est positionnée, /usr/bin/less -is sera utilisé.
LANG: Si LANG est positionnée, sa valeur définira le nom du sous-répertoire où man commencera la recherche des pages de manuel. Ainsi, la commande « LANG=fr man 1 toto » aura pour effet de faire rechercher la page toto dans .../../toto.1, et si ce fichier n'existe pas, dans .../toto.1, où ... est un répertoire du chemin de recherche.
NLSPATH, LC_MESSAGES, LANG: Les variables d'environnement NLSPATH et LC_MESSAGES (ou LANG lorsque la dernière n'existe pas) jouent un rôle dans la localisation du catalogue de messages. (Mais les messages anglais sont inclus dans le programme à la compilation, aucun catalogue n'est donc nécessaire pour un affichage dans la langue de Shakespeare.) Notez que les programmes comme col(1) qui sont appelés par man, utilisent également LC_CTYPE.
PATH: PATH est utilisée pour la construction du chemin de recherche par défaut. Voir CHEMIN DE RECHERCHE POUR LES PAGES DE MANUEL.
SYSTEM: SYSTEM est employée pour obtenir le nom du système alternatif par défaut (en vue de l'utilisation de l'option -m ).

BOGUES

L'option -t ne fonctionne que si un programme « troff-like » est installé.
Si vous voyez clignoter \255 ou <AD> au lieu de traits d'union, mettez « LESSCHARSET=latin1 » dans votre environnement.

ASTUCES

Si vous ajoutez la ligne

(global-set-key [(f1)] (lambda () (interactive) (manual-entry (current-word))))

à votre fichier .emacs, vous obtiendrez la page de manuel de l'appel de la bibliothèque situé à la position courante du curseur lorsque vous presserez la touche F1.

Pour obtenir une version texte seul d'une page de manuel, sans retour arrière ni caractère de soulignement, essayez

# man foo | col -b > foo.mantxt

AUTEUR

John W. Eaton est l'auteur historique de man. Federico Lucifredi <flucifredi@acm.org> en assure aujourd'hui la maintenance.

VOIR AUSSI

apropos(1), whatis(1), less(1), groff(1), man.conf(5).

TRADUCTION

Ce document est une traduction réalisée par René Cougnenc en mai 1995 et mise à jour par Alain Portal <aportal@univ-montp2.fr> le 7 novembre 2005.

L'équipe de traduction a fait le maximum pour réaliser une adaptation française de qualité. La version anglaise la plus à jour de ce document est toujours consultable via la commande : « LANG=en man 1 man ». N'hésitez pas à signaler à l'auteur ou au traducteur, selon le cas, toute erreur dans cette page de manuel.

Index

NOM
SYNOPSIS
DESCRIPTION
OPTIONS
PAGES FORMATÉES
CHEMIN DE RECHERCHE POUR LES PAGES DE MANUEL
ENVIRONNEMENT
BOGUES
ASTUCES
AUTEUR
VOIR AUSSI
TRADUCTION

This document was created by man2html using the manual pages.
Time: 00:22:54 GMT, November 20, 2008

2. man.7.man

Manpage of MAN

MAN

Section: Manuel de l'administrateur Linux (7)
Updated: 27 juillet 2004
Index Return to Main Contents

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 paquetage groff tmac.an (souvent appelÃ© paquetage man). Ce paquetage 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 paquetage, 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Ã©.

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 bibliothÃ¨que 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 ayant un rapport, dans l'ordre alphabÃ©tique, suivies des autres documents Ã©ventuels.
TRADUCTION: le nom du traducteur. Si son adresse courriel 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, mÃªme 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 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. 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

(FonctionnalitÃ© supportÃ©e 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="u">. <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
[.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. defined one.

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).

\*R: Symbole d'enregistrement : ®
\*(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Ã©es 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 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,
x,
(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 m(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.

AUTEURS

---: 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), m(1), mdoc(7), mdoc.samples(7), groff_man(7), groff_www(7), whatis(1)

TRADUCTION

Ce document est une traduction rÃ©alisÃ©e par Christophe Blaess <http://www.blaess.fr/christophe/> le 20 octobre 1996 et rÃ©visÃ©e le 10 aoÃ»t 2006.

L'Ã©quipe de traduction a fait le maximum pour rÃ©aliser une adaptation franÃ§aise de qualitÃ©. La version anglaise la plus Ã jour de ce document est toujours consultable via la commande : Â« LANG=en man 7 man Â». N'hÃ©sitez pas Ã signaler Ã l'auteur ou au traducteur, selon le cas, toute erreur dans cette page de manuel.