<br />
<b>Deprecated</b>:  Assigning the return value of new by reference is deprecated in <b>/srv/www/u-classroom.net/wiki/inc/parserutils.php</b> on line <b>208</b><br />
<br />
<b>Deprecated</b>:  Assigning the return value of new by reference is deprecated in <b>/srv/www/u-classroom.net/wiki/inc/parserutils.php</b> on line <b>211</b><br />
<br />
<b>Deprecated</b>:  Assigning the return value of new by reference is deprecated in <b>/srv/www/u-classroom.net/wiki/inc/parserutils.php</b> on line <b>421</b><br />
<br />
<b>Deprecated</b>:  Assigning the return value of new by reference is deprecated in <b>/srv/www/u-classroom.net/wiki/inc/parserutils.php</b> on line <b>594</b><br />
<br />
<b>Deprecated</b>:  Function split() is deprecated in <b>/srv/www/u-classroom.net/wiki/inc/auth.php</b> on line <b>154</b><br />
<br />
<b>Warning</b>:  Cannot modify header information - headers already sent by (output started at /srv/www/u-classroom.net/wiki/inc/parserutils.php:208) in <b>/srv/www/u-classroom.net/wiki/inc/auth.php</b> on line <b>245</b><br />
<br />
<b>Warning</b>:  Cannot modify header information - headers already sent by (output started at /srv/www/u-classroom.net/wiki/inc/parserutils.php:208) in <b>/srv/www/u-classroom.net/wiki/inc/actions.php</b> on line <b>370</b><br />
<br />
<b>Warning</b>:  Cannot modify header information - headers already sent by (output started at /srv/www/u-classroom.net/wiki/inc/parserutils.php:208) in <b>/srv/www/u-classroom.net/wiki/inc/actions.php</b> on line <b>374</b><br />
====== MAN / INFO - Comment trouver de l'aide ======

Nous allons voir au travers de ce petit cours un élément fondamental de gnu/linux en particuliers, et des Unix en général : **la documentation**. Comme vous le savez, chaque programme est accompagné d'une documentation expliquant à quoi sert le programme en question, quelles sont ses options, ou encore ses bugs. Comme vous le savez aussi, on a coutume de les appelées : **Page de manuel**.

Ces pages de manuels sont distribuées sous une multitude de forme, bien que la plus répendue soit la page de manuel accessible avec la commande ''man'' ou le programme ''xman'' dans sa version graphique. Ces mans ne sont pas une lubie comme l'explique clairement la FAQ d'OpenBSD:

"//Lorsqu'un développeur fait une modification au niveau système, on attend de sa part qu'il mette à jour les pages du manuel  en même temps que la modification du code système, et pas "après" ou "lorsqu'il aura le temps de le faire" ou lorsque "quelqu'un se plaint". Une page de manuel existe pour virtuellement chaque programme, utilitaire, pilote, fichier de         configuration et ainsi de suite dans le système de base.//

"//On attend de la part de l'utilisateur qu'il prenne le temps d'effectuer des recherches dans les pages du manuel avant de demander de l'aide sur les listes de diffusion.//"

En d'autres termes, c'est une belle façon de dire : RTFM!!

Les pages de manuels man sont repérées sous cette forme : programme(?)  où ? est un numéro qui va de 1 à 9. Ces numéros correspondent aux différentes sections de page de manuel. Elles sont écrites selon des critères particuliers, je vous invite à l'occasion à ouvrir des sources man disponibles sur votre distribution. Exemple: /usr/share/man/man1/ls.1.gz

Il n'y a pas besoin d'installer de paquets pour avoir les man des programmes. En effet, elles sont distribués avec eux. Sauf cas particuliers que nous verrons un peu plus bas :)

===== MAN =====


Les pages de manuels sont TOUJOURS présentées de la même manière et ont des conventions très précises : ainsi vous aurez TOUJOURS ces différentes parties dans une man : NAME, SYNOPSIS, DESCRIPTION, OPTIONS, FILES, SEE ALSO, BUGS, et AUTHOR (sauf si le programme bien sûr ne les requiert pas, je pense à FILES par exemple). Il en existe d'autres(comme EXAMPLES) mais celles-ci sont les principales.

Ainsi par exemple, pour savoir à quoi correspondent les 9 sections susmentionnées, il vous suffit dans votre terminal de saisir:
<code>$ man man</code>
Regarder à la section DESCRIPTION.

Sans m'étendre sur le sujet, sachez qu'il existe dans chaque distribution des paquets de pages de manuel qui viennent donc en dehors des programmes. Généralement ce sont des traductions (manpages-fr) ou encore des documentations spécifiques (manpages-dev qui comprend des man traitant du développement sous GNU/Linux ; freebsd-manpages ; etc).

Généralement on connait le nom de la page de manuel et un simple
<code>$ man urxvt</code>
suffit pour la lire. Mais il peut arriver que vous aillez besoin de chercher le nom d'une page de manuel que vous ne connaissez pas ou dont vous connaissez partiellement le nom. Dans ce cas, nous allons utiliser la commande 
<code>$ apropos cron</code>
ou encore
<code>$ man -k cron</code>
qui va faire une recherche sur les noms des pages de manuel (et non leur contenu).

En faisant cela vous voyez le nom des man disponibles pour ce nom avec leur section. Remarquez que crontab dispose de deux pages de manuel distinctes. Par défaut, un man crontab vous renverra sur la page de manuel de la section 1. Pour afficher la page de la section 5 il suffit de faire:

<code>$ man 5 crontab</code>

Note: Si vous préférez l'outil graphique vous pouvez utilise xman pour parcourir toutes les man disponibles par section en cliquant sur Sections/&lt;sections-désirée&gt;

Une petite astuce : Il peut s'avérer utile d'avoir à imprimer une page de manuel. Tandis qu'OpenBSD possède ses propres routines pour directement avoir un fichier imprimable, sous GNU/Linux il faut improviser un peu. Il existe plusieurs solutions mais en voilà une simple qui consiste à passer la sortie de la page de man vers un fichier .txt :

<code>$ man zsh | col -bx > ~/b/zsh.txt</code>

Il ne reste plus qu'à imprimer le fichier .txt.

Vous pouvez aussi générer des fichiers PostScript grâce à nroff:

<code>$ nroff -Tps -mandoc <fichier> > pageman.ps</code>

(&lt;fichier&gt; doit être le fichier source de la page de manuel, et non la version gunziper) (si vous cherchez où ce trouve une manpage, l'option -w peut vous aider ;)).

Si on veut du dvi:

<code>$ man -l -Tdvi ./foo.1x.gz > ./foo.1x.dvi</code>

Ou encore vous pouvez directement imprimer des pages en ligne disponible par exemple sur [[http://linux.die.net|http://linux.die.net]]. De plus généralement un 'man commande' dans un moteur de recherche vous trouve ce que vous cherchez et/ou vous permet d'éviter d'installer le programme pour avoir sa page de manuel. Voir aussi [[http://manpages.debian.net/|http://manpages.debian.net/]] ou [[http://manpages.ubuntu.com/|http://manpages.ubuntu.com/]]

Note: Pour trouver le fichier source d'une page de manuel:

<code>$ man -w &lt;command&gt;</code>

Histoire d'égailler les choses, on peut mettre un peu de couleur dans nos pages de manuel. Il y a deux solutions. Par défaut, la commande man utilise le programme less pour afficher les pages. Il suffit de remplacer less par most par exemple:

<code>$ export PAGER=most</code>

(À rajouter dans votre fichier de configuration de shell pour le rendre permanent).
Pour cela il vous faut avoir le programme most (''sudo apt-get install most'' sous debian). On peut également lancer man avec une option:

<code>$ man --pager=most ls</code>

Ou pour conserver son pager par défaut on peut aussi ajouter ces lignes dans ~/.Xdefaults et sourcer:

<code>*colorULMode:on
*underLine:off
*colorBDMode:on
*colorUL:yellow
*colorBD:green</code>

Pour la liste des couleurs disponibles voir ''/etc/X11/rgb.txt'' (ce fichier n'est pas présent sous ubuntu intrepid et plus récent, cf. [[https://bugs.launchpad.net/bugs/300935|bugreport #300935]].

===== INFO =====

Il arrive parfois que la page de manuel ne donne que très peu d'informations. Cela signifie que la documentation est disponible sous une autre forme. Ici je pense notamment à info bien sûr, qui est une forme de documentation fournie par GNU et qui est beaucoup plus interactive que les pages de manuel man.
   
Vous pouvez voir un exemple de documentation:

<code>$ info wget</code>

Comme je l'ai dit c'est intéractif. Pour rentrer dans un chapitre, vous mettez votre pointer dessus (par exemple dans wget sur * Invoking) et  faites entrée. Pour allez à la page suivante c'est 'n', la page précédente c'est 'p' et pour remonter dans l'architecture de la documentation c'est 'u'. (n pour next, p pour previous).

La commande info et son format sont très puissants.

Nous avons ici des pages de manuel qui (même si elles sont aussi standardisé) permettent de faire beaucoup plus de choses ; et qui, dans le cas des très grosses documentation, permet d'être beaucoup moins inbuvables.
    
Note: Vous obtenez une espèce de "page d'accueil" si l'on peut dire en tapant simplement info dans un terminal. Cette page est statique et ne change pas en fonction des pages qui sont ajoutés ou non.

Testez:
<code>$ info info</code>

Entrez ensuite dans le mode 'menu' en tapant simplement 'm'. Jouez avec la touche tab pour voir tous les menus disponibles pour la section où vous êtes (ça vous évite de descendre en bas d'une page pour ralier le menu que vous cherchez). Il y a dans cette partie des petits exercices avec des pages cachées que vous devez trouver.
    
Si problèmes, voir:
<code>$ info coreutils</code> puis [m] puis ls


===== PAS DE DOCUMENTATION ? =====

"//Hé ma'mselle ma'mselle, pour mon programme y'a ni man ni info qu'est-ce que j'fais ?//"

Et bien mes chers petits, bien que ça soit rare, ça peut en effet arriver. Certains disent que la qualité d'un programme se reconnaît à la qualité de sa documentation.

Au-delà de la particularité trollesque de cette affirmation, on peut en effet se poser des questions. Cependant, il existe  forcément une documentation quelque part. Un man vlc ne vous apprendra pas grand chose. Un info vlc ne vous en dira pas plus.

Si vous ouvrez vlc version graphique, dans l'encart "Aide", vous n'avez qu'un malheureux "A propos" qui se sent bien seul. Si vous aimez démarrer pour quelques raisons que ça soit vlc en mode ncurses, l'aide ne vous apprend rien de plus qu'à vous déplacer dans l'interface curses.

Alors comme beaucoup, une très grosse documentation se trouve sur le site web : videolan.org section documentation/faq/wiki. 

"//Ouai mais ma'mselle, pas envie de lancer mon mastodonte de firefox ou mon lynx quand bien même si léger pour juste trouver l'option-a-la-con mais dont je ne vais pas pouvoir me passer.//"

Alors oui, vous pouvez toujours farfouillez dans votre mode graphique jusqu'à trouver le Saint Graal. Cependant si on veut rester dans notre bon  vieux terminal, VLC a _quand_ même mis quelque part un erzats d'aide. Ou tout du moins, il est possible de lister toutes les options disponibles  accompagnées d'une brêve définition. Pour ce faire, il suffit simplement de faire un ''vlc --help | less'' ; ou bien encore un ''vlc --help | grep fullscr'' pour n'avoir que ce que l'on cherche.

Remarquez au passage que plus d'options sont disponibles avec la commande ''--long-help'' à laquelle on peut rajouter ''--advanced''.

Enfin sachez qu'il est toujours _très_ intéressant de parcourir le dossier  /usr/share/doc d'un programme. On y retrouve souvent de choses sympathiques, comme la documentation en .html, ou encore des fichiers de configuration d'exemples, parfois des scripts supplémentaires, etc.

Pour rester sur vlc, il vous ai fourni les fortunes du canal des développeurs de vlc dans ce dossier /usr/share/doc/vlc/fortunes.txt.gz et généralement /usr/share/doc/&lt;program&gt; contient ce qui se trovuait dans les sources du programme (autres que le code lui-même)

<code>$ zless /usr/share/doc/vlc/fortunes.txt.gz</code>

===== CONCLUSION =====

Voilà donc vous voyez rien de bien sorcier dans tout cela, sinon qu'il faut évidemment taper quelques lettres dans un terminal. Vous apprendrez  beaucoup sur vos programmes. D'ailleurs un bon réflexe à avoir avant de  lancer pour la première fois un programme et de faire : ''programme -h'' ou  ''programme --help''  voir même ''man program'' histoire de voir dans quoi on va mettre les pieds.
    
Enfin pour finir sur un ton joyeux, les mans sont très souvent le support de blagues. Vous pouvez installer par exemple les asr-manpages et funny-manpages qui regroupent quelques perles pour passer un bon moment (sous debian, vous pouvez les  lister (une fois installée bien sûr) en faisant un :

<code>$ dpkg -L asr-manpages | grep "/usr/share/man/"</code>
   
Par exemple man whack pour tout savoir sur comment bien bousiller une imprimante, y'a guru aussi, nuke, uubp et bien sûr l'inévitable : man rtfm (ou encore man sex pour le Wolowitz qui est en vous).

Donc pour la voir elle ça sert à rien de faire man 1 date, il faut faire man /usr/share/man/man1/date.1fun.gz

Un autre exemple de blague à propos notamment d'emacs sur le système Plan9 : [[http://plan9.bell-labs.com/magic/man2html/1/emacs|http://plan9.bell-labs.com/magic/man2html/1/emacs]]

Une dernière pour la route : Pour avoir vos man en html vous pouvez utiliser le programme man2html qui est bien pratique.