Il vous vaut 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 :
/dev ;/etc/passwd) ;root) ;Le nom du fichier source d'une page de manuel (le fichier d'entrée du
système de formatage) est constitué du 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 devrez appeler votre fichier source
"passwd.5". Vous voyez ici qu'il peut exister un fichier
du même nom qu'une commande ; nous pourrions tout aussi bien
avoir une fonction de bibliothèque appelée "passwd".
L'organisation en sections constitue la méthode habituelle pour
résoudre ce type d'ambiguïté : la description de la commande se
trouvera dans le fichier "passwd.1" et notre hypothétique
fonction bibliothèque dans "passwd.3".
xman, par exemple,
affichera "xterm(x)" et "wish(tk)" dans la
liste des documents disponibles.
Attention aux éventuels conflits de noms avec des programmes,
fonctions ou fichiers existants. Ce serait par exemple une très
mauvaise idée que d'appeler votre nouvel éditeur de texte ed,
sed (pour "super ed") ou red (pour "Roger
Editions") ! En vous assurant que le nom de votre application est
unique, vous éviterez qu'un utilisateur exécute votre programme par
erreur ou lise sa page de manuel à la place de celle dont il désirait
prendre connaissance, ou vice versa. Vous pouvez éventuellement vous
aider de la base de données "lsm", qui recense beaucoup des
programmes disponibles pour Linux.
Maintenant que nous savons déterminer le nom de notre fichier, il nous
faut savoir dans quel répertoire l'installer (lorsque la personne
qui installera votre application tapera la commande "make
install" par exemple).
Sous Linux, toutes les pages de manuel sont situées dans des
sous-répertoires à partir d'une (ou plusieurs) racine indiquée dans la
variable d'environnement MANPATH. Les outils de traitement
de la documentation utilisent cette variable de la même manière
que le shell emploie PATH pour localiser les programmes
exécutables. En fait, MANPATH a exactement le même format que
PATH. Toutes deux contiennent une liste de répertoires,
avec le caractère deux-points comme élément séparateur (mais
MANPATH n'autorise pas de champs vides ou de chemins d'accès
relatifs).
Si MANPATH n'existe pas ou n'est pas exportée, le répertoire
/usr/man sera alors utilisé par défaut. Dans le but
d'accélérer les recherches et pour garder des répertoires de
taille raisonnable, les répertoires pointés par MANPATH
contiennent une série de sous-répertoires nommés "manS",
où S désigne le caractère correspondant au numéro de section que
nous avons présenté plus haut. Toutes les sections ne sont pas
représentées, il n'y a par exemple pas de raison de conserver une
entrée "mano". Vous pourrez y trouver également des
sous-répertoires appelés "catS", "dviS" et
"psS", qui contiennent la documentation toute formatée,
prête à être affichée ou imprimée : nous reviendrons sur ce sujet
plus loin. Le seul fichier qui peut être présent à côté de ces
sous-répertoires du répertoire de base s'appelle "whatis".
Nous décrirons son contenu et la manière de le créer plus tard.
La méthode la plus sûre pour installer au bon endroit une
page de manuel de la section "S" est de placer le
fichier dans le répertoire /usr/man/manS. Toutefois un
bon Makefile devra autoriser l'utilisateur à 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=/mon/option. Les pages de manuel
correspondantes seront alors installées à partir du répertoire de base
/mon/option/man. Nous vous conseillons d'employer une méthode
similaire pour vos réalisations personnelles.
Depuis l'avènement du "Système de fichiers standard" pour Linux (FSSTnd), les choses se sont un petit peu compliquées. Ce standard stipule que la structure de /usr/man doit être prévue pour plusieurs jeux de pages de manuels, correspondant à différents langages, en raison de l'internationalisation du système. Il est alors introduit un niveau d'arborescence supplémentaire qui distingue chaque langue. Voici ce qui est dit dans la version 1.2 de ce standard :
Consultez le standard pour obtenir les chaînes les plus courantes dans nos contrées. En fonction de ces recommandations, nous aurons donc 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 aussi ne les fournir que pour une seule langue.Le nom des sous-répertoires de langages de /usr/man est basé sur l'annexe E du standard POSIX 1003.1, qui décrit la chaîne d'identification locale ; celle-ci constituant la méthode la mieux acceptée pour décrire un environnement culturel. Cette chaîne locale est formée ainsi : <langage>[_<pays>][.<jeu-de-caracteres>][,<version>]
Toutefois, je (l'auteur du document, pas le traducteur) ne peut pas recommander d'employer cette structure en l'état actuel des choses. Le standard Linux indique aussi que "les systèmes n'utilisant qu'un seul langage et qu'un seul jeu de caractères pour toutes les pages de manuel peuvent omettre le sous-répertoire locale et stocker les fichiers dans mandir". Par exemple, sur les machines uniquement équipées pour la langue anglaise, qui n'utilise que le code ASCII, on peut placer les sous-répertoires man[1-9] directement dans /usr/man (en fait, il s'agit de l'emplacement traditionnel et c'est le cas le plus fréquent ; c'est ainsi que sont organisés tous les systèmes par défaut).
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.
Chapitre suivant, Chapitre Précédent
Table des matières de ce chapitre, Table des matières générale
Début du document, Début de ce chapitre