Les sources de documentation

Avant de pouvoir comprendre ce qui se passe réellement en cas de problème, il faut connaître le rôle théorique de chaque programme impliqué. Pour cela, rien de tel que de consulter leurs documentations ; mais celles-ci étant multiples et dispersées, il convient de les connaître toutes.

7.1.1.Les pages de manuel

CULTURE

RTFM

Ce sigle est l'abréviation deRead The F…ing Manual(« Lis le f**tu manuel »), mais on rencontre parfois une variante moins grossière avecRead The Fine Ma-nual(« Lis le fameux manuel »). Des traductions alternatives comme « Relis Trois Fois le Manuel » existent aussi. Cee interjection sert parfois de réponse (laconique) à des questions en provenance de débutants ; elle est assez abrupte et laisse transparaître une certaine irritation par rapport à une question posée par quelqu'un qui n'a pas pris la peine de lire la documentation. D'autres per-sonnes affirment que cee réponse classique vaut mieux qu'aucune réponse (puisqu'elle indique que la documentation contient l'information recherchée), voire qu'une réponse courroucée plus développée.

Dans tous les cas, lorsqu'on se voit répondre « RTFM », il est souvent judicieux de ne pas s'offusquer. Et cee réponse pouvant être perçue comme vexante, on s'efforcera de ne pas la susciter. Si l'information requise n'est pas dans le ma-nuel, ce qui peut arriver, il conviendra au contraire de le préciser (de préférence dans la question initiale) ; on décrira également le cheminement suivi lors de la recherche d'informations effectuée personnellement avant de poser la ques-tion sur un forum. On pourra pour cela suivre quelques recommandaques-tions de bon sens, formalisées par Eric Raymond.

è http://www.gnurou.org/writing/smartquestionsfr

Les pages de manuel, relativement austères de prime abord, regroupent pourtant une foule d'in-formations indispensables. Présentons rapidement la commande qui permet de les consulter. Il s'agit deman page-manueloù le nom de la page de manuel est le plus souvent celui de la com-mande à découvrir. Pour se renseigner sur les options possibles de la comcom-mandecp, on tapera donc la commandeman cpà l'invite de l'interpréteur de commandes (voir encadré).

B.A.BA

Interpréteur de commandes

Un interpréteur de commandes — souvent désigné par shell en anglais — est un programme qui exécute les commandes saisies par l'utilisateur ou stockées dans un script. En mode interactif, il affiche une invite (finissant généralement par $pour un utilisateur normal, ou par #pour l'administrateur) indiquant qu'il est prêt à lire une nouvelle commande. L' annexe B, « Petit cours de rat-trapage »page 481 décrit les bases de l'utilisation de l'interpréteur de com-mandes.

L'interpréteur de commandes le plus usité est probablement bash (Bourne Again SHell) mais d'autres existent :dash,csh,tcsh,zsh, etc.

La plupart des shells offrent en outre des fonctionnalités d'assistance à la sai-sie, comme la complétion des noms de commandes ou de fichiers (qu'on active généralement par des tabulations successives), ou encore la gestion d'un his-torique des commandes déjà exécutées.

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

1. commandes exécutables depuis l'interpréteur ; 2. appels système (fonctions fournies par le noyau) ;

3. fonctions de bibliothèques (fournies par les bibliothèques système) ;

4. périphériques (sous les systèmes dérivés d'Unix, ce sont des fichiers spéciaux, habituelle-ment placés sous/dev/) ;

5. fichiers de configuration (formats et conventions) ; 6. jeux ;

7. ensemble de macros et de standards ; 8. commandes d'administration système ; 9. routines du noyau.

Il est possible de préciser la section de la page de manuel recherchée : pour consulter la docu-mentation de l'appel systèmeread, on tapera doncman 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 shadowrenvoieshadow(5)parce qu'il n'y a pas de pages de manuelshadowdans les sections 1 à 4.

ASTUCE whatis

Si vous ne voulez pas consulter la page de manuel complète mais obtenir uni-quement une description courte de la commande pour confirmer qu'il s'agit bien de celle que vous cherchez, tapez simplementwhatis commande.

$ whatis scp

scp (1) - secure copy (remote file copy program)

Cee description courte — présente dans toutes les pages de manuel — se re-trouve dans la sectionNAME(ouNOM) qui les débute toutes.

É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 commandeapropos, 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.aproposrenvoie 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.

Ex. 7.1 Retrouvercpavecapropos

$ apropos "copy file"

cp (1) - copy files and directories cpio (1) - copy files to and from archives hcopy (1) - copy files from or to an HFS volume install (1) - copy files and set attributes

ASTUCE

Naviguer de proche en proche

Beaucoup de pages de manuel disposent d'un paragrapheSEE ALSOou VOIR AUSSI, généralement à la fin. Il renvoie vers d'autres pages de manuel portant sur des notions ou commandes proches de celle en cours d'examen, ou vers des documentations externes. Il est ainsi possible de retrouver la documentation pertinente même quand le premier choix n'est pas optimal.

La commandemann'est plus le seul moyen de consulter les pages de manuel, car les programmes

konqueror(sous KDE) et^yelp(sous GNOME) offrent également cette possibilité. On trouve en-core une interface web, fournie par le paquetman2html : les pages de manuel sont alors consul-tables à l'aide d'un navigateur. Sur l'ordinateur contenant le paquet, utilisez cette URL :

èhttp://localhost/cgi-bin/man/man2html

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.

CHARTE DEBIAN

Pages de manuel obligatoires

Debian impose à chaque programme d'être accompagné d'une page de manuel.

Si l'auteur amont ne la fournit pas, le développeur Debian rédige en général une page minimaliste qui renverra au moins le lecteur à l'emplacement de la documentation originale.

7.1.2.Documentation au formatinfo

Le projet GNU a rédigé les manuels de la plupart de ses programmes au formatinfo ; c'est pour-quoi de nombreuses pages de manuel renvoient vers la documentationinfocorrespondante. Ce format offre quelques avantages mais le programme qui permet de consulter ces documenta-tions est également un peu plus complexe.

Il s'appelle évidemment infoet on l'invoque en lui passant le nom du « nœud » à consulter.

En effet, cette documentation a une structure hiérarchique etinfoinvoqué sans paramètres affichera la liste des nœuds disponibles au premier niveau. Habituellement, un nœud porte le nom de la commande correspondante.

Les commandes de navigation dans la documentation ne sont pas très intuitives. La meilleure méthode pour se familiariser avec le programme est sans doute de l'invoquer puis de taperh

(pourhelp, ou demande d'aide) et de suivre les instructions pour apprendre par la pratique. Al-ternativement, vous pouvez aussi employer un navigateur graphique, beaucoup plus convivial.

À nouveau,konqueroretyelpconviennent ; le paquetinfo2wwwfournit également une inter-face web.

èhttp://localhost/cgi-bin/info2www

On notera que le systèmeinfone permet pas de traduction, à l'opposé du système de pagesman. Ses pages sont donc systématiquement en anglais. En revanche, lorsqu'on demande au pro-gramme d'afficher une page infoinexistante, 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.

7.1.3.La documentation spécifique

Chaque paquet intègre sa documentation spécifique : même les logiciels les moins bien docu-mentés disposent en général au moins d'un fichierREADME(« lisez-moi ») contenant quelques informations intéressantes et/ou importantes. Cette documentation est installée dans le réper-toire/usr/share/doc/paquet/(oùpaquetreprésente le nom du paquet). Si elle est très volu-mineuse, 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 fichierREADME.Debian si-gnale ainsi toutes les adaptations effectuées pour être en conformité avec la charte Debian. Le fichierchangelog.Debian.gzpermet quant à lui de suivre les modifications apportées au pa-quet au fil du temps : il est très utile pour essayer de comprendre ce qui a changé entre deux ver-sions installées et qui n'ont apparemment pas le même comportement. Enfin, on trouve parfois

un fichierNEWS.Debian.gzdocumentant les changements majeurs du programme qui peuvent concerner directement l'administrateur.

7.1.4.Les sites web

Dans la majorité des cas, un logiciel libre dispose d'un site web pour le diffuser et fédérer la com-munauté de ses développeurs et utilisateurs. Ces sites regorgent souvent d'informations perti-nentes sous différentes formes : les documentations officielles, les foires aux questions (FAQ), les archives des listes de diffusion relatives au logiciel, etc. Fréquemment, un problème rencon-tré aura déjà fait l'objet de nombreuses questions ; la FAQ ou les archives de l'une des listes de diffusion en abriteront alors la solution. Une bonne maîtrise d'un moteur de recherche s'avé-rera précieuse pour trouver rapidement les pages pertinentes (en restreignant éventuellement la recherche au domaine ou sous-domaine Internet dédié au logiciel). Si le moteur renvoie trop de pages ou si les réponses ne correspondent pas à ce qui est attendu, l'ajout du mot-clédebian

permet de restreindre les réponses en ciblant les informations concernant les utilisateurs de ce système.

ASTUCE

De l'erreur à la solution

Si le logiciel renvoie un message d'erreur très spécifique, saisissez-le dans un moteur de recherche (entre apostrophes doubles « " » pour ne pas rechercher les mots individuellement, mais l'expression complète) : dans la majorité des cas, les premiers liens renvoyés contiendront la réponse que vous cherchez.

Dans d'autres cas, on aura simplement une erreur très générique comme « Per-mission non accordée » ; il conviendra alors de vérifier les per« Per-missions des élé-ments en jeu (fichiers, identité des utilisateurs, groupes, etc.).

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 champHomepagen'est pas présent dans les méta-informations du paquet (apt-cache 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 tel que Freecode (anciennement Freshmeat) ou Framasoft, ou encore directement effectuer une recherche sur un moteur comme Google ou Yahoo.

èhttp://freecode.com/

èhttp://framasoft.org/

Pensez également à consulter le wiki du projet Debian. Il s'agit d'un site collaboratif où même de simples visiteurs peuvent faire des suggestions depuis un navigateur. Il sert aussi bien aux

développeurs pour spécifier des projets qu'aux utilisateurs pour partager leurs connaissances en rédigeant collaborativement des documents.

èhttp://wiki.debian.org/

7.1.5.Les tutoriels (HOWTO)

Unhowto(« comment faire ») est une documentation décrivant concrètement, étape par étape, comment atteindre un but prédéfini. Les buts couverts sont relativement variés mais souvent techniques : mettre en place l'IP Masquerading(masquage d'IP), configurer le RAID logiciel, ins-taller un serveur Samba, etc. Ces documents essaient souvent de couvrir l'ensemble des problé-matiques susceptibles de se produire dans la mise en œuvre d'une technologie donnée.

Ces tutoriels sont gérés par leLinux Documentation Project(projet de documentation Linux, LDP), dont le site web abrite donc l'ensemble de ces documents :

èhttp://www.tldp.org/

Restez critique en lisant ces documents. Ils sont fréquemment vieux de plusieurs années ; leurs informations seront donc parfois obsolètes. Ce phénomène est encore plus fréquent pour leurs traductions, puisque les mises à jour de ces dernières ne sont ni systématiques ni instantanées après la publication d'une nouvelle version du document original — cela fait partie des joies de travailler dans un environnement bénévole et sans contraintes…