7 À l’aide !
Sommaire 7.1 Quoi fait quoi ? 7.2 Les pages de manuel 7.3 Le format info 7.4 Le logiciel 7.5 Les HOWTO
7.6 La documentation en ligne
? h Sorry, I already gave what help I could...
Maybe you should try asking a human?
TEX Version 3.14159.
L
’austéritéd’un terminal laisse pantois nombre d’utilisateurs affrontant pour la première fois un système Unix. Combien de fois l’Unixien n’a-t-il pas entendu un utilisateur se plaindre du manque de convivialité du système par rapport à ses« concurrents » intégrant aide en ligne, lignes chaudes et autres systèmes d’assistance à l’utilisateur ? Ce chapitre a donc pour principal objectif de tordre le cou à cette idée d’indisponibilité d’information.
7.1 Quoi fait quoi ?
unixfournit une pléthore de commandes. En shellbash, par exemple, le fait d’ap-puyer par deux fois sur la touche tabulation dans un terminal provoque l’apparition du message :
There are 2727 possibilities. Do you really wish to see them all? (y or n)
L’interpréteur de commande signifie par là qu’il nous donne la possibilité de choisir parmi 2727 commandes différentes et ayant a priori toutes une action différente.
Dans cette section, nous ne donnerons pas la signification et l’action de chacune de ces 2727 commandes mais plutôt le moyen de vous permettre d’accéder à l’informa-tion concernant chacune d’entre elle. En effet, l’un des principaux avantages d’unix est de permettre l’accès à ce genre d’informations.
7.1.1 À propos
La première question est probablement de savoir ce que vous désirez faire. Sup-posons que vous cherchiez à visualiser le contenu de votre répertoire de travail.
181
7
7 À l’aide !
Sommaire 7.1 Quoi fait quoi ? 7.2 Les pages de manuel 7.3 Le format info 7.4 Le logiciel 7.5 Les HOWTO
7.6 La documentation en ligne
? h Sorry, I already gave what help I could...
Maybe you should try asking a human?
TEX Version 3.14159.
L
’austéritéd’un terminal laisse pantois nombre d’utilisateurs affrontant pour la première fois un système Unix. Combien de fois l’Unixien n’a-t-il pas entendu un utilisateur se plaindre du manque de convivialité du système par rapport à ses« concurrents » intégrant aide en ligne, lignes chaudes et autres systèmes d’assistance à l’utilisateur ? Ce chapitre a donc pour principal objectif de tordre le cou à cette idée d’indisponibilité d’information.
7.1 Quoi fait quoi ?
unixfournit une pléthore de commandes. En shellbash, par exemple, le fait d’ap-puyer par deux fois sur la touche tabulation dans un terminal provoque l’apparition du message :
There are 2727 possibilities. Do you really wish to see them all? (y or n)
L’interpréteur de commande signifie par là qu’il nous donne la possibilité de choisir parmi 2727 commandes différentes et ayant a priori toutes une action différente.
Dans cette section, nous ne donnerons pas la signification et l’action de chacune de ces 2727 commandes mais plutôt le moyen de vous permettre d’accéder à l’informa-tion concernant chacune d’entre elle. En effet, l’un des principaux avantages d’unix est de permettre l’accès à ce genre d’informations.
7.1.1 À propos
La première question est probablement de savoir ce que vous désirez faire. Sup-posons que vous cherchiez à visualiser le contenu de votre répertoire de travail.
181
7
Malheureusement, vous ne connaissez paslacommande qui permet de le faire. Un outil permet de faire une recherche parmi les commandes disponibles :apropos.
Son utilisation est des plus simples. Tapez simplementapropossuivi d’un mot-clé (en anglais) définissant au mieux votre requête. Pour notre exemple, nous cherchons à visualiser le contenu de notre répertoire de travail (en anglais :to display working directory content). Essayons :
$ apropos display
$
Cette commande devrait faire apparaître un grand nombre (155 sur mon système) de lignes ressemblant probablement à1:
bell (n) - Ring a display’s bell
bitmap (n) - Images that display two colors cal (1) - displays a calendar
ckalloc, memory, ckfree, Tcl_DisplayMemory, Tcl_InitMemory, Tcl_ValidateAllMemory (n)
- Validated memory allocation interface.
Si vous aussi, vous prétendez être un informaticien plein de qualités2vous ne lirez pas (sauf peut-être en dernier recours) ces 75 lignes. Le mot-clé display n’était probablement pas suffisamment significatif. Essayons autre chose :
$ apropos working
cd (n) - Change working directory chdir, fchdir (2) - change working directory getcwd (3) - Get current working directory
pwd (1) - print name of current/working directory pwd (n) - Return the current working directory rcsclean (1) - clean up working files
$
Nous obtenons moins d’informations mais malheureusement pas celle qui nous inté-resse3. Essayons encore :
$ apropos content
dir (1) - list directory contents
gl_copyscreen (3) - copy the screen contents of contexts ls (1) - list directory contents
perltoc (1) - perl documentation table of contents pick (1) - search for messages by content pair_content (3x) - curses color manipulation routines stat (1) - print inode contents
vdir (1) - list directory contents
vga_dumpregs (3) - dump the contents of the SVGA registers xev (1x) - print contents of X events
$
Il semble que la commande recherchée soitdiroulsouvdir. Essayons l’une d’entre elles :
1. Nous vous faisons grâce de 71 lignes.
2. Voir à ce sujet Wallet al.(1996) et sa définition de la paresse.
3. Il n’empêche que vous savez maintenant changer de répertoire...
7
Malheureusement, vous ne connaissez pasla commande qui permet de le faire. Un outil permet de faire une recherche parmi les commandes disponibles :apropos.
Son utilisation est des plus simples. Tapez simplementapropossuivi d’un mot-clé (en anglais) définissant au mieux votre requête. Pour notre exemple, nous cherchons à visualiser le contenu de notre répertoire de travail (en anglais :to display working directory content). Essayons :
$ apropos display
$
Cette commande devrait faire apparaître un grand nombre (155 sur mon système) de lignes ressemblant probablement à1:
bell (n) - Ring a display’s bell
bitmap (n) - Images that display two colors cal (1) - displays a calendar
ckalloc, memory, ckfree, Tcl_DisplayMemory, Tcl_InitMemory, Tcl_ValidateAllMemory (n)
- Validated memory allocation interface.
Si vous aussi, vous prétendez être un informaticien plein de qualités2 vous ne lirez pas (sauf peut-être en dernier recours) ces 75 lignes. Le mot-clé display n’était probablement pas suffisamment significatif. Essayons autre chose :
$ apropos working
cd (n) - Change working directory chdir, fchdir (2) - change working directory getcwd (3) - Get current working directory
pwd (1) - print name of current/working directory pwd (n) - Return the current working directory rcsclean (1) - clean up working files
$
Nous obtenons moins d’informations mais malheureusement pas celle qui nous inté-resse3. Essayons encore :
$ apropos content
dir (1) - list directory contents
gl_copyscreen (3) - copy the screen contents of contexts ls (1) - list directory contents
perltoc (1) - perl documentation table of contents pick (1) - search for messages by content pair_content (3x) - curses color manipulation routines stat (1) - print inode contents
vdir (1) - list directory contents
vga_dumpregs (3) - dump the contents of the SVGA registers xev (1x) - print contents of X events
$
Il semble que la commande recherchée soitdiroulsouvdir. Essayons l’une d’entre elles :
1. Nous vous faisons grâce de 71 lignes.
2. Voir à ce sujet Wallet al.(1996) et sa définition de la paresse.
3. Il n’empêche que vous savez maintenant changer de répertoire...
7
$ ls
2Hypergraphes Impression Microsoft Sarah games
Admin LaTeX Mygale Transfert local
Archives Logo NT Web nsmail
Arkeia Mac Netscape archive test
ConfigNT Mail Oueb bin tmp
$
... et nous avons donc bien obtenu le contenu du répertoire courant. En conclu-sion,apropospeut être considéré comme un « moteur de recherche » sur le rôle des commandes disponibles.
7.1.2 Mais c’est quoi donc ?
Il arrive parfois d’oublier ce que peut faire une commande. Supposons que l’on vous ait parlé de la commandefinden vous disant qu’elle était fabuleuse. La com-mandewhatisdevrait vous éclairer.
$ whatis find
find (1) - search for files in a directory hierarchy
$
Notez quewhatisne sait pas nécessairement de quoi vous lui causez :
$ whatis trouver
trouver: nothing appropriate
$
whatispermet donc d’obtenir une information succincte sur le rôle d’une commande shell.
7.2 Les pages de manuel
Le paragraphe précédent nous a permis de constater que findpermettait de rechercher des fichiers dans une arborescence. Supposons que vous vouliez recher-cher un fichier dénommétotoperdu quelque part sur votre home. Unfind toto lancé en ligne de commande produit un navrant find: toto: No such file or directory. Vous vous douterez alors quefindattend peut-être autre chose pour lui permettre de trouver ce fameuxtoto. Une commande va nous aider grandement : man. Osons unman find. Devant vos yeux ébahis devrait apparaître une page de manuel (raccourci en anglais enmanpage) concernantfind.
7.2.1 Une page de manuel
Les pages de manuel ont cette propriété d’avoir une structure assez fixe. Dé-taillons quelques-unes de ses principales entrées :
Name qui définit en une ligne ce que fait la commande. C’est d’ailleurs cette ligne qui est affichée parwhatis. Il s’agit de la seule partie requise pour faire d’une page de documentation quelconque unemanpage;
Synopsis qui précise la forme d’appel de la commande. Le synopsis précise de plus toutes les options qu’il est possible de passer à la commande et ses arguments éventuels ;
7
$ ls
2Hypergraphes Impression Microsoft Sarah games
Admin LaTeX Mygale Transfert local
Archives Logo NT Web nsmail
Arkeia Mac Netscape archive test
ConfigNT Mail Oueb bin tmp
$
... et nous avons donc bien obtenu le contenu du répertoire courant. En conclu-sion,apropospeut être considéré comme un « moteur de recherche » sur le rôle des commandes disponibles.
7.1.2 Mais c’est quoi donc ?
Il arrive parfois d’oublier ce que peut faire une commande. Supposons que l’on vous ait parlé de la commandefinden vous disant qu’elle était fabuleuse. La com-mandewhatisdevrait vous éclairer.
$ whatis find
find (1) - search for files in a directory hierarchy
$
Notez quewhatisne sait pas nécessairement de quoi vous lui causez :
$ whatis trouver
trouver: nothing appropriate
$
whatispermet donc d’obtenir une information succincte sur le rôle d’une commande shell.
7.2 Les pages de manuel
Le paragraphe précédent nous a permis de constater que findpermettait de rechercher des fichiers dans une arborescence. Supposons que vous vouliez recher-cher un fichier dénommétotoperdu quelque part sur votrehome. Unfind toto lancé en ligne de commande produit un navrantfind: toto: No such file or directory. Vous vous douterez alors quefindattend peut-être autre chose pour lui permettre de trouver ce fameuxtoto. Une commande va nous aider grandement : man. Osons unman find. Devant vos yeux ébahis devrait apparaître une page de manuel (raccourci en anglais enmanpage) concernantfind.
7.2.1 Une page de manuel
Les pages de manuel ont cette propriété d’avoir une structure assez fixe. Dé-taillons quelques-unes de ses principales entrées :
Name qui définit en une ligne ce que fait la commande. C’est d’ailleurs cette ligne qui est affichée parwhatis. Il s’agit de la seule partie requise pour faire d’une page de documentation quelconque unemanpage;
Synopsis qui précise la forme d’appel de la commande. Le synopsis précise de plus toutes les options qu’il est possible de passer à la commande et ses arguments éventuels ;
7
Description qui décrit effectivement l’action de la commande, précise le rôle de chaque argument ;
Options précise le rôle de chaque option (vous vous en doutiez, non ?);
See Also vous donne quelques commandes qui ont une action similaire à la com-mande dont vous avez la page de manuel sous les yeux et parfois les comcom-mandes utilisées par la commande.
Parfois on trouve également en fin de page, des exemples et les bugs connus du programme documenté.
7.2.2 Hiérarchie des pages de manuel
Vous aurez constaté que la page de manuel defindcommence en fait non pas par NAME, mais en fait par un nébuleux FIND(1). Les pages de manuel sont souvent hiérarchisées en douze sections numérotées de 1 à 9,n,oetl. Décrivons succincte-ment cette hiérarchie.
1 commandes de l’utilisateur pouvant être lancées par n’importe qui ; 2 appels système (fonctions fournies par le noyau) ;
3 fonctions propres à certaines bibliothèques (C, X windows, etc.) ; 4 ports et périphériques (c’est-à-dire les fichiers de /dev) ; 5 descriptions de formats de fichier de configuration ; 6 jeux ;
7 divers (essentiellement des conventions) ; 8 outils d’administration système ; 9 routines des noyaux (propre àLINUX).
Les sections suivantes ont vraisemblablement été abondonnées mais peuvent être toutefois présentes sur de « vieux » systèmes :
n ce qu’il y a de nouveau. Les documentations résidant dans cette partie se doivent d’être déplacées au bout d’un certain temps dans la section appropriée ; o vieilles documentations condamnées à la disparition ;
l documentation locale propre à un système, un site.
Notons qu’il n’est pas conseillé d’utiliser les trois dernières sections et que ces der-nières ont de plus en plus tendance à disparaître (sur le système où ces lignes sont écrites, seule subsiste la sectionn4).
Il peut arriver qu’un mot donné corresponde à des pages de manuel de différentes sections. Par exemple, vous cherchez une information sur la fonction Cprintf:
$ apropos printf
format (n) - Format a string in the style of sprintf gl_printf (3) - write formatted output in graphic mode printf (1) - format and print data
sprintf, printf,(3) - formatted output conversion printftest (6) - tests the vgagl gl_printf function snprintf, vsnprintf (3) - formatted output conversion
$
4. Et elle ne contient que 210 pages de documentation alors que la section 1 en contient environ 1300.
7
Description qui décrit effectivement l’action de la commande, précise le rôle de chaque argument ;
Options précise le rôle de chaque option (vous vous en doutiez, non ?);
See Also vous donne quelques commandes qui ont une action similaire à la com-mande dont vous avez la page de manuel sous les yeux et parfois les comcom-mandes utilisées par la commande.
Parfois on trouve également en fin de page, des exemples et les bugs connus du programme documenté.
7.2.2 Hiérarchie des pages de manuel
Vous aurez constaté que la page de manuel defindcommence en fait non pas par NAME, mais en fait par un nébuleux FIND(1). Les pages de manuel sont souvent hiérarchisées en douze sections numérotées de 1 à 9,n,oetl. Décrivons succincte-ment cette hiérarchie.
1 commandes de l’utilisateur pouvant être lancées par n’importe qui ; 2 appels système (fonctions fournies par le noyau) ;
3 fonctions propres à certaines bibliothèques (C, X windows, etc.) ; 4 ports et périphériques (c’est-à-dire les fichiers de /dev) ; 5 descriptions de formats de fichier de configuration ; 6 jeux ;
7 divers (essentiellement des conventions) ; 8 outils d’administration système ; 9 routines des noyaux (propre àLINUX).
Les sections suivantes ont vraisemblablement été abondonnées mais peuvent être toutefois présentes sur de « vieux » systèmes :
n ce qu’il y a de nouveau. Les documentations résidant dans cette partie se doivent d’être déplacées au bout d’un certain temps dans la section appropriée ; o vieilles documentations condamnées à la disparition ;
l documentation locale propre à un système, un site.
Notons qu’il n’est pas conseillé d’utiliser les trois dernières sections et que ces der-nières ont de plus en plus tendance à disparaître (sur le système où ces lignes sont écrites, seule subsiste la sectionn4).
Il peut arriver qu’un mot donné corresponde à des pages de manuel de différentes sections. Par exemple, vous cherchez une information sur la fonction Cprintf:
$ apropos printf
format (n) - Format a string in the style of sprintf gl_printf (3) - write formatted output in graphic mode printf (1) - format and print data
sprintf, printf,(3) - formatted output conversion printftest (6) - tests the vgagl gl_printf function snprintf, vsnprintf (3) - formatted output conversion
$
4. Et elle ne contient que 210 pages de documentation alors que la section 1 en contient environ 1300.
7
Si vous vous contentez d’un man printf, à votre grand désarroi, vous ne pourrez visualiser que la page de documentation correspondant à la section 1. Comment spécifier àmand’aller regarder dans la section 3 ? Facile : essayez unman 3 printf et réjouissez-vous :
$ man 3 printf
PRINTF(3) Linux Programmer’s Manual PRINTF(3) NAME
printf, fprintf, sprintf, snprintf, vprintf, vfprintf, vsprintf, vsnprintf - formatted output conversion SYNOPSIS
#include <stdio.h>
...
$
Bien entendu, il est nécessaire d’interroger une section dans laquelle existe la page de documentation. Il y a fort à parier qu’unman 2 printfvous rétorque narquoisement qu’il n’y a pas d’entrée pourprintfdans la section 2 du manuel.
7.2.3 La variable d’environnement MANPATH
Le plus rageant avec l’utilisation demanest d’obtenir un insoutenableNo manual entry for (le nom de la commande). Par exemple, unman xvproduitNo manual entry for xv. La première idée qui peut vous venir à l’esprit est qu’il n’existe pas de documentation pour cet outil qu’estxv. C’est possible mais regardons de plus près une certaine variable d’environnement dénomméeMANPATH.
$ echo $MANPATH
/usr/share/man:/usr/local/man
$
Cette variable a le même format que ◮PATHNet indique à la commande man les § 6.1.4 p. 147◭ endroits où rechercher les pages de manuel. Dans l’exemple précédent,manira donc
dans/usr/share/manpuis (en cas d’échec) dans/usr/local/manpour tenter de trouver l’information qui vous intéresse. Aucune page n’étant associée à xv, man vous le signifie poliment. Il suffit de rajouter un nouveau répertoire de recherche (/usr/X11R6/mansous Linux) à la variableMANPATHpour voir apparaître la page de documentation.
$ export MANPATH=$MANPATH:/usr/X11R6/man
$ man xv
XV(1) XV(1)
NAME
xv - interactive image display for the X Window System ... etc ...
$
Cette variable devrait êtrea priori« correctement » configurée pour aller visiter les points de chute classiques des pages de manuel, c’est-à-dire (cette liste ne se veut en aucun cas exhaustive)/usr/share/man,/usr/local/manet/usr/X11R6/man.
Dans le cas où vous souhaiteriez installer certaines pages de manuel à certains endroits précis de votre compte utilisateur, vous pouvez utiliser la même démarche
et ajouter dans vos◮fichiersNde démarrage : § 6.1.6 p. 148◭
7
Si vous vous contentez d’unman printf, à votre grand désarroi, vous ne pourrez visualiser que la page de documentation correspondant à la section 1. Comment spécifier àmand’aller regarder dans la section 3 ? Facile : essayez unman 3 printf et réjouissez-vous :
$ man 3 printf
PRINTF(3) Linux Programmer’s Manual PRINTF(3) NAME
printf, fprintf, sprintf, snprintf, vprintf, vfprintf, vsprintf, vsnprintf - formatted output conversion SYNOPSIS
#include <stdio.h>
...
$
Bien entendu, il est nécessaire d’interroger une section dans laquelle existe la page de documentation. Il y a fort à parier qu’unman 2 printfvous rétorque narquoisement qu’il n’y a pas d’entrée pourprintfdans la section 2 du manuel.
7.2.3 La variable d’environnement MANPATH
Le plus rageant avec l’utilisation demanest d’obtenir un insoutenableNo manual entry for (le nom de la commande). Par exemple, unman xvproduitNo manual entry for xv. La première idée qui peut vous venir à l’esprit est qu’il n’existe pas de documentation pour cet outil qu’estxv. C’est possible mais regardons de plus près une certaine variable d’environnement dénomméeMANPATH.
$ echo $MANPATH
/usr/share/man:/usr/local/man
$
Cette variable a le même format que ◮PATHNet indique à la commandeman les § 6.1.4 p. 147◭ endroits où rechercher les pages de manuel. Dans l’exemple précédent,manira donc
dans/usr/share/man puis (en cas d’échec) dans/usr/local/manpour tenter de trouver l’information qui vous intéresse. Aucune page n’étant associée à xv, man vous le signifie poliment. Il suffit de rajouter un nouveau répertoire de recherche (/usr/X11R6/mansous Linux) à la variableMANPATHpour voir apparaître la page de documentation.
$ export MANPATH=$MANPATH:/usr/X11R6/man
$ man xv
XV(1) XV(1)
NAME
xv - interactive image display for the X Window System ... etc ...
$
Cette variable devrait êtrea priori« correctement » configurée pour aller visiter les points de chute classiques des pages de manuel, c’est-à-dire (cette liste ne se veut en aucun cas exhaustive)/usr/share/man,/usr/local/manet/usr/X11R6/man.
Dans le cas où vous souhaiteriez installer certaines pages de manuel à certains endroits précis de votre compte utilisateur, vous pouvez utiliser la même démarche
et ajouter dans vos◮fichiersNde démarrage : § 6.1.6 p. 148◭
7
export MANPATH=$HOME/man:$MANPATH
de manière à ajouter vos pages de manuels aux pages traitées par la commandeman.
7.2.4 Recherche exhaustive
Il peut arriver qu’en désespoir de cause, vous désiriez effectuer une recherche exhaustive d’un mot donné dans l’ensemble des pages de manuel. Si vous choisissez de prendre ce risque, sachez que c’est possible mais qu’il y a de grandes chances que cela prenne un certain temps5.
7.2.5 La commande ultime
Pour toutes les subtilités concernant votre version locale deman, vous n’avez fi-nalement qu’une seule commande à connaître :man man. La boucle est donc bouclée.
7.3 Le format info
Il existe un système de documentation répandu sur les systèmesunixbasé sur
Il existe un système de documentation répandu sur les systèmesunixbasé sur