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

Re: Poor State of the Man Pages

H.Merijn Brand
November 29, 2003 08:33
Re: Poor State of the Man Pages
Message ID:
On Fri 28 Nov 2003 12:01, Shlomi Fish <> wrote:
> > Haha, it makes for a good laughter that particularly the GNU folks would
> > complain about the Perl documentation. I am sure that I had never learnt
> > Perl if it had been documented the way GNU projects are.
> >
> It depends on the GNU project. GNU awk has an excellent documentation and
> I learned Awk from there (albeit after I knew Perl). GNU make also has a
> good documentation, and I think I learned how to write makefiles from
> there. Still, I found out that it was hard to find out what I was looking
> for there, after I became experienced.

If you regard 'info' files as documentation, I fully disagree. One has to be
an emacs user to be able to read that, and even then, finding the info you
need takes too much time. man or pod, all info is ready for immediate
trashcanning and can IMHO *never* be marked good documentation. If you ask me,
it cannot be marked documentation at all.

I realy like perl's pod, and not only because it auto-translates to plain old
manpages, but also because it rather well translates to HTML, which is easy to
browse with Opera, and then is rather good to print.

> Some GNU packages are documented just enough to explain the basic flags
> and operation modes, and nothing too much besides. For example, the docs
> of gcc do not teach you C, or the docs of wget do not teach you WWW
> basics. It vastly depends on how original the particular application is.
> I found the GNU documentation as a whole to be a good, clear, reference,
> which I'm not sure can be said on the Perl pod files.

H.Merijn Brand        Amsterdam Perl Mongers (
using perl-5.6.1, 5.8.0, & 5.9.x, and 806 on  HP-UX 10.20 & 11.00, 11i,
   AIX 4.3, SuSE 8.2, and Win2k. 
send smoke reports to:, QA: Perl Programming lists via nntp and http.
Comments to Ask Bjørn Hansen at | Group listing | About