[couverture de Linux Dossiers 2]
[couverture de Linux Magazine 53]

La documentation de Perl

Article publié dans Linux Magazine 53, septembre 2003. Repris dans Linux Dossiers 2 (avril/mail/juin 2004).

Copyright © 2003 - Philippe Bruhat.

[+ del.icio.us] [+ Developers Zone] [+ Bookmarks.fr] [Digg this] [+ My Yahoo!]

Chapeau de l'article

The following two statements are usually both true: There's not enough documentation. There's too much documentation.

-- Larry Wall, perl5-porters@perl.org, 1er septembre 1997

Perl est un langage de programmation unique, avec de nombreuses manières très caractéristiques de faire les choses. Le problème pour les débutants (et les autres) est de savoir où trouver l'information qu'ils cherchent dans la masse de documentation existante.

L'objectif de cet article est de vous fournir les moyens de trouver seul la réponse aux questions que vous vous posez, ou au moins de progresser aussi loin que possible avant de finir par poser la question sur un forum ou une liste de discussion.

Le manuel de Perl

man perl

Sous Unix, la documentation est disponible sous la forme de pages de manuel. Pour simplifier la recherche, les pages de manuel sont divisées en sections numérotées qui concernent différents aspects du système :

  1. les programmes exécutables et commandes shell,

  2. les appels systèmes (fonctions du kernel),

  3. les appels de librairies (fonctions dans les librairies système),

  4. les fichiers spéciaux (ceux qu'on trouve en général dans /dev),

  5. les formats de fichiers (de configuration, en général),

  6. les jeux

  7. les paquetages de macros et leurs conventions,

  8. les commandes d'administration système (réservées habituellement à root)

Nous trouverons de la documentation au sujet de Perl et des modules Perl dans les sections 1 et 3 du manuel. La documentation concernant le programme perl et le langage Perl est dans la section 1 du manuel, et la documentation concernant les modules (librairies) Perl est dans la section 3. Sur certains Unix, la documentation des modules est même dans la sous-section 3pm (pour Perl module).

La page de manuel principale, perl(1), est en fait une liste des pages de manuel concernant Perl (dans la section 1 uniquement). La version 5.8.0 de Perl est livrée avec 121 pages de manuel dans la seule section 1. On comprend pourquoi le manuel a été fractionné en plusieurs parties ! Et encore, ce nombre n'inclut pas la documentation des modules (qui se trouve en section 3).

Ces pages de manuel sont regroupées en plusieurs catégories : vue d'ensemble, tutoriels, manuels de référence, architecture interne et interfaces avec C, divers, spécificités liées à la langue, et enfin spécificités liées à la plateforme.

Pas moins de 29 nouvelles pages de manuel sont apparues entre la version 5.6.1 et la version 5.8.0 de Perl. Too much documentation, vraiment ?

perldoc

perldoc est le programme de recherche et d'affichage de la documentation Perl. Même si les pages de manuel d'un module n'ont pas été générées et installées sur le système, perldoc est capable de les retrouver dans les modules (l'utilisation de pod permet de stocker la documentation dans le source du script ou module). En général, man est un peu plus rapide que perldoc.

Voici quelques exemples d'utilisation de perldoc :

Le web

Il existe beaucoup de sites web consacrés à Perl. Il s'agit de sites d'aide, de sites communautaires organisés autour de forums ou encore de sites d'information.

La documentation officielle en ligne

Les sites d'aide

Certains sites sont spécifiquement conçus pour vous aider, quel que soit votre niveau. La plupart des sites consacrés à Perl sont en anglais.

Sites d'information

La communauté Perl est très active. Au-delà de la documentation, http://use.perl.org/ est un site qui regroupe les actualités de la communauté Perl. On y trouve également les blogs d'un certain nombre de membres de la communauté. C'est également là qu'est diffusé le compte-rendu hebdomadaire de P5P, rédigé par Rafael Garcia-Suarez, l'un des fondateurs de Lyon.pm.

http://www.perl.com/ est le site Perl géré par O'Reilly, dans le cadre de son O'Reilly Network. On y trouve des articles écrits par des membres plus ou moins connus de la communauté Perl, sur des sujets aussi variés et pointus que mod_perl, Template-Toolkit, mais également les résumés hebdomadaires des listes de diffusion consacrées à Perl 6. Le tout entrecoupé de publicités pour les livres O'Reilly.

http://www.perl.org/, quant à lui est le site de la communauté Perl, avec des liens vers tout ce qui est Perl : les Perl Mongers, la Perl Foundation, l'histoire de Perl, les livres, les revues, la documentation. Comme le dit le slogan du site : When you need perl, think perl.org.

La fondation Perl (http://www.perlfoundation.org/) est une association à but non lucratif américaine qui se consacre à l'avancement de Perl à travers la collaboration des différents acteurs de la communauté. Elle coordonne les efforts des divers groupes d'utilisateurs pour organiser des conférences (YAPC) ou financer le développement du langage (par le biais de bourses).

Les groupes de discussion

Le newsgroup comp.lang.perl est utilisé pour les questions Perl, mais il existe des newsgroups plus spécialisés :

Note : tous ces groupes portent des discussions en anglais.

Les listes de discussion

Les principales listes de discussion consacrées à Perl (hormis les listes des divers groupes de Perl mongers) sont listées sur http://lists.perl.org ou http://lists.cpan.org/.

Ce n'est généralement pas une bonne idée de poser une question sur votre script qui "ne marche pas" sur une liste qui n'a pas pour rôle de répondre aux questions. Quelques exemples de telles listes :

Listes et archives

Les listes de discussion consacrées à Perl sont listées sur la page http://lists.perl.org/, avec les instructions nécessaires pour l'abonnement et le désabonnement. Il y en a tellement qu'on ne peut toutes les citer. La plupart sont évidemment en anglais.

La plupart des listes de distribution recensées sur http://lists.perl.org/ sont archivées sur http://archive.perl.org/ (alias de http://archive.develooper.com/, oui, avec deux 'o').

Il existe également une passerelle NNTP pour accéder aux mailings-list Perl comme s'il s'agissait d'un newsgroup. Celle-ci est hébergée par perl.org, et accessible à nntp://nntp.perl.org. Une interface web est disponible à presque la même adresse : http://nntp.perl.org.

http://groups.google.com/ les reproduit également, sous la hiérarchie perl.*.

Listes en français

Si vous ne parlez pas assez bien anglais pour poser des questions, ou si vous voulez parler de vos problèmes Perl entre francophones, il existe quelques listes en français.

perl@mongueurs.net est la liste technique consacrée à Perl. Cette liste est en fait la migration de la liste paris-pm-list@pm.org, il est possible qu'elle n'existe pas encore au moment où vous lirez ces lignes. En cas de doute, consultez http://paris.mongueurs.net/mail.html ou http://www.mongueurs.net/services/listes.html.

Il existe un certain nombre de listes "locales", animées par des groupes d'utilisateurs de Perl répartis dans toute la France :

Les listes hébergées par le serveur des mongueurs (en mongueurs.net) sont listées sur http://www.mongueurs.net/services/listes.html.

Avant de poser une question...

Nous abordons maintenant plutôt les questions de débogage et de recherche d'erreur que de documentation proprement dite.

Comme vous programmez, vous allez forcément buter sur un problème, qui va vous bloquer. C'est notre lot à tous. Avant de vous faire malmener sur une liste de discussion ou un forum à cause d'une question idiote ou mal formulée, apprenez à résoudre vos problèmes tous seuls, et à poser la bonne question.

Pour cela, je vous renvoie à deux articles écrits par des maîtres de Perl.

Apprenez à résoudre votre problème tout seul

Dans brian's Guide to Solving Any Perl Problem, brian d foy explique sa méthode pour résoudre tous les problèmes Perl. Si jamais cela ne marche pas, il sera toujours temps de poser la question sur une liste de discussion ou un forum. http://www.pair.com/~comdog/brian's_guide.pod

Ce document me paraît tellement important à lire que je vous l'ai traduit. Vous pouvez le consulter en français sur http://articles.mongueurs.net/traductions/guide_brian.html

Sachez poser la bonne question

Il y a certaines questions auxquelles personne ne répond, ou alors par des sarcasmes (ou des flammes). Dans Why Questions go Unanswered, Mark-Jason Dominus explique pourquoi certaines questions n'obtiennent jamais de réponse, et surtout comment formuler une question pour obtenir une réponse. http://perl.plover.com/Questions.html

perl aussi peut vous aider

Perl dispose de plusieurs manières de vous aider à trouver les erreurs dans vos programmes. Celles-ci n'étant pas activées par défaut (c'est ce qui permet de ne pas déclarer les variables dans un mini-programme qui ne sera utilisé qu'une fois), il vous faudra le faire explicitement.

Les magazines

Il existe plusieurs revues consacrées exclusivement à Perl, et certaines revues plus générales disposent également d'une rubrique Perl.

En anglais

En français

Linux Magazine France, depuis le numéro 41, publie chaque mois un article écrit par des membres des Mongueurs de Perl, la version française des Perl Mongers. Il s'agit d'une association qui se consacre à la promotion de Perl en France, par l'organisation de conférences (http://yapc.mongueurs.net/), en soutenant les groupes locaux d'utilisateurs (http://www.mongueurs.net/), et en faisant du prosélytisme partout où c'est possible.

Après l'introduction à Perl de Sylvain Lhullier, vous pourrez lire ici des articles variés sur l'ensemble du spectre d'application de Perl, avec pour objectif de présenter la manière Perl de faire les choses. Que dire d'autre, sinon qu'il s'agit d'articles sur Perl et ses techniques, écrits par des spécialistes du langage et de ses applications, et que notre absence du numéro 51 est une malencontreuse erreur de calendrier que nous nous efforcerons de ne pas répéter... ;-)

Ces articles sont tous archivés sur http://articles.mongueurs.net/, si vous avez raté les épisodes précédents. Sylvain a reformaté (et corrigé) ses articles d'introduction en un seul document, disponible en PDF à l'adresse suivante : https://formation-perl.fr/guide-perl.html

Les livres

Les livres sur Perl sont légion. Les bons comme les mauvais. Le site http://books.perl.org/ liste 113 livres en anglais consacrés à Perl, classés par auteur, éditeur, etc., mais le site lui-même contient peu de critiques de livres, et les notes ne suffisent pas à se faire une idée de l'intérêt de tel ou tel livre peu connu.

En général, les bons livres sur Perl sont ceux recommandés, voire écrits par des membres de la communauté Perl. Visitez un peu le web, ou posez des questions sur les listes de discussion pour vous faire une idée.

On trouve des critiques des nouvelles parutions sur la plupart des sites communautaires : http://use.perl.org/, http://www.perlmonks.org/, http://www.perl.com/. Sinon Google saura vous en trouver...

Conclusion

La réponse à de nombreuses questions se trouve dans la documentation (et c'est de plus en plus vrai, car un gros effort a été fait dans les versions récentes de Perl pour améliorer encore la documentation disponible), il suffit de savoir chercher. RTFM, quoi. ;-)

J'espère donc que cet article vous aura rassuré après le choc qu'a dû être normalement pour vous le premier appel à man perl. N'imprimez pas la documentation complète de Perl, c'est du gaspillage de papier. (Si vous tenez vraiment à avoir du papier, achetez des livres, c'est plus beau et plus facile à ranger...) La documentation en ligne permet des recherches fructueuses et rapides, et la maîtrise de perldoc est un atout indispensable pour les développeurs Perl.

L'auteur

Philippe 'BooK' Bruhat, <book@mongueurs.net>.

Philippe Bruhat est vice-président de l'association les Mongueurs de Perl (http://www.mongueurs.net/), membre du groupe Paris.pm et de l'équipe organisatrice de la conférence YAPC::Europe qui s'est déroulée à Paris en juillet 2003 (http://yapc.mongueurs.net/). Il est consultant en sécurité et l'auteur des modules Log::Procmail, HTTP::Proxy et Regexp::Log, disponibles sur CPAN.

Pour ce qui concerne la documentation, il a traduit les chapitres 3 à 9 d'Amelia (Programming Perl, 3rd edition) en français pour O'Reilly.

[IE7, par Dean Edwards] [Validation du HTML] [Validation du CSS]