The sad state of Perl Documentation

by SuperCruncher

I have a number of problems with Perl's documentation. The way I see it, the documentation is currently provided through a system of antiquated man pages or automated conversions from these man pages to HTML. Documentation is not provided in formats suitable for printing such as PDF. At one point on my long search around Perl.com I was able to find a PostScript version of the documentation. This was for Perl 5.003 or something old like that. Postscript?! Until starting university, I had not encountered files in Postscript format before (I had heard of it, but not encountered). It seems to be a very common thing on UNIX platforms. So Perl started out on UNIX, maybe it's time to loosen the ties? Granted PS can be converted to PDF using the ps2pdf program, but not everyone has the time or knowledge to get this program.

Perl's documentation has its problems, and even worse is that Perl's competitors (well, I don't consider them competitors as I think Perl is far superior, but..) all have documentation available in many formats. PHP has documentation available in many formats and languages. With Python, it's a similar story. I recognise though that Python might not be an option for the free software purists since according to RMS it is incompatible with the GPL.

I had hoped that new sites like Perl FAQ and Perldoc would improve the situation, but perldoc especially seems to be a simple a re-hashing of the standard docs.

I also have problems with the actual documentation itself in some cases (not the actual format). In this node I complained about how I consider the documentation for exec() in perlfunc to be misleading. More recently, I also had the misfortune of trying to figure out the documentation for chmod(), also in perlfunc. As is common throughout the Perl documentation, the documentation for chmod assumes much knowledge of UNIX. I have used Linux for around 2-3 years now (albeit not on my own PC) and I have never once used the octal numbers as a mode for chmod. The authors of the chmod documentation in perlfunc consider mentioning how to calculate mode values is beyond the scope of the documentation. It's bad enough that Perl doesn't support the symbolic a+r etc. notation, and it's even worse that the documentation for Perl's chmod function doesn't at least include a table with the values of the most commonly used symbolic modes.

Perl does have good documentation provided by O'Reilly in the form the llama and camel books. However, I'm sure most monks will realise that these books (although very useful) are quite costly. At Amazon.co.uk, Learning Perl and Programming Perl currently cost £15.96 and £26.80 respectively.

I'd be willing to try and help out with the Perl documentation, does anyone know who to ask?

And BTW, I know this post would probably have belonged in the "Rant" section of PerlMonks if there was one, but to me it's the one thing of Perl that really needs major improvement