Les sections du manuel sont traditionnellement définies comme suit :

1 Commands (Programs) « Commandes (Programmes) »

Les commandes qui peuvent être exécutées par un utilisateur dans un interpréteur de commande (shell).

2 System calls « Appels système »

Les fonctions qui doivent être exécutées par le noyau.

3 Library calls « Appels bibliothèque »

La plupart des fonctions de la libc.

4 Special files (devices) « Fichiers spéciaux (Périphériques) »

Les fichiers que l'on trouve dans /dev.

5 File formats and conventions « Formats de fichiers et conventions »

Le format de /etc/passwd et tout autre fichier intelligible.

6 Games « Jeux »

7 Conventions and miscellaneous « Conventions et divers »

Aperçus sur divers sujets, conventions et protocoles, normes des jeux de caractères, et diverses autres choses.

8 System management commands « Commande de gestion du système »

Les commandes comme mount(8), la plupart n'étant exécutable que par le superutilisateur.

Les nouvelles phrases doivent débuter sur une nouvelle ligne. Cela permet de voir plus facilement l'effet des correctifs qui ne s'appliquent souvent qu'à une seule phrase.  

.TH titre section date source manuel

titre

Le titre de la page de manuel, écrit entièrement en lettres capitales (par exemple, MAN-PAGES).

section

Le numéro de la section dans laquelle doit être placée la page (par exemple, 7).

date

La date de la dernière révision --- rappelez-vous de la modifier chaque fois que vous effectuez une modification dans la page de manuel car c'est la manière la plus courante d'avoir un contrôle de version. Dans la version anglaise, les dates doivent être écrites sous la forme AAAA-MM-JJ.

source

L'origine de la commande, fonction ou appel système.

Pour les quelques pages des sections 1 et 8 du projet man-pages, vous devriez probablement n'écrire que GNU.

Pour les appels système, écrivez simplement Linux. (Une pratique précédente était d'indiquer la version du noyau pour laquelle la page avait été rédigée, vérifiée ou mise à jour. Toutefois, cela n'a jamais été fait de manière cohérente et était donc probablement pire que de ne pas indiquer de numéro de version. Désormais, évitez d'indiquer la version du noyau.)

Pour les fonctions de bibliothèque qui font partie de la glibc ou des autres bibliothèques GNU, utilisez simplement GNU C Library, GNU, ou même une chaîne vide.

Pour les pages de la section 4, utilisez Linux.

Lorsque vous avez un doute, écrivez tout simplement Linux, ou GNU.

manual

Le titre du manuel (par exemple, pour les sections 2 et 3 du paquet utilisez Linux Programmer's Manual en anglais et Manuel du programmeur Linux en français).

Pour la version originale en anglais :

NAME
SYNOPSIS
CONFIGURATION      [Normalement, seulement dans la section 4]
DESCRIPTION
OPTIONS            [Normalement, seulement dans les sections 1 et 8]
EXIT STATUS        [Normalement, seulement dans les sections 1 et 8]
RETURN VALUE       [Normalement, seulement dans les sections 2 et 3]
ERRORS             [Typiquement, seulement dans les sections 2 et 3]
ENVIRONMENT
FILES
VERSIONS           [Normalement, seulement dans les sections 2 et 3]
CONFORMING TO
NOTES
BUGS
EXAMPLE
SEE ALSO

NOM
SYNOPSIS
CONFIGURATION      [Normalement, seulement dans la section 4]
DESCRIPTION
OPTIONS            [Normalement, seulement dans les sections 1 et 8]
CODE DE RETOUR     [Normalement, seulement dans les sections 1 et 8]
VALEUR RENVOYÉE    [Normalement, seulement dans les sections 2 et 3]
ERREURS            [Typiquement, seulement dans les sections 2 et 3]
ENVIRONNEMENT
FICHIERS
VERSIONS           [Normalement, seulement dans les sections 2 et 3]
CONFORMITÉ
NOTES
BOGUES
EXEMPLE
VOIR AUSSI
TRADUCTION

La liste suivante indique le contenu de chacune des sections précédentes.

NAME (NOM)

Le nom de la page de manuel. Voir man(7) pour des détails importants sur la (les) lignes qui doi(ven)t suivre la commande .SH NAME.

SYNOPSIS

décrit brièvement l'interface de la commande ou de la fonction. Pour les commandes, ce paragraphe montre sa syntaxe et ses arguments (y compris les options). 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.

Lorsqu'une macro de test de fonctionnalité doit être définie afin d'obtenir la déclaration d'une fonction (ou d'une variable) à partir d'un fichier d'entête, le SYNOPSIS doit l'indiquer comme cela est décrit dans la page feature_test_macros(7).

CONFIGURATION

Les détails de configuration d'un périphérique. Cette section n'apparait normalement que dans les pages de la section 4.

DESCRIPTION

fournit une explication sur ce que le programme, 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 interne, sauf s'ils sont critiques pour comprendre l'interface. Décrit le cas principal ; pour les détails sur les options de la ligne de commande, on utilise le paragraphe OPTIONS.

OPTIONS

décrit les options de la ligne de commande acceptées par le programme et comment son comportement se modifie. Cette section ne devrait apparaître que dans les pages des sections 1 et 8.

EXIT STATUS (CODE DE RETOUR)

indique les codes de retour d'un programme et les conditions associées. Cette section ne devrait apparaître que dans les pages des sections 1 et 8.

RETURN VALUE (VALEUR RENVOYÉE)

Pour les pages des sections 2 et 3, donne une liste des valeurs qu'une routine de bibliothèque renverra à l'appelant et les conditions qui provoquent ces retours.

ERRORS (ERREURS)

Pour les pages des sections 2 et 3, il s'agit de la liste des valeurs qui peuvent être placées dans errno dans l'éventualité d'une erreur, avec une information sur ce qui provoque l'erreur. La liste des erreurs doit être ordonnée alphabétiquement.

ENVIRONMENT (ENVIRONNEMENT)

décrit toutes les variables d'environnement qui affectent le programme ou la fonction, ainsi que leurs effets.

FILES (FICHIERS)

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

VERSIONS

Un court résumé de la version du noyau Linux ou de la glibc où l'appel système ou la fonction de bibliothèque est apparu, ou dont le fonctionnement est modifié de manière significative.

CONFORMING TO (CONFORMITÉ)

décrit les normes ou les conventions suivies par la fonction ou la commande décrite dans la page de manuel. Pour une page des sections 2 ou 3, cette section doit indiquer la version de POSIX.1 à laquelle l'appel se conforme, et également si l'appel est spécifié par C99. (Ne vous souciez pas trop des autres standards comme SUS, SUSv2 et XPG, ou les standards d'implémentation SVr4 et BSD 4.x, à moins que l'appel ne soit spécifié dans ces standards et pas dans l'actuelle version de POSIX.1.) (Voir standards(7).)

Si l'appel n'est régit par aucun standard mais qu'il existe également sur d'autres systèmes, veuillez l'indiquer. Si l'appel est spécifique à Linux, veuillez l'indiquer.

NOTES

contient des notes diverses. Pour les pages de manuel des sections 2 et 3, vous pouvez trouver utile d'ajouter des sous-sections, nommées Linux Notes et Glibc Notes (Notes Linux et Notes glibc).

BUGS (BOGUES)

indique les limitations ou les défauts recensés, ainsi que les sujets à débat.

EXAMPLE (EXEMPLE)

donne un ou plusieurs exemples d'utilisation de la fonction, du fichier ou de la commande. Pour des détails sur la rédaction des programmes exemples, voir Programmes exemples plus loin.

AUTHOR (AUTEUR)

liste les auteurs de la documentation ou du programme. L'utilisation d'une section AUTHOR (ou AUTEUR) n'est pas encouragée. Généralement, il est préférable de ne pas encombrer chaque page avec une liste d'auteurs (parfois potentiellement nombreux) ; si vous écrivez ou modifiez significativement une page, ajouter une notice de copyright en tant que ligne commentée dans le haut du fichier source. Si vous êtes l'auteur d'un pilote de périphériques et que vous vouliez indiquer une adresse pour le signalement des bogues, veuillez le faire dans la section BOGUES.

SEE ALSO (VOIR AUSSI)

fournit une liste des pages de manuel ayant un rapport, dans l'ordre alphabétique, suivies d'autres documents éventuels.

TRADUCTION

le nom du traducteur. Si son adresse courriel n'est pas fournie, vous la trouverez dans le fichier LISEZ_MOI fourni 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 !

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, que ce soit des chemins ou des références à des fichiers du répertoire /usr/include) sont toujours en italique (par exemple <stdio.h>), sauf dans le paragraphe SYNOPSIS, où les fichiers inclus sont en gras (par exemple #include <stdio.h>). Lorsque vous faites référence à un fichier d'entête standard situé dans /usr/include, spécifiez le fichier d'entête entouré avec les symboles inférieur et supérieur, de la même manière que dans un fichier source C (par exemple, <stdio.h>).

Les macros spécifiques, généralement en lettres capitales, sont en gras (par exemple MAXINT). Exception : ne mettez pas en gras NULL.

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

Toute référence au sujet principal de la page en cours doit être écrite avec le nom en gras. S'il s'agit d'une fonction (par exemple, d'une page des sections 2 ou 3), le nom doit être suivi d'une paire de paranthèses en Roman. Par exemple, dans la page de manuel fcntl(2) les références au sujet de la page doivent être écrites comme ceci : fcntl(). La méthode préférée pour écrire cela dans le fichier source est :

    .BR fcntl ()

Toute référence à une autre page de manuel doit être écrite avec le nom en gras, toujours suivi par le numéro de section, en Roman, sans espace de séparation (par exemple : intro(2)). La méthode préférée pour écrire cela dans le fichier source est :

    .BR intro (2)

*

Les programmes exemples doivent être écrits en C.

*

Un programme exemple n'est seulement nécessaire et utile que s'il montre quelque chose au delà de ce qui peut être facilement fourni dans une description textuelle de l'interface. Un programme exemple qui ne fait rien d'autre qu'appeler une interface ne sert pas à grand chose.

*

Les programmes exemples doivent être relativement courts (de préférence moins de 100 lignes, idéalement moins de 50 lignes)

*

Les programmes exemples doivent effectuer des vérifications d'erreur en testant les valeurs renvoyées par les appels système ou les fonctions de la bibliothèque.

*

Les programmes exemples doivent être complets et compiler sans avertissement lorsqu'ils sont compilés avec cc -Wall.

*

Lorsque c'est possible et approprié, les programmes exemples doivent permettre des expérimentations en faisant évoluer leur comportement basé sur les entrées (idéalement avec les arguments de la ligne de commande, ou éventuellement avec une lecture de l'entrée par le programme).

*

Les programmes exemples doivent se conformer au style Kernighan et Ritchie, avec une indentation de 4 espaces.

Pour des exemples sur ce à quoi de tels programmes exemples doivent ressembler, consultez wait(2) et pipe(2).  

Ce document est une traduction réalisée par Alain Portal <aportal AT univ-montp2 DOT fr> le 24 novembre 2007 et révisée le 8 janvier 2008.

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

NOM

SYNOPSIS

DESCRIPTION

Sections des pages de manuel

Paquetage de macros

Conventions pour le fichier source

Ligne de titre

Sections dans une page de manuel

Conventions typographiques

Programmes exemples

Indentation des définitions de structure, session shell, etc.

EXEMPLE

VOIR AUSSI

TRADUCTION