As someone who hasn't been using some Unix style operating system much before (Just Amiga OS/Workbench and Windows - recently started with Linux) I'm not too used on reading documentation that comes with programs. And even when I did - it was usually crap.

Even using Perl for freelance web development for the past ~3 years didn't help much with that. I guess I assumed that it's documentation is like any other.

And exception to that was perltoot - I stumbled upon it somewhere on Internet while I was searching for Perl OOP Tutorial.

Either way, recently I got some spare time and I gave a chance to Perl's documentation. Downloaded from Internet, in compiled HTML (chm) file type. Maybe reading JAVA built-in docs (needed something for University, and that was only thing about JAVA handy) added to it.

Revelation !

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 ...

Oh now I feel bad for not taking a look at it before!

Have you tried freelancing? Check out Scriptlance - I work there.
  • Comment on How I started reading Perl's (builtin) documentation.

Replies are listed 'Best First'.
Re: How I started reading Perl's (builtin) documentation.
by Zaxo (Archbishop) on Oct 06, 2005 at 13:02 UTC

    I learned perl from the standard pod and example code. Once I learned enough syntax to do some damage, my favorite strategy was to review the first parts of perlfunc once a week or so. A good notion of what builtin names are available and what they apply to is a great help.

    After Compline,

Re: How I started reading Perl's (builtin) documentation.
by ghenry (Vicar) on Oct 06, 2005 at 13:09 UTC

    Update: If you need to read it online and not in the chm format:

    You can even download the whole lot in PDF format, as shown on the front page.

    Walking the road to enlightenment... I found a penguin and a camel on the way.....
    Fancy a Just ask!!!

      Thanks for posting this, ghenry. Even though the docs are bundled, I really like's formatting and find myself perusing the online version often. For those rare cases when I'm not online, now I'll take my favorite with me. :-)

Re: How I started reading Perl's (builtin) documentation.
by pg (Canon) on Oct 06, 2005 at 15:10 UTC
    "Way better than Java's. Way better than any documentation that I saw before ..."

    It is more close to reality and fair to put it in this way: If we are talking about the document for each module, Java's is better than Perl's in most cases; but Java lacks the kind of documentation like perltoot, perlfaq etc., which put things together for you.

    When you read Java document, you may get a very clear picture of what the module is doing but it does not usually contain information as how to use the module in an application with other related modules.

    However, the other side of the life is that, there are big knowledge bases for both languages on internet and in book stores beyond pure documentation.

Re: How I started reading Perl's (builtin) documentation.
by Hue-Bond (Priest) on Oct 06, 2005 at 19:19 UTC

    On a Unix, one can do man -Tps perlref > and get documentation in postscript format. Then one can scale that down in order to save some trees (using pstops for instance) and print it on both sides (to save more trees). Then one can bind it and read it instead of novels when going to work or back.

    That's what I did. My journeys to/from work will no longer be the same.

    David Serrano

Re: How I started reading Perl's (builtin) documentation.
by blazar (Canon) on Oct 06, 2005 at 14:52 UTC
    My first steps into the world of Perl were greately aided by the friends of clpmisc. As I asked what in fact were faqs, they pointed me perldoc -q whatever, and then to relevant perldoc entries, and it didn't take long get addicted to perl's documentation. Occasionally under Windows I check AS's HTMLized version, but the cli is my preferred entry point to it...
Re: How I started reading Perl's (builtin) documentation.
by davido (Cardinal) on Oct 07, 2005 at 06:33 UTC

    I read the Llama book, Learning Perl. Then I started in on the Camel book, Programming Perl. But on first reading, I got a little hung up with references and objects. Following a path of lesser resistance and greater interest, I picked up the Owls book, Mastering Regular Expressions. I really got into that book; it was fascenating to me for some reason.

    Then I started digging around for additional information on objects and references. That's when I really got interested in the POD. I uploaded the complete POD in HTML format to my Sharp Zaurus PDA, and for a week or two took that thing everywhere, reading whenever I had a spare moment. I didn't stop until I had read all of it, except for the platform-specific documents. I didn't understand all of it (especially the internals stuff, especially the first time through), but from that point on, the POD became my primary reference. Though it has its quirks, I have to say Perl's POD is one of its best attributes. I refer back to it almost daily.

    Since then, I've read a lot of other Perl books and other peripherally related books, but I keep going back to the POD as the most up-to-date and authoritative place to go to get my questions answered.

    I would assert that you haven't learned Perl until you've really become acquainted with its POD.


Re: How I started reading Perl's (builtin) documentation.
by ady (Deacon) on Oct 07, 2005 at 05:39 UTC
    From which URL did you grab the perldoc in .chm format ?
    best regards
Re: How I started reading Perl's (builtin) documentation.
by Anonymous Monk on Oct 07, 2005 at 16:09 UTC
    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.

      Where are your doc patches? Where is the work you've put into it? How can you demand things of and complain about the work people do on a volunteer basis?

      Besides that, your laundry list of complaints doesn't address his comment at all: he said the Perl documentation is better than any he had see before. Putting aside the impossibility of proving what he has or hasn't seen before, it was a comparitive analysis. Your complaints about the quality of the documentation may indeed be correct (and I'm not saying they are; they sound a bit too much like pissy ranting for me to take seriously), but that's completely missing the point.

      Now, I'll make a prediction: your response (if you respond at all) is going to be even less relevant and coherent than your original rant. So go ahead, give me your best shot, but I'm not going to be surprised.

        I don't demand anything, except honesty. I do retain the right to criticise people, volunteers or otherwise, who don't follow through on their promises. Lies aren't acceptable to many people.

        People who say they're going to do something, and then don't do it, disappoint others. Obviously the people who planned to address problems and then chose not to disappointed a lot of people, self included.

        People coming into the Perl community should know that history, and know that coding with perl isn't all the sunshine and roses that it's portrayed to be by it's breathless enthusisasts. They shouldn't believe promises that the documentation will be cleaned up "real soon now", because that's been false for a long time now. Those promises are still in the documentation; and they're still lies.

        There are issues for and against perl, and in this thread, perl's documentation was being presented as a strength. I felt it was only right to point out the weaknesses, as well; and to prevent others from being mislead by false promises, like I was in thhe past.

        Perl can do good work. It could be better if it were better documented. People in the Perl community complain that they want more supporters and perl enthusiasts, and write long threads wondering how to attract people, but they don't want to do the basics, like document the language cleanly, simply and concisely. Now, I'll make a prediction: your response (if you respond at all) is going to be even less relevant and coherent than your original rant. This is Ad hominem, antagonistic, and completely uncalled for! I'm not "shooting" at you; I'm providing a valid criticism of an otherwise useful language, based upon real world experience. So go ahead, give me your best shot, but I'm not going to be surprised. Nor open minded... it seems. I'm only replying for the benefit of those who might be misled by all the Perl cheerleading, not for your empty minded, selfish complaints. As for you, get lost. No one need empty minded boosterism.