MAN(7)

NOM
man - Macros pour le formattage des pages de manuel.

SYNOPSIS
groff -Tascii -man file ...

groff -Tps -man file ...

man [section] title

DESCRIPTION
Cette page de manuel explique le contenu du package groff tmac.an. Ce package doit etre utilise par les developpeurs pour ecrire ou porter des pages de manuels pour Linux. Il est largement compatible avec d'autres versions de ce package, donc le portage de pages pour Linux ne devrait pas poser de problemes (sauf pour NET-2 BSD qui utilise un package complement different). 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 package utilise.

PREAMBULE
La premiere commande d'une page de manuel doit etre

    .TH titre section date source manuel,

ou :

    titre
        Le titre de la page de manuel (par exemple MAN).

    section
        Le numero de section dans laquelle placer la page (par exemple 7).

    date
        La date de la derniere modification. Pensez a modifier cette date a chaque changement dans la page, car c'est la maniere la plus courante d'avoir un controle de version.

    source
        La source de la commande

        Pour les executables, utilisez quelque chose comme GNU, NET-2, SLS Distribution, MCC Distribution.

        Pour les appels systemes, indiquez la version du noyau que vous utilisez : Linux 0.99.11.

        Pour les fonctions de bibliotheque, 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).

Les sections du manuel sont traditionnellement reparties ainsi :

    1 Commandes
        Les commandes qui peuvent etre invoquees par l'utilisateur depuis le shell.

    2 Appel systemes
        Les fonctions fournies par le noyau.

    3 Fonctions de bibliotheques
        La plupart des fonctions de la libc telles que sort(3))

    4 Peripheriques
        Fichiers speciaux trouves 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 systeme de fichiers standard, cette page de manuel, des jeux de caracteres, entre autres...

    8 Commandes d'administration systeme.
        Les commandes comme mount(8), que seul root peut executer.

    9 Routines du noyau
        Il s'agit d'une section non-standard, et est incluse ici car le code source de Linux est librement disponible sous license GPL, et beaucoup de gens travaillent sur les changements dans le noyau.

FONTES
Bien qu'il y ait de nombreuses conventions arbitraires concernant les pages de manuel pour UNIX, l'existence de plusieurs centaines de pages specifiques a Linux definit nos propres standards :

    Pour les fonctions, les arguments sont toujours indiques en italique, meme dans le paragraphe SYNOPSIS, ou le reste de la fonction est en caractere gras:
    int mafonction(int argc, char **argv);

    Les noms de fichiers sont toujours en ialique (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, generalement en majuscule, sont en gras (par exemple MAXINT).

    Dans l'enumeration d'une liste de code d'erreurs, les codes sont en gras, et la liste utilise normalement la macro .TP.

    Toute reference a une autre page de manuel, ou au sujet principal de la page en cours, est en gras. Si le numero de section de manuel est donne, il est en Roman, sans espace (par exemple man(7)). Les commandes pour selectionner les fontes sont les suivantes :

.B  Gras

.BI Gras alterne avec Italique

.BR Gras alterne avec Roman

.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

Traditionnellement, chaque commande peut avoir jusqu'a six arguments, mais les versions GNU semblent eliminer cette contrainte. 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 appres les autres sans inercaler d'espace, ainsi la commande .BR peut etre utilisee pour indiquer un mot en Gras suivi par un signe de ponctuation en Roman.

SECTIONS (PARAGRAPHES)
les sections commencent par .SH suivi de leurs titres. Si le titre contient des espaces, l'encadrer par des guillements. Les titres traditionnels sont : NOM, SYNOPSIS, DESCRIPTION, OPTIONS, FICHIERS, VOIR AUSSI, DIAGNOSTIQUE, BUGS, et AUTEUR. Le seul titre indispensable est NOM, qui doit etre suivi sur la ligne suivante par une courte description du programme :

    .SH NOM
    chess \- Jeu d'echec

Il est tres important que ce format soit respecte, et qu'il se trouve un backslash avant le tiret suivant le nom du programme. 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). NDT : Vous vous doutez bien que la version de distribution de makewhatis(8) ne reconnait 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 a apporter est decrite dans le fichier LISEZ_MOI, qui est livre avec l'archive des pages de manuel en francais.

AUTRES MACROS
D'autres macros sont disponibles :

.DT Tabulation par defaut.

.HP Debut d'indentation.

.IP Debut de paragraphe avec un mot-cle. C'est le meme format que .TP, sauf que le mot-cle est sur la meme ligne, pas sur la suivante.

.LP Comme .PP

.PD Fixe la distance entre paragraphe a la valeur fournie en argument

.PP Commencer un nouveau paragraphe

.RE Fin d'indentation relative (dans un paragraphe)

.RS Debut d'indentation relative (dans un paragraphe)

.SS Sous-titre, comme .SH, mais pour une sous-section

.TP Debut de paragraphe avec un mot-cle. Ce mot est sur la ligne suivante. Commande similaire a .IP

FICHIERS
/usr/local/lib/groff/tmac/tmac.an
/usr/man/whatis

VOIR AUSSI
groff(1), man(1), whatis(1), apropos(1), makewhatis(8)