Aller au menu - Aller au contenu

[Plan du site] Vous êtes ici --- > Le Site du Zéro > Les tutoriels > Officiels > Systèmes alternatifs > Lecture du tutoriel

RTFM : lisez le manuel !

Avatar
Auteur : M@teo21
Créé : le 03/04/2008 17:12:51
Modifié : le 09/04/2008 17:08:44
Noter et commenter ce tutoriel
Imprimer ce tutoriel
Quand on vient de Windows, on n'a pas trop l'habitude de lire des documentations. Parfois les logiciels sont livrés avec des modes d'emploi, mais honnêtement, qui ici prend la peine de les lire ? :p

Sous Linux, lire la documentation doit devenir un réflexe. En effet, bien que cela fasse un peu peur au premier abord, la documentation est vraiment le meilleur endroit pour en savoir plus sur les commandes que vous utilisez.
Les tutoriels que j'écris ne pourront jamais rivaliser avec la documentation. Je peux vous montrer les commandes et les paramètres qui me semblent les plus utiles, mais pour connaître certains paramètres dont vous avez besoin moins souvent, vous n'y couperez pas : vous aurez besoin de lire la doc.

Ce chapitre est justement là pour "démystifier" la doc et vous apprendre à la lire. C'est peut-être un des chapitres les plus importants du cours, car si vous savez lire la doc, vous êtes capables d'apprendre tout ce dont vous avez besoin, et donc vous pourrez tout faire !

Le titre de ce chapitre est une insulte "amicale" entre Linuxiens. C'est en général ce qu'on dit à un débutant qui pose trop de questions sur les forums, alors que la réponse était dans la doc.
"RTFM" est une abréviation qui signifie "Read The Fucking Manual", ce qui se traduirait en français par quelque chose "Lis ce p*** de manuel". Mais oui, c'est amical ! Puisque je vous le dis... :p
Sommaire du chapitre :
Chapitre précédent Sommaire

man : afficher le manuel d'une commande

La commande magique que nous allons expérimenter durant tout ce chapitre est man, qui est l'abréviation de MANual.

La commande man s'utilise très simplement : elle prend en paramètre le nom de la commande dont vous voulez lire la doc.
Par exemple, si je veux tout savoir sur la commande mkdir, je dois écrire :

Code : Console
man mkdir


Votre console devrait alors ressembler à ceci :

Commande man


Il s'agit de la documentation de la commande mkdir. Là-dedans, il y a tout ce qu'il faut savoir sur mkdir.
La doc de la commande étant généralement un peu longue, celle-ci s'affiche page par page, à la manière de less qu'on a vue dans un chapitre précédent.


Se déplacer dans le manuel



Quelques commandes à connaître pour se déplacer dans le man :

Si vous avez ouvert votre manuel dans une console graphique comme moi, vous pouvez aussi utiliser la molette de la souris !


Les principales sections du manuel



Comme vous pouvez le voir, le manuel de la commande est découpé en plusieurs sections (leur nom est écrit en gras et est aligné à gauche de l'écran).
Voici leur signification :


Pour faire simple, les 3 premières sections sont vraiment les plus importantes (NAME, SYNOPSIS et DESCRIPTION), c'est celles que nous regarderons dans la plupart des cas et c'est aussi pour cela qu'elles sont au début du manuel ;)


La langue des pages de manuel



Eh mais... c'est tout en anglais ! Tout le monde n'est pas un crack en anglais, comment je fais moi si j'ai du mal à lire l'anglais ??? :(


Mon premier conseil, même si vous n'allez pas l'apprécier, je tiens à le donner car c'est vraiment le meilleur conseil : familiarisez-vous avec l'anglais. Si vous voulez travailler dans l'informatique c'est de toute façon une langue incontournable, il est impossible de l'ignorer ou alors ce serait du pur suicide.

Bon, malgré tout, il y en a peut-être parmi vous qui ne comptent pas forcément travailler dans l'informatique mais qui aimeraient éviter d'avoir à apprendre l'anglais pour se servir de Linux, ce que je peux très bien comprendre. Si l'évocation du mot "anglais" provoque chez vous des éruptions cutanées inexplicables, alors voici une bonne nouvelle : il existe une version française des pages de manuel !

Vous pouvez l'installer grâce à la commande apt-get qu'on a justement apprise dans le chapitre précédent (rien n'est laissé au hasard, je vous l'ai dit :-° ) :

Code : Console
apt-get install manpages-fr


Le paquet à installer est manpages-fr comme vous pouvez le voir :)
Maintenant, si vous tapez man mkdir, vous verrez la page s'afficher en français :

Pages de manuel en français


Utiliser les pages de manuel en français n'est pas recommandé. En effet, ces pages ne sont parfois pas à jour, certaines ne sont pas traduites, et seule la version anglaise est assurée d'être la plus à jour et de comporter le moins d'erreurs.
D'ailleurs en parlant d'erreur cher lecteur, une faute d'orthographe s'est glissée dans la capture d'écran ci-dessus, sauras-tu la retrouver ? :-°


Dans la suite de ce tutoriel, je considèrerai que vous travaillez avec les pages de manuel en anglais. C'est vraiment ce que je recommande. Utilisez la version française uniquement si vous ne comprenez rien à l'anglais, sinon faites un petit effort je vous assure que ça vaut le coup ;)

Je vais donc désinstaller les pages de manuel en français pour revenir à la version anglaise pour la suite de ce chapitre :

Code : Console
apt-get autoremove manpages-fr


Bien, les présentations étant faites, passons à la suite !
Nous allons apprendre à lire la section SYNOPSIS, une des sections les plus importantes.

Comprendre le synopsis

Le synopsis est une des sections les plus importantes, mais aussi une des plus difficiles à lire.

Quel est le rôle du synopsis ?


Son rôle est de lister toutes les façons possibles d'utiliser la commande. En clair, le synopsis vous affiche toutes les combinaisons de paramètres que l'on peut faire avec cette commande.
Certains synopsis sont simples, d'autres sont plus compliqués. Je pense que le mieux est de voir des exemples pour bien comprendre comment ça fonctionne :)


man mkdir



Commençons par le man de mkdir. La section d'introduction du manuel nous dit : "mkdir - make directories", ce qui signifie que mkdir sert à créer des répertoires.


Synopsis



La section synopsis de mkdir contient ceci :

Synopsis de mkdir

Même si ce synopsis est court, il contient déjà beaucoup d'informations. Il vous dit comment on doit utiliser la commande.
Détaillons point par point ce synopsis :


Pourquoi mkdir est écrit en gras tandis que OPTION et DIRECTORY sont soulignés ?

Les mots du synopsis écrits en gras sont des mots à taper tels quels.
Les mots écrits en souligné doivent être remplacés par le nom approprié.

C'est logique : on doit bel et bien écrire précisément "mkdir", par contre on ne doit pas écrire "DIRECTORY" mais le nom du répertoire. La présence d'un paramètre souligné signifie donc : "Remplacez le mot souligné par un mot qui convient dans votre cas".

Exemples d'utilisation



D'après le synopsis, on doit au minimum écrire le nom du dossier. Par exemple :

Code : Console
mkdir images


Comme on l'a vu, les points de suspension après DIRECTORY nous indiquent qu'on peut répéter le nom du répertoire autant de fois que l'on veut, ce qui nous permet d'en créer plusieurs d'un coup.
On peut donc aussi utiliser mkdir comme ceci :

Code : Console
mkdir images videos musiques


... ce qui aura pour effet de créer 3 dossiers : "images", "videos" et "musiques".

Maintenant, on peut aussi préciser des options facultatives. Ces options sont listées dans la section DESCRIPTION du man juste un peu plus bas :

Code : Console
DESCRIPTION
       Create the DIRECTORY(ies), if they do not already exist.
 
       Mandatory  arguments  to  long  options are mandatory for short options
       too.
 
       -m, --mode=MODE
              set file mode (as in chmod), not a=rwx - umask
 
       -p, --parents
              no error if existing, make parent directories as needed
 
       -v, --verbose
              print a message for each created directory
 
       -Z, --context=CTX
              set the SELinux security context of each  created  directory  to
              CTX
 
       --help display this help and exit
 
       --version
              output version information and exit


Toutes ces options peuvent être utilisées à la place de [OPTION] dans le synopsis.
Par exemple, l'option -v (ou --verbose, c'est pareil mais plus long :p ) affiche un message après chaque répertoire créé. On peut donc écrire :

Code : Console
mkdir -v images videos musiques


Résultat :

Code : Console
mateo21@mateo21-desktop:~/tests$ mkdir -v images videos musiques
mkdir: création du répertoire `images'
mkdir: création du répertoire `videos'
mkdir: création du répertoire `musiques'

La commande nous informe maintenant de ce qu'elle fait. Sans le -v, la commande n'affiche rien (on dit qu'elle est silencieuse).

Vous remarquerez d'ailleurs qu'on retrouve l'option -v dans beaucoup de commandes. A chaque fois elle a la même signification : elle demande à ce que la commande affiche le détail de ce qu'elle est en train de faire. On dit alors qu'on utilise la commande en mode "verbeux" (bavard), pour bien voir tout ce qu'elle fait.


man cp



Essayons une commande un peu plus complexe : cp. Je vous rappelle que cette commande sert à copier des fichiers et des répertoires.

Synopsis



Son synopsis est le suivant :

Synopsis de cp

Oulah, ça commence à devenir un peu plus délicat :o
Pourquoi il y a 3 lignes déjà ? Tout simplement parce qu'on ne pouvait pas exprimer toutes les façons d'utiliser cp sur une seule ligne.


Exemples d'utilisation



Ca fait beaucoup de façons d'utiliser cp en fait :D
Si on se base sur la première ligne, on peut juste écrire :

Code : Console
cp photo.jpg photo_copie.jpg


... ce qui aura pour effet de créer la copie photo_copie.jpg.

On peut aussi ajouter une ou plusieurs options. Pour connaître toutes les options disponibles, vous devrez lire la section DESCRIPTION. Pour cp, il y a beaucoup de choix comme vous pouvez le voir.
Par exemple, on retrouve notre mode -v (verbeux) qui demande à ce que la commande détaille ce qu'elle fait. On pourrait aussi ajouter -i qui demande confirmation si le fichier de destination existe déjà.

On peut donc faire :

Code : Console
cp -vi photo.jpg photo_copie.jpg


Dans mon cas, le fichier photo_copie.jpg existait déjà. L'ajout de l'option -i va me demander confirmation pour savoir si je veux bien écraser le fichier. Je peux répondre par "o" ou "n" (pour oui ou non), ou "y" ou "n" (pour yes ou no).

Code : Console
mateo21@mateo21-desktop:~$ cp -vi photo.jpg photo_copie.jpg
cp: écraser `photo_copie.jpg'? o
`photo.jpg' -> `photo_copie.jpg'


Comme le fichier existait déjà, on m'a demandé confirmation. La dernière ligne est le résultat du mode verbeux qu'on a demandé.

Bien :)
Tout ça c'était juste pour la première ligne, dans le cas où on veut copier un fichier. Essayons un peu ce que propose la seconde ligne : copier un ou plusieurs fichiers dans un dossier.

Code : Console
cp photo.jpg photo_copie.jpg images/


On exploite là la seconde façon d'utiliser cp (seconde ligne du synopsis). On copie 2 fichiers dans le sous-dossier images/.
Bien entendu, comme l'indique le synopsis, on peut là encore utiliser des options comme -v et -i que l'on vient de voir :)

Mon conseil : vous vous demandez peut-être comment je comprends la signification de chaque mot du synopsis. Par exemple, était-il évident de savoir que SOURCE correspondait au fichier que l'on voulait copier ?
Si je sais tout ça, c'est parce que j'ai lu attentivement le début de la section DESCRIPTION du man. Je vous recommande d'en faire de même quelle que soit la commande que vous êtes en train d'analyser.

Code : Console
DESCRIPTION
       Copy SOURCE to DEST, or multiple SOURCE(s) to DIRECTORY.


Cette phrase est claire, pour peu que l'on comprenne l'anglais ;)
Elle signifie que l'on peut copier le paramètre appelé SOURCE vers DEST, ou encore (cas de la seconde ligne) plusieurs fichiers SOURCE vers un répertoire (DIRECTORY).


man apt-get



Plus joyeux encore : le synopsis de la commande apt-get :D

Synopsis de aptget

La bonne nouvelle cette fois, c'est que les créateurs d'apt-get n'ont pas eu besoin de faire tenir la commande sur 3 lignes : ils ont mis tous les cas d'utilisation possibles sur une seule ligne !
La mauvaise nouvelle c'est que c'est un peu difficile à lire comme ça.

Décortiquons.

La commande apt-get doit commencer par "apt-get" (ce mot est d'ailleurs écrit en gras). Ca c'est logique.
Ensuite vous pouvez utiliser une des options -hvs (vous pouvez utiliser juste -h, mais aussi -hv, -v, -vs, -hvs...). Ces options étant entre crochets, elles sont facultatives.

Pareil ensuite pour -o et -c. Ces options sont facultatives. En revanche, vous remarquerez qu'elles doivent être obligatoirement suivies d'une valeur. Par exemple "-o=option de configuration". Je vous rappelle que le fait que "option de configuration" soit souligné signifie que vous ne devez pas recopier ces mots tels quels dans la console : vous devez les remplacer par une valeur qui convient (lisez la section DESCRIPTION pour en savoir plus sur -o).

La section qui m'intéresse et que je voudrais qu'on analyse plus en détail arrive juste après. Elle commence et se termine par des accolades :
{[update] | [upgrade] | [dselect-upgrade] | [install paquet...] | [remove paquet...] | [source paquet...] | [build-dep paquet...] | [check] | [clean] | [autoclean]}

Vous remarquerez qu'à l'intérieur, les mots sont séparés par des barres verticales |. Ces barres verticales signifient "OU". Cela veut dire que vous devez mettre une et une seule option parmi la liste entre accolades.
Parmi ces options possibles, il y en a que vous devez connaître maintenant, comme :


Il y a bien d'autres mots-clés utilisables. Pour voir la signification de chacun d'eux, je vous invite à lire la section DESCRIPTION du man qui sert précisément à expliquer ça.


Exemples d'utilisation



Le synopsis indique donc qu'on doit choisir une des options entre accolades séparées par des barres verticales.
On peut donc écrire :

Code : Console
apt-get install monpaquet


Ou encore :

Code : Console
apt-get update


Ou encore :

Code : Console
apt-get autoclean


En revanche, on ne peut pas utiliser simultanément deux options séparées par une barre verticale :

Code : Console
INTERDIT :
apt-get update install monpaquet


Le synopsis nous avait bien dit : "utilisez update OU install OU upgrade (OU ...), mais pas deux éléments de cette liste à la fois".
Souvenez-vous donc que les barres verticales signifient "OU" et tout ira bien ;)

Résumé de la syntaxe du SYNOPSIS



Voici un petit résumé de la syntaxe du synopsis pour vous souvenir de la façon dont chaque élément doit être interprété :


apropos : trouver une commande

Le man suppose que vous connaissez déjà votre commande et que vous voulez en savoir plus. Mais si vous ne connaissez pas la commande, comment faites-vous ? :(

C'est là que la commande apropos intervient. Vous lui donnez en paramètre un mot-clé, et elle va le rechercher dans les descriptions de toutes les pages du manuel.
La commande apropos est donc un peu l'inverse de man : elle vous permet de retrouver une commande.

Prenons un exemple : vous recherchez une commande (que vous avez installée) en rapport avec le son, parce que vous aimeriez bien savoir comment modifier le volume en console.
Vous pouvez taper :

Code : Console
apropos sound


... ce qui va rechercher toutes les commandes qui parlent de son (sound) dans leur page de manuel.

Résultat :

Code : Console
mateo21@mateo21-desktop:~$ apropos sound
alsactl (1)          - advanced controls for ALSA soundcard driver
alsamixer (1)        - soundcard mixer for ALSA soundcard driver, with ncurse...
amixer (1)           - command-line mixer for ALSA soundcard driver
aplay (1)            - command-line sound recorder and player for ALSA soundc...
arecord (1)          - command-line sound recorder and player for ALSA soundc...
artscat (1)          - pipe data to sound device
asoundconf (1)       - utility to read and change the user's ALSA library con...


A gauche la commande, à droite l'extrait de la description courte de la commande dans laquelle apropos a trouvé le mot que vous recherchiez.
Il se trouve que je cherchais était alsamixer. Et zou ! :)

Code : Console
alsamixer


Alsamixer


Et si vous voulez en savoir plus sur la commande alsamixer, vous savez maintenant comment faire ! ;)

Code : Console
man alsamixer


Manuel de Alsamixer


Son synopsis est ridiculement simple. Pfeuh ! Même pas drôle :-°

D'autres façons de lire le manuel

Bien que ce soit la technique la plus courante, utiliser man et apropos n'est pas le seul moyen de vous documenter.
Quelles sont les alternatives à man ?

Le paramètre -h (et --help)



Bien que ça ne soit pas une règle, la plupart des commandes acceptent un paramètre -h (et parfois son équivalent plus long --help) qui provoque l'affichage d'une aide résumée. Parfois, cette aide est d'ailleurs plus facile à lire que celle du man, ce qui fait qu'il m'arrive de l'utiliser de temps en temps.

Par exemple :

Code : Console
apt-get -h


Ce qui nous donne :

Code : Console
mateo21@mateo21-desktop:~$ apt-get -h
apt 0.7.9ubuntu15 pour amd64 compilé sur Mar 14 2008 00:00:28
Usage: apt-get [options] command
       apt-get [options] install|remove pkg1 [pkg2 ...]
       apt-get [options] source pkg1 [pkg2 ...]
 
apt-get is a simple command line interface for downloading and
installing packages. The most frequently used commands are update
and install.
 
Commands:
   update - Retrieve new lists of packages
   upgrade - Perform an upgrade
   install - Install new packages (pkg is libc6 not libc6.deb)
   remove - Remove packages
   autoremove - Remove all automatic unused packages
   purge - Remove and purge packages
   source - Download source archives
   build-dep - Configure build-dependencies for source packages
   dist-upgrade - Distribution upgrade, see apt-get(8)
   dselect-upgrade - Follow dselect selections
   clean - Erase downloaded archive files
   autoclean - Erase old downloaded archive files
   check - Verify that there are no broken dependencies
 
Options:
  -h  This help text.
  -q  Loggable output - no progress indicator
  -qq No output except for errors
  -d  Download only - do NOT install or unpack archives
  -s  No-act. Perform ordering simulation
  -y  Assume Yes to all queries and do not prompt
  -f  Attempt to correct a system with broken dependencies in place
  -m  Attempt to continue if archives are unlocatable
  -u  Show a list of upgraded packages as well
  -b  Build the source package after fetching it
  -V  Show verbose version numbers
  -c=? Read this configuration file
  -o=? Set an arbitrary configuration option, eg -o dir::cache=/tmp
See the apt-get(8), sources.list(5) and apt.conf(5) manual
pages for more information and options.
                       This APT has Super Cow Powers.


Le -h est parfois un bon complément au man si vous n'arrivez pas à comprendre comment utiliser la commande. On y trouve parfois des informations utiles comme ici : "The most frequently used commands are update and install", ce qui signifie que l'on utilise le plus souvent apt-get avec les paramètres update et install (et c'est vrai ;) ).

Parfois, il n'y a pas de page de manuel pour une commande (man ne fonctionne pas sur cette commande) mais le -h ou le --help fonctionnent. Pensez-y !


La commande whatis



La commande whatis est une sorte de man très allégé. Elle donne juste l'en-tête du manuel pour expliquer en deux mots à quoi sert la commande. Par exemple pour mkdir :

Code : Console
whatis mkdir


Ca vous permet d'éviter de sortir l'artillerie lourde juste pour savoir à quoi sert la commande :p

Code : Console
mateo21@mateo21-desktop:~$ whatis mkdir
mkdir (1)            - make directories


La commande info



La commande info est une alternative à man. Elle est réputée plus puissante mais je la connais trop peu pour vous en parler ici. Je peux donc vous dire qu'elle existe mais je ne vais pas vous faire un chapitre entier dessus ^^
En général le man est bien suffisant.

A noter toutefois que si vous tapez :

Code : Console
info coreutils


... cela affichera une sorte de méga-résumé des principales commandes console sous Linux (elles n'y sont pas toutes bien sûr !). Ca vous permet d'avoir une bonne vue d'ensemble :)

Le manuel sous Konqueror



Ceux qui utilisent KDE, et qui ont donc Konqueror, seront ravis d'apprendre que l'on peut lire le manuel directement depuis Konqueror.
Pour ce faire, tapez dans la barre d'adresse : man:votrecommande. Par exemple : man:mkdir.

Man sous Konqueror


On profite ainsi au passage d'une jolie mise en forme dans le navigateur :)

Rechercher man sur le Web



Google
Enfin, il est bien de le préciser : on retrouve aussi le man sur le Web !
Si vous devez lire un manuel et que vous n'êtes pas sous Linux à ce moment-là, utilisez tout bêtement un moteur de recherche comme Google pour retrouver la doc.

Par exemple, vous pouvez taper la recherche Google : man mkdir.
Je vous parie que vous trouverez le manuel dans les premiers liens qui s'offrent à vous ;)

Bonne recherche !

Q.C.M.

Comment faire une recherche dans une page de manuel qu'on est en train de lire ?
Comment quitter le manuel ?
Quelle est la section du manuel qui décrit la signification des paramètres ?
D'après le synopsis suivant de la commande imaginaire imprimer, peut-on imprimer plusieurs fichiers d'un seul coup ?


Code : Console
imprimer [-vf] NOMFICHIER...
Que signifient les mots en gras dans un synopsis ?
Voici le synopsis de la commande file qui permet de déterminer le type d'un fichier (image, exécutable, paquet...) :

Code : Console
file [-bchikLnNprsvz] [-f namefile] [-F separator] [-m magicfiles] file
file -C [-m magicfile]


Laquelle de ces commandes est valide d'après ce synopsis ?


La commande man en elle-meme n'est pas très complexe, mais lire une page de manuel peut faire peur aux débutants au début je le reconnais.
Ce chapitre était justement là pour démystifier la doc et vous encourager à la lire.

Lire la doc doit devenir un réflexe.
Ne pas savoir faire quelque chose sous Linux n'est pas grave. Ne pas chercher la réponse et baisser les bras est par contre beaucoup plus grave.

Les bons utilisateurs de Linux sont justement de grands amateurs de doc. Ils n'ont pas peur d'aller la lire dès qu'ils ne savent pas comment utiliser une commande.

Quoi ? Les pros de Linux ne connaissent pas toutes les commandes par coeur ? ^^

Non, personne ne connaît toutes les commandes en détail. Ca n'existe pas, c'est infaisable, et ce serait de toute façon stupide de tout vouloir apprendre par coeur.
On dit qu'un vrai professionnel connaît en moyenne 90% des commandes qu'il tape. Cela veut dire que pour les 10% restants, il ouvre la doc pour apprendre comment faire ce dont il a besoin.

Comme vous pouvez le voir, lire la doc n'est pas une honte bien au contraire. Pour écrire ce cours de Linux pour débutants, vous n'imaginez pas le nombre de fois que j'ai tapé la commande man ! Comme quoi, il n'y a pas de secret.


Allez, on se quitte sur une petite devinette pour terminer la partie II du cours, et on se retrouve dans la partie III pour en découvrir encore plus sur Linux !

Quel est le résultat de cette commande ?

Code : Console
man man


Ok je sors... :-°
(mais vous pouvez essayer ça marche hein !)
Chapitre précédent Sommaire
Auteur : M@teo21
Noter et commenter ce tutoriel
Imprimer ce tutoriel

Changer de design | En savoir plus | Plan du site | Politique d'accessibilité | Règles | Fil RSS | XHTML 1.0 | CSS 2.0
Édité par Simple IT SARL : Nous contacter | Revue de presse | Publicité

Y'a plus rien à lire, faut remonter maintenant !

Hébergement web - Correction de tutoriels - Créer un site
Vous souhaitez apparaître ici ? Contactez-nous.

Nombre de connectés 350 Zéros connectés | Requêtes SQL 10 requêtes | Temps de génération de la page : Total (SQL) 0.0552s (0.0416s)