Chapitre 7. Résolution de problèmes et sources d'informations

Les pages de manuel, relativement austères de prime abord, regroupent pourtant une foule d'informations indispensables. Présentons rapidement la commande, fournie par le paquet man-db, qui permet de les consulter. Il s'agit de man page-manuel où le nom de la page de manuel est le plus souvent celui de la commande à découvrir. Pour se renseigner sur les options possibles de la commande cp, on tapera donc la commande man cp à l'invite de l'interpréteur de commandes (voir encadré B.A.-BA Interpréteur de commandes).

Les pages de manuel ne documentent pas uniquement les commandes et programmes accessibles en ligne de commande, mais aussi les fichiers de configuration, les appels système, les fonctions de bibliothèque, etc. Des collisions de noms surviennent donc. Ainsi, la commande read de l'interpréteur de commandes s'appelle comme l'appel système read. C'est pourquoi les pages de manuel sont classées dans des sections numérotées :

Il est possible de préciser la section de la page de manuel recherchée : pour consulter la documentation de l'appel système read, on tapera donc man 2 read. En l'absence d'une section explicite, c'est la première section abritant une page du nom demandé qui sera utilisée. Ainsi, man shadow renvoie shadow(5) parce qu'il n'y a pas de pages de manuel shadow dans les sections 1 à 4.

$ whatis scp
scp (1)              - OpenSSH secure file copy

Évidemment, si vous ne connaissez pas les noms des commandes, le manuel ne vous sera pas d'un grand secours. C'est l'objet de la commande apropos, qui permet de mener une recherche dans les pages de manuel, ou plus précisément dans leurs descriptions courtes : chaque page de manuel commence en effet par un résumé en une ligne des fonctions documentées plus en détail par la suite. apropos renvoie donc une liste des pages de manuel dont la description mentionne le ou les mots-clés demandés. En choisissant bien ceux-ci, on trouvera le nom de la commande recherchée.

$ apropos "copy file"
cp (1)               - copy files and directories
cp (1posix)          - copy files
cpio (1)             - copy files to and from archives
exec (1posix)        - execute commands and open, close, or copy file descriptors
install (1)          - copy files and set attributes
ntfscp (8)           - copy file to an NTFS volume.

The man command is not the only means of consulting the manual pages, since khelpcenter and konqueror (by KDE) and yelp (under GNOME) programs also offer this possibility. There is also a web interface, provided by the man2html package, which allows you to view manual pages in a web browser. On a computer where this package is installed, use this URL after following the instructions in /usr/share/doc/man2html/README.Debian:

Cet utilitaire a donc besoin d'un serveur web. C'est pourquoi vous choisirez d'installer ce paquet sur l'un de vos serveurs : tous les utilisateurs du réseau local bénéficieront du service (y compris les postes non Linux) et vous éviterez de devoir mettre en place un serveur HTTP sur chaque poste. Par ailleurs, si votre serveur est accessible depuis l'extérieur, il peut être souhaitable de restreindre l'accès à ce service aux seuls utilisateurs du réseau local.

Last but not least, you can view all manual pages available in Debian (even those that are not installed on your machine) on the manpages.debian.org service. It offers each manual page in multiple versions, one for each Debian release.

Le projet GNU a rédigé les manuels de la plupart de ses programmes au format info ; c'est pourquoi de nombreuses pages de manuel renvoient vers la documentation info correspondante. Ce format offre quelques avantages mais le programme par défaut qui permet de consulter ces documents (appelé info) est également un peu plus complexe. Il est recommandé d'utiliser pinfo à la place (dans le paquet pinfo).

La documentation info a une structure hiérarchique et pinfo invoqué sans paramètres affichera la liste des nœuds disponibles au premier niveau. Habituellement, un nœud porte le nom de la commande correspondante.

Dans pinfo, la navigation entre les nœuds se fait simplement avec les touches flèches. Alternativement, vous pouvez aussi employer un navigateur graphique, beaucoup plus convivial. À nouveau, konqueror et yelp conviennent ; le paquet info2www fournit également une interface web.

On notera que le système info ne permet pas de traduction, contrairement au système de pages man. Ses pages sont donc presque systématiquement en anglais. Cependant, lorsqu'on demande au programme pinfo d'afficher une page info inexistante, il se rabattra sur la page man du même nom, si celle-ci existe ; cette dernière pourra donc éventuellement exister en français.

Chaque paquet intègre sa documentation spécifique : même les logiciels les moins bien documentés disposent en général au moins d'un fichier README (« lisez-moi ») contenant quelques informations intéressantes et/ou importantes. Cette documentation est installée dans le répertoire /usr/share/doc/paquet/ (où paquet représente le nom du paquet). Si elle est très volumineuse, elle peut ne pas être intégrée au paquet du programme mais constituer son propre paquet, alors intitulé paquet-doc. Le paquet du programme recommande en général le paquet de documentation pour le mettre en exergue.

Dans le répertoire /usr/share/doc/paquet/ se trouvent également quelques fichiers fournis par Debian qui complètent la documentation du point de vue des particularités ou améliorations du paquet par rapport à une installation traditionnelle du logiciel. Le fichier README.Debian signale ainsi toutes les adaptations effectuées pour être en conformité avec la charte Debian. Le fichier changelog.Debian.gz permet quant à lui de suivre les modifications apportées au paquet au fil du temps : il est très utile pour essayer de comprendre ce qui a changé entre deux versions installées et qui n'ont apparemment pas le même comportement. Enfin, on trouve parfois un fichier NEWS.Debian.gz documentant les changements majeurs du programme qui peuvent concerner directement l'administrateur (voir Section 6.7.2, « Gérer les problèmes consécutifs à une mise à jour »).

In most cases, free software programs have websites that are used to distribute it and to bring together the community of its developers and users. These sites are frequently loaded with relevant information in various forms: official documentation, FAQ (Frequently Asked Questions), mailing list archives, etc. Problems that you may encounter have often already been the subject of many questions; the FAQ or mailing list archives may have a solution for it. A good mastery of search engines will prove immensely valuable to find relevant pages quickly (by restricting the search to the Internet domain or sub-domain dedicated to the program). If the search returns too many pages or if the results do not match what you seek, you can add the keyword debian to limit results and target relevant information.

Si vous ne connaissez pas l'adresse du site web du logiciel, il y a différents moyens de l'obtenir. Vérifiez en premier lieu si un champ Homepage n'est pas présent dans les méta-informations du paquet (apt show paquet). Alternativement, la description du paquet peut contenir un pointeur sur le site web officiel du logiciel. Si aucune URL n'y est indiquée, il convient alors d'examiner /usr/share/doc/paquet/copyright. Le mainteneur Debian y mentionne en effet l'endroit où il a récupéré le code source du programme et il est probable qu'il s'agisse justement du site web en question. Si à ce stade votre recherche est toujours infructueuse, il faut consulter un annuaire de logiciels libres comme celui de la FSF ou Framasoft, ou encore directement effectuer une recherche sur un moteur comme Google ou Yahoo.

You might also want to check the Debian wiki, a collaborative website where anybody, even new visitors, can make suggestions directly from their browsers. It is used equally by developers who design and specify their projects, and by users who share their knowledge by writing documents collaboratively.

A HOWTO is a document that describes, in concrete terms and step by step, “how to” reach a predefined goal. The covered goals are relatively varied, but often technical in nature: for example, setting up IP Masquerading, configuring software RAID, installing a Samba server, etc. These documents often attempt to cover all of the potential problems likely to occur during the implementation of a given technology.

Many such tutorials are managed by the Linux Documentation Project (LDP), whose website hosts all of these documents:

Debian also provides tutorials for its users:

All these documents should be taken with a grain of salt. They are often several years old; the information they contain is sometimes obsolete. This phenomenon is even more frequent for their translations, since updates are neither systematic nor instant after the publication of a new version of the original documents. Further many tutorials nowadays are provided by bloggers, sharing their individual solution with the interested reader. They often lack important information, i.e. the reason why some configuration has been chosen over another, or why some option has been enabled or disabled. Because blogging and creating personal websites made it so easy to share, many of these often short tutorials exist, but only a few are actively maintained and well-kept. This can make it hard to find the "right" one for you. This is all part of the joys of working in a volunteer environment and without constraints…