Beefy Boxes and Bandwidth Generously Provided by pair Networks
Perl-Sensitive Sunglasses
 
PerlMonks  

Re: How I started reading Perl's (builtin) documentation.

by Anonymous Monk
on Oct 07, 2005 at 16:09 UTC ( #498248=note: print w/replies, xml ) Need Help??


in reply to How I started reading Perl's (builtin) documentation.

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.

  • Comment on Re: How I started reading Perl's (builtin) documentation.

Replies are listed 'Best First'.
Re^2: How I started reading Perl's (builtin) documentation.
by Anonymous Monk on Oct 07, 2005 at 19:18 UTC

    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.

        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.

        This is one of the drawbacks of using the AM account for posting. People are likely to assume you are someone other than who you are and also to assume that you will behave other than you would normally do so. Post under a real account and people are far more likely to give you the benefit of the doubt. Its only human nature...

        ---
        $world=~s/war/peace/g

          A reply falls below the community's threshold of quality. You may see it by logging in.

Log In?
Username:
Password:

What's my password?
Create A New User
Node Status?
node history
Node Type: note [id://498248]
help
Chatterbox?
and the web crawler heard nothing...

How do I use this? | Other CB clients
Other Users?
Others contemplating the Monastery: (3)
As of 2020-05-27 03:51 GMT
Sections?
Information?
Find Nodes?
Leftovers?
    Voting Booth?
    If programming languages were movie genres, Perl would be:















    Results (152 votes). Check out past polls.

    Notices?