But honestly - I didn't realise so far that Perl's built in documentation is so good. Way better than Java's. Way better than any documentation that I saw before ...

You're kidding, right?!?

Sure, there's a lot of perl documentation; in fact, there's now so much that it's become a byzantine maze of quip ridden, cutsey fluff that's funny at first reading, and annoying forever thereafter.

The regular expression section has yet to be re-written so that it's accessible. They promised to write something better sometime back in 1997; it never really happened. Instead of tearing out bad documentation, people just write more documentation, and put incorrect English suffixes like "toot" on the end. The documentation itself is overly verbose, far too glib, and despite all the verbiage, isn't even always complete.

In perlvar, the list of places where $_ is used automatically is still only a "partial" list!

The single greatest weakness of perl is unpredicted side-effects; and every single perl detractor rightly complains about how difficult it is for a non-expert to guess what perl is doing. We can't even centrally document all the functions that have side effects for the single most glaring embodiement of perl side effects, the $_! Back in 1995, I decided that using $_ wasn't worth the risk of bugs until until the documentation was sorted out, and I could tell what everything did. It's been ten years, and I've more or less learned what $_ does, but the documentation still isn't centralized. When newcomers ask me about details on Perl's side effects, I just turn away and mumble. They're as horrible to keep straight in your head as they've always been, and they're as poorly documented as ever.

Yes, you can learn perl just from the manual pages. I was a broke student, so yes, that's what I did. It's nice that I could, but it's hardly a masterwork of literature. The whole thing needs a massive re-write, and has for ten years. The documentation for Perl5 is so bad that we're re-writing the entire language (Perl6) without ever finishing the documentation for Perl5, because, frankly, it's easier to do a complete re-write than to clearly document all the wierd complexity of Perl as it currently exists.

In reply to Re: How I started reading Perl's (builtin) documentation. by Anonymous Monk
in thread How I started reading Perl's (builtin) documentation. by techcode

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!
  • Titles consisting of a single word are discouraged, and in most cases are disallowed outright.
  • 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, details, 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, summary, sup, table, tbody, td, tfoot, th, thead, tr, tt, u, ul, wbr
  • You may need to use entities for some characters, as follows. (Exception: Within code tags, you can put the characters literally.)
            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.