Front page | perl.perl5.porters |
Postings from November 2003
My friend has recently graduated from the Technion in Electrical Engineering. He knows English very well, but is short of practical experience in programming. To remedy this, he decided to install Linux on his computer, and to learn UNIX and Perl programming thoroughly in order to become a better hacker. Now, he learned some Perl by reading my Perl for Perl Newbies notes[1]. However, I only teach there a limited subset of Perl which just aims to get people started writing their own code. It is not suitable for programming Perl idiomatically, much less for reading the code of experienced programmers. At one point, I suggested the reader that he can now go over the man pages and should. However, my friend complained that the man pages were hard to understand, and I can relate to it, as they are certainly not intended for people with very little background in UNIX. He's using the Perl that ships with RedHat Linux 9.0. I can instruct him to install Perl 5.8.2 or bleadperl, if the man pages there are substantially better. I recommended him to buy the Camel Book, which is a good read even for people who are very good programmers. Still, it was a bit pricy for him (220 NIS or $40). At the moment he is using a pirated version he found on the Net somewhere. (of the second edition). For a long time, I complained that the Perl man pages were probably intended for either experienced Perl 4 programmers or for seasoned UNIX shell/sed/awk/whatever hackers. But naturally, reality wanted otherwise and Perl is now being learned by people with very little experience of either. Those people could perhaps get started by reading Simon Cozens' "Beginning Perl" book or whatever, but still need a good reference. This is either "Programming Perl" or the man pages. A good idea to revitalize them and adapt them to our needs, would be to start a Phalanx like project for documentation. Namely, we: 1. Collect user stories on what they did not understand in the documentation. 2. Assign volunteers to remedy these issues. 3. Assign volunteers to go over sections of the man pages and try to paraphrase them to make them clear enough. 4. Collectively decide where the man pages could use some re-organization, and re-organize them. Once we're through, we release Perl 5.8.3 with all of the changes applied. (or maybe delay it to Perl 5.10.x due to configuration management issues) Are you with me? I volunteer to take the initial effort and get this effort going. One thing that has to be understood is that the man pages should be clear, explanatory, and organized. We cannot leave "transliterate" as such because it's a piece of UNIX jargon and not plain English. (for example). Regards, Shlomi Fish [1] - http://vipe.technion.ac.il/~shlomif/lecture/Perl/Newbies/ ---------------------------------------------------------------------- Shlomi Fish shlomif@vipe.technion.ac.il Home Page: http://t2.technion.ac.il/~shlomif/ An apple a day will keep a doctor away. Two apples a day will keep two doctors away. Falk Fish