Page suivantePage précédenteTable des matières

4. Comment documenter plusieurs choses dans une seule page de manuel ?

De nombreux programmes (grep, egrep) et fonctions (printf, fprintf,...) sont documentées dans une seule page de manuel. Cependant, ces pages seraient inutilisables si elles n'étaient accessibles que par un seul nom. Nous ne pouvous nous attendre à ce qu'un utilisateur se souviennent que la page de manuel de egrep est en fait celle de grep. Il est par conséquent indispensable que la page soit accessible sous différents noms. Vous avez plusieurs possibilités pour y arriver :

  1. avoir des copies identiques pour chaque nom ;
  2. connecter toutes les pages de manuels en utilisant des liens physiques ;
  3. utiliser les liens symboliques pointant la page de manuel ;
  4. utiliser le mécanisme de "source" de groff fournie par la macro ".SO".
La première possibilité est une perte de place. La deuxième n'est pas recommandée parce que les versions intelligentes du programme catman peuvent gagner beaucoup de temps en regardant le type du fichier et son contenu. Les liens physiques réduiraient l'efficacité de cet outil (dont le but est de formater toutes les pages de manuel pour qu'elles soient affichées plus rapidement). La troisième alternative comporte un piège si vous êtes concerné par la portabilité, vous devez savoir qu'il existe des systèmes de fichiers qui ne supportent pas les liens symboliques. En bref, la Meilleure Chose (TM) est d'utiliser le mécanisme source de groff.

Voila comment l'utiliser : si vous voulez que votre page soit accessible sous les noms truc et bidule dans la section 1, alors mettez la page de manuel dans truc.1 et réalisez le fichier bidule.1 contenant :

 .SO man1/truc.1
Il est important de spécifier le répertoire man1/ aussi bien que le nom du fichier truc.1 car lors de l'exécution de groff, celui-ci aura comme répertoire courant le répertoire de base des pages de manuel, et il interprètera les arguments de .SO comme étant relatifs à cet emplacement.


Page suivantePage précédenteTable des matières