Beefy Boxes and Bandwidth Generously Provided by pair Networks
P is for Practical
 
PerlMonks  

Comment on

( #3333=superdoc: print w/ replies, xml ) Need Help??
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


In reply to The sad state of Perl documentation by SuperCruncher

Title:
Use:  <p> text here (a paragraph) </p>
and:  <code> code here </code>
to format your post; it's "PerlMonks-approved HTML":



  • Posts are HTML formatted. Put <p> </p> tags around your paragraphs. Put <code> </code> tags around your code and data!
  • Read Where should I post X? if you're not absolutely sure you're posting in the right place.
  • Please read these before you post! —
  • Posts may use any of the Perl Monks Approved HTML tags:
    a, abbr, b, big, blockquote, br, caption, center, col, colgroup, dd, del, div, dl, dt, em, font, h1, h2, h3, h4, h5, h6, hr, i, ins, li, ol, p, pre, readmore, small, span, spoiler, strike, strong, sub, sup, table, tbody, td, tfoot, th, thead, tr, tt, u, ul, wbr
  • Outside of code tags, you may need to use entities for some characters:
            For:     Use:
    & &amp;
    < &lt;
    > &gt;
    [ &#91;
    ] &#93;
  • Link using PerlMonks shortcuts! What shortcuts can I use for linking?
  • See Writeup Formatting Tips and other pages linked from there for more info.
  • Log In?
    Username:
    Password:

    What's my password?
    Create A New User
    Chatterbox?
    and the web crawler heard nothing...

    How do I use this? | Other CB clients
    Other Users?
    Others surveying the Monastery: (9)
    As of 2014-09-02 10:20 GMT
    Sections?
    Information?
    Find Nodes?
    Leftovers?
      Voting Booth?

      My favorite cookbook is:










      Results (21 votes), past polls