LA doc - suite

Page principale

Répondre à ce message
Auteur: Manu Rouat
Date:  
À: La Guilde
Sujet: LA doc - suite
Salut,


j'ai htmlise mon article (remanié) de la doc pour linux - il
devrait apparaitre sur le site bientot.

Cela dit, je reposte quand meme la version ascii, pour notre ami
patrick dupre LCMI a qui ca peut etre bien utile.



LA DOCUMENTATION POUR LINUX
***************************

Les débutants s'en sont aperçus, la documentation concernant
linux est riche, complète, mais éparse! Dans cet article,
j'essaye de mettre un peu d'ordre la dedans.


La page 'man'
************

Tout système Unix possède un ensemble de pages de documentation
connues sous le non de pages 'man'. Pour connaitre les détails
et options d'une commande Unix,il suffit de taper "man <commande>".
Par exemple, 'man df' me dit:


DF(1)                                                       DF(1)


NAME
       df - summarize free disk space


SYNOPSIS
       df   [-aikPv]   [-t   fstype]   [-x   fstype]  [--all]  [--inodes]
       [--type=fstype] [--exclude-type=fstype] [--kilobytes] [--portabil-
       ity] [--print-type] [--help] [--version] [filename...]


DESCRIPTION

etc...

Evidemment, il faut connaitre au moins le nom de la commande pour pouvoir
consulter sa page man. Cependant, la plupart des pages man se terminent
par un certain nombre de références à d'autres commandes liées de près ou
de loin à celle dont vous venez de consulter la page man.
Par ex, la fin de la page man pour 'lpd' est:

SEE ALSO
     lpc(8),  pac(1),  lpr(1),  lpq(1),  lprm(1),  syslog(3),  printcap(5)




Notez bien que la page man ne concerne pas que des commandes Unix.
Ainsi, il existe des pages man pour le langage C (man printf) ou
encore Tcl. Certains fichiers de configuration ont aussi leur page man
(par ex '/etc/printcap' --> 'man printcap')

Parfois, il existe plusieurs pages de man pour un même terme
- par exemple, 'split' est un terme Unix, ainsi que Tcl. Par défaut, man
affiche la première page qu'il trouve. Pour les faires défiler toutes,
utilisez l'option -a: 'man -a split'

'Man' a d'autres options - pour les connaitres , 'man man' bien sur!



La page 'info'
**************

Le projet GNU a imaginé un autre format de doc en ligne, il
s'agit du format 'info'. C'est le format officiel de GNU, mais
assez peu de gens les ont suivis. Plus puissant que le format man,
il est aussi plus difficile à manipuler. Il convient de le connaitre,
car assez souvent, les pages info sont plus à jour et plus complètes
que les pages man. De plus, le système de références croisées est
assez évolué.
Pour y acceder , il suffit de taper 'info <commande>' voire 'info'
tout court.


Il est possible de transformer certaines docs de format info en format
HTML - il faut pour cela récuperer le fichier 'texinfo' qui a servi à
l'origine à génerer les fichiers info. Ce sont des fichiers se terminant
par '.texi' , ils sont très souvent disponibles dans les tar.gz des sources
de la commande. Il suffit ensuite de lui passer une moulinette, en
l'occurence un script perl nommé 'texi2html'.

D'autres moulinettes du même genre existent, par exemple 'man2html'
ou encore 'man2ps', utiles si vous voulez vous constituer une
documentation en-ligne ou papier.
Il existe un certains nombres d'utilitaire assez sympas qui facilitent
l'exploration des pages man ou des pages info.
Parmi eux, citons 'xman', (x)emacs ,ou encore le lecteur de doc
en ligne de KDE.



Les HOWTOs
**********

Tout le monde a un jour ou l'autre consulté un 'HOWTO'.
Ces documents, disponibles en formats divers (ascii,HTML,PS) sont
en général une description d'une démarche à suivre pour mettre en
place un service (site web, acces internet...), configurer du matériel
(carte son, video...). De manière globale, les HOWTOs ne sont pas
très détaillés - ils traitent du cas général, mais c'est très souvent
suffisant pour s'attaquer à un probleme assez large, qui dépasse le
cadre (étroit) de la page man.

La plupart des distributions incluent ces HOWTOs, sur ma redhat
ils se trouvent dans /usr/doc/HOWTO.
La plupart de ces HOWTOs ont été traduits (et fort bien) en français,
mais il convient de noter que les traductions sont un peu en retard sur
les 'officiels'. Si vous êtes sur un sujet 'chaud', il est souvent
préférable de consulter aussi le HOWTO en V.O .


Le /usr/doc
***********

Sur la plupart des distributions linux (en particulier Redhat, Suse,
Slackware et Debian) il existe un répertoire privilegié pour la
documentation, c'est le /usr/doc - par exemple, j'ai chez moi un
répertoire /usr/doc/automake qui contient:

ll /usr/doc/automake-1.3/
total 221
-rw-r--r--   1 root     root          171 Jan 23  1996 AUTHORS
-rw-r--r--   1 root     root        17989 Jun  2  1997 COPYING
-rw-r--r--   1 root     root       161460 Apr  6 06:44 ChangeLog
-rw-r--r--   1 root     root         7831 Mar 27 22:45 INSTALL
-rw-r--r--   1 root     root         6147 Apr  6 00:50 NEWS
-rw-r--r--   1 root     root         1278 Dec  1  1997 README
-rw-r--r--   1 root     root         2571 Apr  5 23:34 THANKS
-rw-r--r--   1 root     root        20605 Apr  5 21:46 TODO



rien de bien excitant en l'occurence - mais d'autres répertoires
peuvent etre bien plus riches:

ll /usr/doc/gawk-3.0.3/ 
total 1687
-rw-r--r--   1 root     root         1580 Oct 13  1995 ACKNOWLEDGMENT
-rw-r--r--   1 root     root        18007 May  2  1997 COPYING
-rw-r--r--   1 root     root         2831 Dec 11  1996 FUTURES
-rw-r--r--   1 root     root         7721 Dec 27  1995 INSTALL
-rw-r--r--   1 root     root          649 Aug 16  1995 LIMITATIONS
-rw-r--r--   1 root     root        57230 May 11  1997 NEWS
-rw-r--r--   1 root     root          931 May 14  1997 PORTS
-rw-r--r--   1 root     root         3545 Dec 27  1995 POSIX.STD
-rw-r--r--   1 root     root         3166 May  2  1997 README
drwxr-xr-x   2 root     root         1024 Jun 27 04:28 README_d/
-rw-r--r--   1 root     root       225769 May 14  1997 awkcard.ps
-rw-r--r--   1 root     root      1389906 May 14  1997 gawk.ps



Ici, il y a toute une doc en postscript sur gawk!


C'est aussi souvent dans le /usr/doc qu'on trouve les HOWTOs, FAQs etc.
Si vous n'avez pas de /usr/doc, essayez eventuellement /usr/share/doc.



Les livres
**********

Notez bien qu'avant toute chose, Linux est un Unix, donc un bon
bouquin sur Unix devrait vous en apprendre pas mal. Cela dit, il
existe d'excellents ouvrages sur Linux (et sur les divers outils
disponibles sur linux), notamment dans la collection O'Reilly.
(Personnelement, j'ai 'Linux In A Nutshell' de O'Reilly)

Certains ouvrages sont disponibles sur le net, en particulier:

    'Linux System Adminitrators Guide' de Larz Wirzenius 
    'Linux Network Administrators Guide' de Olaf Kirch


(tous deux disponibles sur le site du LDP - voir plus bas)

ou bien encore 'Le Guide du Rootard', qui reste une des meilleures
réferences françaises.
Pour les débutants, un bon livre reste à mon avis un bon investissement,
surtout si vous ne connaissez pas du tout Unix.

Journaux/magazines
******************

Le premier journal linux est le 'Linux Journal' (en Anglais), mensuel.
C'est un magazine très sérieux, et dont la qualité augmente constamment.
Il est très facile de s'y abonner (voir leur site).

Sur internet, il existe aussi un magazine en ligne qui est une mine d'or
en trucs et astuces diverses, c'est la 'Linux Gazette'. A consulter!

Notons aussi la revue 'Dream', qui est consacrée aux OS alternatifs
(mais linux y a la part de plus en plus belle), avec laquelle vous aurez
de surcroit un cdrom avec des applis, des docs....

Plus spécifiquement, en France un nouveau petit canard vient de naitre:
'Linux magazine' - des débuts un peu timides, mais qui promettent.



La recherche de solutions
*************************

Outres tous les documents sités plus haut,il existe d'autres moyens
de trouver des solutions a ses problemes. Vous en connaissez au
moins un, c'est la mailing-list guilde. Il y a également les forums
de discussions sur USENET. Les groupes les plus intéressants pour le
sujet qui nous concerne sont:

    fr.comp.os.linux
    comp.os.linux
    comp.os.linux.setup
    comp.os.linux.applications


Cela dit, ces groupes ont un traffic élevé, et disons que c'est un peu
le b****l la dessus. Une solution intéressante consiste à utiliser un
moteur de recherche sur les archives de ces groupes. Cela peut se faire
sur le site suivant:

    http://www.dejanews./com


C'est en fait le moyen le plus puissant pour trouver une réponse à un
problème tres précis. En effet, vu la masse de posts qui passent tous les
jours, il y a presque certainement quelqu'un quelque part qui a eu le
meme probleme que vous, a posé la question, et a eu (espérons le) une
réponse.

Si malgré tout vous ne trouvez pas de solution par ce moyen la, postez
votre question sur le forum le plus approprié. Notez que poser une question
sur 'awk' ou le langage perl sur un forum linux n'est pas la meilleure
solution (et vous risquez meme de vous faire recevoir froidement).
Notez aussi que la plupart des forums ont une FAQ qu'il convient évidemment
de lire avant de s'aventurer.


Les sites WWW
*************

Linux étant un enfant d'internet, il n'est pas étonnant que la grande
majorité de la documentation linux ait été créee et soit disponible sur internet.
Certains sites ne sont d'ailleurs que des observatoires (ils testent les pages
principales de certains sites , et affichent quotidiennement les liens
vers celles qui ont étés modifiés), c'est le cas de 'WebWatcher' par exemple.

D'autres comme 'Freshmeat' permettent de savoir quasiment en temps réel l'évolution
de différents projets - chaque nouvelle version d'un logiciel/projet est annoncée
avec un court descriptif, et des liens vers les sites concernés. C'est le moyen
ideal pour se tenir au courant de ce qui se fait sans avoir à surfer comme un
fou.    


Pour finir, il faut absolument connaitre les sites 'Scientific Apps On Linux'
et 'Linux Applications Page' , qui sont incontournables si vous cherchez
un type d'application particulier (genre un lecteur de fichier MP3, c'est la
mode en ce moment...).


Voici une liste des sites les plus intéressants:


Documentation:
--------------
- Linux Documentation Project http://sunsite.unc.edu/LDP/
- XFree86                     http://www.xfree86.org
- le guide du rootard         http://www.freenix.fr/linux/Guide/
- HOWTOs              http://linux-howto.com
- HOWTOs en francais:         http://www.freenix.fr/linux/HOWTO/Liste-des-HOWTO.html


Géneral et applications:
------------------------ 
- Noyau linux                 http://www.linuxhq.com/
- Home Linux:                 http://www.linux.org/
- Linux applications page:    http://www.xnet.com/~blatura/linapps.shtml
- Applis scientifiques        http://ftp.llp.fu-berlin.de/lsoft/



Journaux/magazines:
-------------------
- Linux journal               http://www.linuxjournal.com/ 
- Linux Gazette              http://www.ssc.com/lg/


Nouvelles/observatoires:
------------------------
- articles et nouvelles       http://www.linuxresources.com
- observatoire de sites       http://www.math.jussieu.fr/~fermigie/lcenter/
- observatoire de sites       http://webwatcher.org/
- developement d'applis       http://freshmeat.unreal.org/





--
"In the Beginning was the Word - then came the fucking word processor.
Then came the thought processor, then came the Death of literature.
And so it goes." The Poet - Hyperion