From: Daniel Carrera <dcarrera@...>
Date: 2003-12-17T03:55:08+09:00
Subject: Re: Newbie questions

> OK, I've heard this discussed before, but as I'm not a Perler, I don't
> know what the big deal is with perldoc.
> 
> What is it, what can it do, how is it used, why is it better than ri,
> etc.?

Using perldoc feels much the same as using man.  In fact, you can use 
perldoc to make man pages.

What makes perldoc betters is not perldoc but the documentation.  Perl 
has an exceptional ammount of very thorough documentation in a very 
accessible (ie man-page) manner.  When you install a module you have a 
reasonable expectation of it automatically installing a perldoc page.

The writing style of ri is different from that of man pages.  It is more 
of a list of methods than an actual explanation of how to use them.

Try this:

man perl  -> You get a list of the standard pages that come with Perl.


man perlre
man perlvar
man perlreftut

...

Try these.  You'll see that Perl comes with a garganuous ammount of 
man-page-style documentation.

Compare that with :

ri Class


Notice that ri does not produce a scrollable output (yes, you can pipe 
ri to less, I know), and the descriptions are fairly limited.

Also, ri seems to be limited to explaining what a class does.  Perldoc 
is limited only by the number of characters on your keyboard.  With 
perldoc you get a lot of tutorials and descriptions of how things work.

It's more of an issue of the ammount and style of documentation than of 
the actual technology.  Documentation one of the things I like most 
about Perl and like least about Ruby.

I do think that ri should be scrollable though.

Cheers,
-- 
Daniel Carrera | "Software is like sex.  It's better when it's free".
PhD student.   | 
Math Dept. UMD |     -- Linus Torvalds