Man page HOWTO: Comment accède-t-on aux pages de manuel ?

2. Comment accède-t-on aux pages de manuel ?

Vous devez connaître avec précision le mécanisme d'accès aux pages de manuel afin de savoir donner un nom correct à vos documents, et d'être capable de les installer au bon endroit. Chaque page de manuel appartient à une section spécifique, dénotée par un simple chiffre. Les sections les plus courantes rencontrées sous Linux sont :

1 : commandes utilisateurs pouvant être exécutées par tout le monde ;
2 : appels systèmes, c'est-à-dire les fonctions fournies par le noyau ;
3 : fonctions des bibliothèques ;
4 : périphériques, c'est-à-dire les fichiers spéciaux que l'on trouve dans le répertoire /dev ;
5 : descriptions des formats de fichiers (comme par exemple /etc/passwd ;
6 : les jeux, sans commentaire...
7 : divers (macros, conventions particulières, ...) ;
8 : outils d'administration exécutables uniquement par le super utilisateur ;
9 : un autre endroit (spécifique à Linux) destiné à la documentation des services offerts par le noyau ;
n : nouvelle documentation, qui pourra être déplacée vers un endroit approprié ;
o : ancienne documentation, qui peut être conservée encore un certain temps ;
l : documentation locale, propre à ce système particulier.

Le nom du fichier source d'une page de manuel (le fichier d'entrée du système de formatage) est le nom de la commande décrite (ou de la fonction, du fichier, etc.), suivi d'un point et du numéro de section. Si, par exemple, vous documentez le format du fichier "passwd", vous devez appeler le fichier source "passwd.5". Nous avons ici un exemple d'un fichier qui porte le même nom qu'une commande ; nous aurions tout aussi bien avoir une fonction de bibliothèque appelée "passwd". L'organisation en sections constitue la méthode habituelle pour résoudre ces ambiguïtés : la description de la commande se trouvera dans le fichier "passwd.1" et notre hypothétique fonction de bibliothèque dans "passwd.3".

Quelquefois, une lettre est ajoutée au numéro de section comme par exemple "xterm.1x" ou "wish.1tk". Le but de cette notation est d'indiquer qu'il s'agit respectivement d'une documentation d'un programme X Window ou d'une application Tk. Certains programmes d'affichage du manuel peuvent exploiter cette particularité ; xman, par exemple affichera "xterm(x)" et "wish(tk)" dans la liste des documents disponibles.

S'il vous plaît, n'utilisez pas les sections n, o et l : selon le standard du système de fichiers (File System Standard), ces sections sont déconseillées, utilisez plutôt les sections numériques.

Attention aux éventuels conflits de noms avec des programmes, fonctions ou fichiers déjà existants. Ce serait certainement une mauvaise idée d'écrire un autre éditeur de texte et de le nommer ed, sed (pour super ed) ou red (pour Roger edition). En vous assurant que le nom de votre programme est unique, vous éviterez que quelqu'un exécute votre programme et qu'il lise la page de manuel d'un autre ou vice verca. Vous pouvez éventuellement vous aider de la base de données "lsm" qui recense beaucoup de programmes disponibles pour Linux.

Maintenant que nous savons quel nom donner à notre fichier, la prochaine décision est de choisir le répertoire dans lequel nous l'installerons (quand l'utilisateur lancera la commande "make install"). Sous Linux, toutes les pages de manuel sont dans des sous-répertoires à partir d'une racine mémorisée dans la variable d'environnement MANPATH. Les outils de traitement de la documentation l'utilisent de la même manière que le shell utilise la variable PATH pour trouver les exécutables. En fait, MANPATH a le même format que PATH : toutes les deux sont une liste de répertoires séparés par des ":" (mais MANPATH n'autorise pas de champs vides ou des chemins relatifs, seulement des chemins absolus). Si MANPATH n'existe pas ou si elle n'est pas exportée, /usr/man est utilisée comme valeur par défaut. Dans le but d'accélerer la recherche et pour garder les répertoires de taille raisonable, les répertoires pointés dans MANPATH (aussi appelés répertoires de base) contiennent une multitude de sous-répertoires nommés "man<s>" où <s> désigne le caractère correspondant à la section présenté plus haut. Toutes les sections ne sont pas représentées, il n'y a pas, par exemple de raison de garder une entrée "mano". Vous pourrez y trouver également des sous-répertoires appelés "cat<s>", "dvi<s>" et "ps<s>", qui contiennent toute la documentation formatée, prête à être affichée ou imprimée : nous reviendrons sur ce sujet plus loin. Le seul fichier à être présent à côté de ces sous-répertoires du répertoire de base s'appelle "whatis". Le but et la création de ce fichier sera décrit dans la section 11. La méthode la plus sûre pour installer au bon endroit une page de manuel de la section "s" est de mettre le fichier dans le répertoire "/usr/man/man<s>". Toutefois, un bon Makefile devra autoriser l'utilisateur de choisir un autre répertoire de base, disons par exemple par le biais d'une variable d'environnement que l'on pourrait nommer MANDIR. La plupart des distributions GNU peuvent être configurées à l'aide de l'option --prefix=/nom/option. Les pages de manuels correspondantes seront alors installées à partir du répertoire de base /mon/option/man. Je vous suggère d'utiliser une méthode similaire pour vos réalisations personnelles.

Depuis l'avènement du "Système de fichiers standard" pour Linux (FS-STnd), les choses se sont compliquées. Le FS-STnd 1.2 stipule que :

des aménagements doivent être faits dans la structure de /usr/man pour supporter des pages de manuel écrites dans différentes (ou mutiples) langues.

Ceci est fait en introduisant un niveau de répertoires supplémentaire qui distingue les différentes langues. Citant encore le FS-Stnd 1.2 :

Le nommage des sous-répertoires correspondants aux langues de /usr/man est basé sur l'appendice E du standard POSIX 1003.1 qui décrit la chaîne de caractères d'authentification locale (qui est la méthode la mieux acceptée pour décrire un environement culturel). La chaîne locale se présente sous la forme
            <langage>[_<pays>][.<jeu-de-caracteres>][,<version>]
          

(Reportez vous au FS-Stnd pour voir quelques chaînes localecourantes.) D'après ces recommandations, nous avons nos pages de manuel dans /usr/man/<locale>/man[1-9lno]. Les versions formatées se trouveraient alors bien entendu dans /usr/man/<locale>/cat[1-9lno] : nous pourrions ne les fournir que pour une seule langue.

TOUTEFOIS, je (l'auteur du document, pas le traducteur) ne peut pas recommander de passer a cette structure en l'état actuel des choses. Le FS-Stnd 1.2 autorise aussi que

les systèmes qui n'utilisent qu'une seule langue et jeu de caractères pour toutes les pages de manuel peuvent omettre la sous-chaîne <locale> et stocker toutes ces pages dans le répertoire mandir. Par exemple, les machines équipées seulement de pages de manuel en anglais codées en ASCII peuvent mettre les pages de manuel (les répertoires man[1-9]) directement dans /usr/man/. Il s'agit en fait de l'arrangement habituel.

Je (l'auteur du document, pas le traducteur) ne changerai pas ma configuration tant que tous les outils (comme xman, info, tkman et beaucoup d'autres) ne seront pas tous adaptés à cette nouvelle structure.