man − Macros pour la mise en forme des pages de manuel.

groff −Tascii −man fichier ...

groff −Tps −man fichier ...

man [section] titre

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

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 /dev)

5 Formats de fichiers et conventions

Le format de /etc/passwd et d’autres fichiers lisibles par un humain.

6 Jeux

7 Ensembles de macros et de standards

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é, et celle qui existe est déjà dépassée. Il existe de bien meilleures sources d’information pour les développeurs du noyau.

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 librairie 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 du 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 donne 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 est /usr/local.

ENVIRONNEMENT

décrit toutes les variables d’environnement qui affecte 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ée à flatter l’ego du traducteur, mais à savoir à qui s’adresser si vous relevez une erreur !

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, ou 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.

Ci-dessous se trouvent les macros et chaînes prédéfinies. Sauf indication contraire, toutes les macros déclenche 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

.UR u

Débute un lien hypertexte vers l’URI (URL) u; il se terminera avec la commande UE coorrespondante. Lors d’une conversion en HTML, cela se traduit par les commandes HTML <A HREF="u">. Il y a une exception : si u a la valeur spéciale ":", aucun lien hypertext ne sera créé après le UE de fermeture. Ceci permet de désactiver les liens dans des phrases comme LALR(1) lorsqu’ils ne seraient pas appropriés). 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.

.UE

Fin de la commande UR correspondante ; lors de la génération HTML, ceci se traduit par </A>.

.UN u

Crée une cible hypertexte nommée u ; ne contient pas de commande UE correspondante. Lors de la génération de code HTML, ceci devrait se traduire en balise <A NAME="u" id="u">&nbsp;</A> (le &nbsp; est optionnel si le support pour Mosaic n’est pas nécessaire).

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 paquetage 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 : ”

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. Evitez 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). Evitez 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 vou 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. Evitez 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 devrait 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.

Insérer 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 UR 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 a un texte ASCII simple (par exemple une sortie "catman").

Plusieurs pages commencent avec ’\" suivi d’un 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).

/usr/share/groff/ [*/] tmac/tmac.an
/usr/man/whatis

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.

—

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.

apropos(1), groff(1), man(1), man2html(1), mdoc(7), mdoc.samples(7), whatis(1)

Christophe Blaess, 1997.