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

Re: Poor State of the Man Pages

Shlomi Fish
November 27, 2003 06:38
Re: Poor State of the Man Pages
Message ID:
On Thu, 27 Nov 2003, Rafael Garcia-Suarez wrote:

> 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 ?)

Actually, let's assume for the moment that my friend can learn the
_basics_ of Perl from "Perl for Perl Newbies" or from "Beginning Perl"
which are both available online. In any case, he also needs a good
reference to consult with to cover the _whole_ of Perl.

"Programming Perl" is such a good reference. However, it is not available
online for him to make use of. I can lend him my copy, but so far he
wanted to have a copy all of his own. And he found the man pages very hard
to understand.

There's a difference between keeping things "expert" and not aiming for
the general populace. For example saying:

	And you can do the C-shell like "fooish".

And that's it, is bad, because not everyone here knows C-shell or ever has
to work with it. As for the exec example. One can say:

	exec() executes a different program instead of the current perl
	program. That is, it will run instead of the script and execution
	will never return to the script. (unless in case of error, in
	which it is usually recommended to exit immediately).

That's it! Brief, to the point, and portable for all people. UNIX 101 for

> > 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.)

I suggest I start by asking people who are new to Perl what they don't
understand in the man pages, and so collect user stories. (I'll ask my
friend to go over the pods and comment as well). Once we have enough, we
can see where should we improve things.

As a general rule, one can expect a beginning Perl programmer to refer to
the perl*.pod documents looking for a nice information or a trick. I feel
that they can be made suitable for almost everybody, without sacrificing
their use for expert hackers.


	Shlomi Fish

Shlomi Fish
Home Page:

An apple a day will keep a doctor away. Two apples a day will keep two
doctors away.

	Falk Fish Perl Programming lists via nntp and http.
Comments to Ask Bjørn Hansen at | Group listing | About