Coreolyn sits lotus style and allows the stress to pass through him

Oommmmmm
Oommmmmm
I hate man pages, Oommmmm
I hate perldoc, Ommmmm
but I'm glad perldocs exist, Ommmmmm
I exist to keep O,Rielly, Corolis, and Sam's in business, Ohmmmmmm

Seriously. I find that man pages and perldoc entries obtuse and difficult to grep. This is a personal choice and an expensive one. In the last year and a half I've spent close to $1000 on IT books and I've gone from knowing absolutely nothing about perl to being wonderfully bored at Tom Christiansen's advanced perl session at Perl Conf v4.

(Damiens OO session was still downright awe-inspiring. -Oommmmmmm.)

Anyhowser's. Whether it's here or on a mailing list, whenever anyone looks for more info I'll point them to the right book. Sometimes even to the chapter and page that I think provides the best clarification of the problem they are looking for. Maybe when I use a book index I'm just like my old man solving math problems on his sliderule when calculators were available, but lets face it perldocs were not written with publishing editor's reviewing the entries. While they may get the essential's across to the expirienced perl programmer they naturally lack in content for the inexpirienced.

I cringe whenever I see a post to an obvious newbie that chastises them with RTFM's and a perlsyn or perldoc reference. Just using perldoc for a fine grained search is obtuse enough, but even when one is successful the entries sometimes qualify for the Obfuscated Perl Contest.

Personaly I think in the Perl world RTFM should be changed to OTFM (Own the f'n manual).

Coreolyn changes into a flame retardant robe and takes his meditation out of the node.

Oommmmmm
Oommmmmm
I hate Andy Rooney
Oommmmmm.

coreolyn Duct tape devotee.

Replies are listed 'Best First'.
(zdog) RE: Perldoc's vrs. Books, and RTFM's
by zdog (Priest) on Aug 12, 2000 at 19:58 UTC
    I tend to disagree. I find that books are a great place to learn any programming language from, but I also find that perldoc is a great reference as well. Sometimes, however, it is a little difficult to find the information you need, so I don't mind when I have a question and another monk points me to a perldoc . However, I do think that you can't learn Perl from perldocs and that having some kind of book or tutorial is better.

    Update: I came up with an idea that puts what I am trying to say in a nutshell: You buy the books to learn how to read the docs.

    Zenon Zabinski | zdog | zdog7@hotmail.com

[reply]
[d/l]
[select]
      Agreed.

      Furthermore, readmes, howtos, perldocs etc. have one really big advantage: have you ever tried to carry the equivalent of 1 GB in book form? Hell, the stuff that fits on the HD of my notebook would fill several suitcases! Believe it or not, whenever possible, I'm reading on my notebook's display instead of paper.

      Just my 2 cents :-) ...

      Andreas

[reply]
      Absolutely!

      As I said, I have a lot of animals running around my house. It is far easier for me to get an overview from a book. But once I have done that, learned the concepts, seen examples, etc, the final arbitrator is always going to be what is locally installed.

      Why?

      Well suppose that, like me, you run Perl 5.005_03. Suppose you buy Camel 3 so you can learn to use it. Well then here is a list of features that you will be led to believe that you can use which, in fact, you can't!

      Like you I buy books and learn from them. However when I need the answer to be right, I won't rely on books.

[reply]
RE: Perldoc's vrs. Books, and RTFM's
by BlaisePascal (Monk) on Aug 12, 2000 at 19:10 UTC
    I find several advantages to well-written books than to online docs:

    You can annotate books. It's a lot harder with on-line docs.

    It's easier (for me, at least) to see the surrounding context when I'm looking at a bound book, as opposed to online docs. The surrounding context can be essential for true understanding

    Your desktop usually has more space than your screen. Having several books open on your desktop for quick reference is easier than having several online docs open on your screen at one time.

    etc.

[reply]
RE: Perldoc's vrs. Books, and RTFM's
by tilly (Archbishop) on Aug 12, 2000 at 20:38 UTC
    Well you know my opinion.

    I like using books as well. I have a lot of animals wandering around my house. When I need to learn I prefer something I can read offline.

    But if your ultimate authority is anything other than that which you have locally installed then it will be somewhat wrong and you will never know when. For instance if you want to learn how to use tie effectively, the documentation in this site will lie to you about the limitations of what you have installed. This site's documentation does not include the wonderful qr// operator. You might or might not have the our keyword locally available. No book will tell you whether you do - but your locally installed documentation does. And, of course, the odds are very good that the exact list of diagnostic messages that you might get are available nowhere else than with what is locally installed.

    Aw heck, I don't have time to rant properly. Besides which I already did: RE (5): Should I use $ and $# ?.

    BTW for what it is worth I have been using Perl for about 2.5 years and programming for not much more than that. Of course I have a strong technical background, I have done my level best to learn, and I have had the incredible fortune to work very closely with someone whose first real job was kernel hacker in a tiger team at DEC under "Maddog" during the height of the VMS-Unix wars. You can decide for yourself how well I have learned Perl.

[reply]
RE: Perldoc's vrs. Books, and RTFM's
by ZZamboni (Curate) on Aug 12, 2000 at 17:48 UTC
    I think it's a matter of using the right tool for the right job.

    I own (or have access to) every single Perl book published by O'Reilly, and several others. At any given time I usually have several of them scattered on my desk. So yes, I like books. For language-related reference, nothing beats O'Reilly's pocket reference, or the Camel for more detailed stuff.

    But sometimes I find it easier to find things in perldocs. For one, module documentation, which is not in any book (other than the "Perl resource kit" from O'Reilly, but that is terribly outdated). But let's say I don't quiite remember the syntax for some function, sometimes nothing beats "perldoc -f function". Or for special variables, "perldoc perlvar" and grepping for the appropriate keywords.

    So I guess I agree with your meditation. I like books, but I'm glad perldoc exists.

    --ZZamboni

    (Oh, and yes, Conway's advanced OO session at TPC4.0 was truly awe-inspiring)

[reply]
(Guildenstern) RE: Perldoc's vrs. Books, and RTFM's
by Guildenstern (Deacon) on Aug 12, 2000 at 20:34 UTC
    Amen! I tend to be more of a hands on person, so when I can actually pick up a book and thumb through it, it feels more natural to me. As someone who has been accused several times of not knowing how to RTFM, I must say that the online docs are often quite helpful, but that's just not my style of learning. I will give credit to the ActiveState distribution - all of the man pages are available as HTML. It's so nice to be able to just click on a "see also" without having to pull that page up as well. Also, given the sorry state of the laptop I use at work, it's much easier to have multiple books open than windows.
[reply]

Back to Meditations