groff -Tps -man fichier ...

man [section] titre  

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

Pour les conventions à utiliser pour la rédaction de pages de manuel pour le paquetage man-pages Linux, voir man-pages(7).  

.TH titre section date source manuel

Notez que les pages BSD formatées avec mdoc commencent avec la commande Dd et non pas TH.  

Le seul titre indispensable est NOM, qui doit être suivi sur la ligne suivante par une courte description du programme :

.SH NOM

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.

Pour une liste des autres sections qui peuvent apparaîtrent dans une page de manuel, voir man-pages(7).  

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

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

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

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

.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 \n[.g] .mso www.tmac
.TH ...
(plus bas dans la page page)
Ce logiciel est fourni 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.  

.DT

Réinitialiser les tabulations à leurs valeurs par défaut, tous les 0.5 pouces sans déclencher de saut de ligne.

.PD d

Définir la distance verticale entre paragraphes à la valeur d (si absent, d=0.4v). Ne provoque pas de saut de ligne.

.SHt

Sous-chapitre t (comme .SH, mais pour les sous-sections au sein d'une section).

\*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 : ''

Vous pouvez aussi employer les séquences d'échappement de troff (celles qui commencent par \). Si vous devez insérer une contre oblique 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.  

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

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.  

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 22 décembre 2007.

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=C man 7 man ». N'hésitez pas à signaler à l'auteur ou au traducteur, selon le cas, toute erreur dans cette page de manuel.

NOM

SYNOPSIS

DESCRIPTION

Ligne de titre

Sections

Polices

Autres macros et chaînes

Paragraphes normaux

Indentation Relative

Macros d'indentation de paragraphe

Macros de liens hypertextes

Macros diverses

Chaînes prédéfinies

Ensemble de commandes sûres

FICHIERS

NOTES

BOGUES

VOIR AUSSI

TRADUCTION