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

Re: Poor State of the Man Pages

Shlomi Fish
November 28, 2003 03:01
Re: Poor State of the Man Pages
Message ID:
On Fri, 28 Nov 2003, Tassilo von Parseval wrote:

> On Thu, Nov 27, 2003 at 10:41:32PM +0200 Shlomi Fish wrote:
> > Check:
> >
> >
> >
> > And Perl is mentioned there speicifically.
> 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.

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.

> The chaps from the Free Software Foundation live in a sort of parallel
> universe, as it sometimes seems. In the mentioned article they complain
> that O'Reilly doesn't let users copy and modify the source of their
> books. Of course, they are neglecting the rather obvious fact that it'd
> be pretty hard to earn any money when allowing that.

You might as well complain that Microsoft or a different vendor of
proprietary software does not let users copy and modify the source of
their software. And neglect the rather obvious fact that it'd be pretty
hard to earn any money when allowing that. ;-)

Seriously, some books distributed online under an open content license,
actually sold pretty well in paperware. Not all, but then again, not every
book that wasn't placed online was successful, either.

I'm not someone who thinks that every book should be distributed online
(even though everyting I created and transcribed to a digital format is,
and I hope I will continue this trend). But I agree that releasing a piece
of software, without supplying a good and thorough introduction and
reference documentation, is very bad for the software. Simply put, users
will shy away from it, become frustrated using it and use something else
instead. Many computer users nowadays expect (and rightfully so) that an
open source software (that is free as in beer), will be also adequately
documented without having to pay for paperware. If someone likes books,
then he may be willing to pay or borrow such a book, but we must also
accomodate for people who like learning from Internet resources. (like me)

My point is that the perl*.pod pages should be suitable for a large part
of our demographic. Telling someone to buy "Programming Perl" is
equivalent to telling him to "learn Python instead because it has good
documentation online". (you might not like it, but it's life). It is my
intention to make perl*.pod suitable for people like my friend. And my
friend, mind you is an Electrical Engineering graduate from the Technion,
so he is well above average intelligence. Again, it may be a good idea to
fork the man pages, and turn them into something more organized that will
cater to a more average demographic. We'll see.

Of course, all of this would have been much easier if "Programming Perl"
was available online for free. There are already some replacements for
"Learning Perl" (like Simon Cozens' book) online. This all reminds me of
the "triple development" symptom of open-source:

1. Someone decides to write KDE based on Qt, where Qt is not free.
2. Someone decides to write GNOME based on the free Gtk, to pose an
alternative to KDE.
3. Someone decides to write a free Qt replacement (Harmony).

So, in order to provide a good reference to the core language of Perl, we
have to duplicate the efforts of other people.


	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