develooper Front page | perl.perl5.porters | Postings from November 2003

Re: Poor State of the Man Pages

Thread Previous | Thread Next
From:
Rafael Garcia-Suarez
Date:
November 27, 2003 05:38
Subject:
Re: Poor State of the Man Pages
Message ID:
20031127143502.6f531915.rgarcia@hexaflux.com
Shlomi Fish wrote:
> 
> At one point, I suggested the reader that he can now go over the man pages
> and should. However, my friend complained that the man pages were hard to
> understand, and I can relate to it, as they are certainly not intended for
> people with very little background in UNIX.

I'd like to point out that the perl manpages are intented to be exactly
that : manpages -- reference documentation, complete but yet concise.
To draw a comparison, I doubt anyone can learn the basics of using a
Unix shell by reading in a row and from cover to cover sh(1), ls(1),
rm(1) and the like.

> I recommended him to buy the Camel Book, which is a good read even for
> people who are very good programmers. Still, it was a bit pricy for him
> (220 NIS or $40). At the moment he is using a pirated version he found on
> the Net somewhere. (of the second edition).

"Learning Perl" would be a more obvious choice IMHO. (BTW may I point
out that O'Reilly has a lower-price program for user groups ? and that
books can be shared ?)

> For a long time, I complained that the Perl man pages were probably
> intended for either experienced Perl 4 programmers or for seasoned UNIX
> shell/sed/awk/whatever hackers. But naturally, reality wanted otherwise
> and Perl is now being learned by people with very little experience of
> either.

Agreed.

> Those people could perhaps get started by reading Simon Cozens' "Beginning
> Perl" book or whatever, but still need a good reference. This is either
> "Programming Perl" or the man pages.

Ultimately, the man pages *are* the reference, and vice versa. I'd be
happy to apply any improvement to the man pages,  But I still think
that, as a reference documentation, they need to suppose a minimal level
of knowledge about programming and systems. For example, I don't see the
point of explaining what perl's exec() does without supposing that the
programmer can refer to the exec(3) manpage and understand it. The FAQs
and the *tut* pods have a little different purpose (and it should be
noted that the FAQs are maintained separately.)

Thread Previous | Thread Next


nntp.perl.org: Perl Programming lists via nntp and http.
Comments to Ask Bjørn Hansen at ask@perl.org | Group listing | About