Opinions on usefulness of Perldoc

[nysus]

I'm learning Perl on my own and I'd like someone to shed a little light on the usefulness of the Perl plain old documentation (POD). For example, I was recently trying to figure out the difference between the /s and /m modifiers for pattern matching. The pod says:

/s Treat string as single line
/m Treat string as multiple lines

Honestly, how useful is that? The pod is totally silent about how the ".", "$", "^", and newline characters get handled based upon these modifiers.

So I'd like to know: Where does everyone else turn when they need clarification on Perl syntax? Does anyone else who is not a Perl veteran really find the pod that useful?

2001-03-26 Edit by Corion : Moved from Seekers Of Perl Wisdom to Meditations

[busunsl]

Either your version of the docs is old or you have to read a bit more. The docs of perl 5.6.0 state the following:

m    Treat string as multiple lines.  
     That is, change "^" and
     "$" from matching the start or end of the string to
     matching the start or end of any line anywhere within
     the string.

s    Treat string as single line.  That is, change "." to
     match any character whatsoever, even a newline, which
     normally it would not match.

and the next paragraph explains it even further.

I had problems with perldoc too, when I started to learn perl.
For a beginner the best she/he can do is buy the camel book.

But for a quick lookup of syntax the best is perldoc!

[chipmunk]

This text is also present in the 5.005_03 documentation.

Even the documentation that came with perl5.004 includes those two paragraphs:

    m     Treat string as multiple lines.  That is, change "^"
          and "$" from matching at only the very start or end of
          the string to the start or end of any line anywhere
          within the string,

    s     Treat string as single line.  That is, change "." to
          match any character whatsoever, even a newline, which
          it normally would not match.

Although it lacks the followup explanation of the interactions between /s, /m, and $*.

The original poster must have a very old version of Perl. Complaining about a lack of documentation in such an old version of Perl is pointless. The problem was found and fixed years ago; the solution is to upgrade.

[mirod]

I must say that I rarely use perldoc for the core, except for the always useful perldoc -f func.

Instead I rely on books, especially the Camel 3.

I often use perldoc with modules though. As soon as you install a new module it's doc is accessible using perldoc module. That's very cool!

[scottstef]

In my mind, the perl docs are extremekly useful- after you learn how to use them. I am going thru this also, it is the same as when I first started learning unix. Yes the answer is in the man pages, but learning how to use them is almost as difficult as learning the language itself. I used to post to usenet and would ask people to include chapter and verse in all RTFM replies. It at least gave a target on where to look for an answer. I think the biggest problem/feature is as new people learning the language we don't know how to use them. Perhaps, someone should try to write a tutorial on using the perldocs :-) At this point, I use the O'reilly cd bookshelf as well as the super search here. The super search here will usually get me started on the right road to finding something similar I can use. If that doesn't work, check merlyn's site, he has written columns on almost everything I have been looking for so far! %^)

[andye]

nysus, perldoc is useful enough, but personally I couldn't do without the Camel Book. I also find the Perl CD Bookshelf (old version) exceptionally useful, because it has a combined HTML index of the Camel Book, Perl in a Nutshell (which you also get on paper) the Cookbook, Advanced Perl Programming and Learning Perl - and most things are covered in more than one of these books, so there's always a couple of *different* explanations immediately to hand. Highly recommended.

andy.

[alfie]

I started off with reading SAMS Teach yourself PERL in 21 days and have to say that it is good for getting into it. Especially the section about the regular expressions ins't that bad after all... After that I used the man-pages only. They are good if you are searching for the syntax of a function, or even for /s and /m - if you already know what they mean and to remind which one is which....

P.S.: /s is matching \n with ., /m is handling ^ and $ after and before each \n :-)
--
Alfie