MAN-PAGES

Section : Manuel du programmeur Linux (7)
Mise à jour de la version anglaise : 12 juin 2008
Index Menu principal  

NOM

man-pages - Conventions pour la rédaction de pages de manuel Linux  

SYNOPSIS

man [section] titre  

DESCRIPTION

Cette page décrit les conventions à suivre lors de la rédaction de pages de manuel pour le projet man-pages Linux qui comporte les sections 2, 3, 4, 5 et 7 des pages de manuel Linux. Les conventions décrites ici peuvent être utiles aux auteurs dans la rédaction de pages de manuel dans d'autres projets.

 

Sections des pages de manuel

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.

 

Paquetage de macros

Les nouvelles pages doivent être balisées en utilisant le paquetage groff an.tmac décrit dans man(7). Ce choix est principalement dû à des raisons de cohérence : une très grande majorité des pages de manuel Linux existantes sont balisées avec ces macros.  

Conventions pour le fichier source

Veuillez limiter la longueur des lignes à 75 caractères dans le fichier source, lorsque c'est possible. Cela permet d'éviter les coupures de ligne dans certains clients courriels lorsque des correctifs sont envoyés à l'intérieur du courriel.

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.  

Ligne de titre

La première commande d'une page de manuel doit être la commande TH :

.TH titre section date source manuel

où :

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

 

Sections dans une page de manuel

La liste ci-dessous indique les sections conventionnelles ou suggérées. La plupart des pages de manuel devraient au moins inclure les sections mises en évidence. Veuillez faire l'effort d'ordonner les sections comme suit dans une nouvelle page de manuel.

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

Pour la version française :

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

Voici donc une mise en page traditionnelle, veuillez l'utiliser ; 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 (Cela peut être utile particulièrement pour les pages des sections 4 et 5). Toutefois, avant de le faire, regardez bien si vous ne pouvez pas utiliser les titres traditionnels, avec des sous-sections (.SS) dans ces sections.

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. De manière générale, la page de manuel de chaque nouvelle interface devrait inclure une section VERSIONS. Malheureusement, bien des pages de manuel existantes n'incluent pas cette information (car il n'y avait pas de politique pour le faire lors qu'elles ont été rédigées). Les correctifs pour y remédier sont les bienvenus. Dans la perpective d'écriture de nouveau code, cette information n'a de sens que dans le cas d'interface noyau ajoutée à Linux 2.4 ou suivant (c'est-à-dire les modifications depuis la version 2.2 du noyau), et les fonctions de la bibliothèque ajoutées dans Linux 2.4 ou suivant (c'est-à-dire les modifications depuis la version 2.0 de la glibc),

La page de manuel syscalls(2) fournit également des informations de versions de noyau dans lesquelles sont apparus les appels système.

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 !

 

Conventions typographiques

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 variables devraient, tout comme les noms d'argument, être formatés en italique.

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.

Les commandes complètes devraient, si elles sont longues, être écrites sous forme identée, par exemple

man 7 man-pages

Si la commande est courte, elle peut être incluse dans le texte, en italique, par exemple, man 7 man-pages. Dans ce cas, il peut être intéressant d'utiliser des espaces insécables (« \  ») aux endroits appropriés dans la commande. Les options des commandes doivent elles aussi être formatées en italique, par exemple, -l.

Les expressions, si elles ne sont pas écrites sur une ligne identée, devraient être mises en italique. Ici aussi, l'utilisation d'espaces insécables est appropriée si l'expression est mélangée à du texte normal.

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

(L'utilisation de ce format plutôt que « \fB...\fP() » rend plus facile l'écriture d'outils d'analyse des fichiers source des pages de manuel.

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)

(Inclure le numéro de section dans les références croisées permet aux outils comme man2html de créer correctement les hyperliens.)  

Programmes exemples

Les pages de manuel peuvent comporter des programmes exemples montrant l'utilisation d'un appel système ou d'une fonction de la bibliothèque. Toutefois, veuillez noter ce qui suit :

*

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

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

Lorsque des définitions de structure, des sorties de seesion shell, etc. sont inclus dans le texte courant, indentez-les avec 4 espaces (c'est-à-dire un bloc entouré par .in +4n et .in).  

EXEMPLE

Pour des exemples canoniques sur ce à quoi les pages de manuel du paquet man-pages doivent ressembler, consultez pipe(2) et fcntl(2).  

VOIR AUSSI

man(1), man2html(1), groff(7), groff_man(7), man(7), mdoc(7)  

TRADUCTION

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

 

Index

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