Python to Perl Conversions

[Jeff Blaine]

>In comp.lang.python, 
>    jblaine at shell2.shore.net (Jeff Blaine) writes:
>:If you put me on any UNIX machine without man pages containing
>:descriptions and command-line usage of the tools there, I would
>:be royally pissed.
>
>Exactly.  And I thought my statements were rather subdued for
>being royally pissed. 

Heh.  Alright...it's just that you and *at least* myself are coming from
very different views and usage expectations on this.  Perl didn't always
have pod, and more to the point Perl did not have pod when I learned it.
Perl had a gigantic man page that was so cumbersome to use, I didn't.

I always used the HTML version that used to exist at ufl.edu and it didn't
bother me in the least.  As a matter of fact, I found it much more useful
than any existing Perl documentation.

Because of that, I've never expected language reference to be available
in man page form on any UNIX box, with the exception of C function
reference which has just been there from day one for me.  So, I honestly
never blinked an eye when Python's docs were in HTML format, especially
given its wide platform availability (specifically non-UNIX) from
early versions.  I installed the documentation tarball, pointed lynx and
GUI browsers at it and that was that.

Even *when* Perl got pod, I didn't use the man pages due to their flat
and linear nature.

I know what version of Python I am running, and I know where the docs
for that version are.  Using Python 1.5.x and expecting a book which
is several years old (and based on 1.4) to be your source of
day-to-day reference seems pretty silly if you ask me.

As a royally-pissed-if-expected-tool-man-pages-are-not-there kinda
person, it doesn't bother me at all if a 3rd party language gets installed
and does not have man pages for each function or functionality.  I
can certainly agree that SOME sort of man page for 'python.1' would
make some sense, and more than that would only make more people happy...

Now, having said ALL of that, recently Transarc/IBM decided to STOP
doing man pages for AFS.  Man pages that I knew existed and depended
on.  This removal of service is the kind of thing that can really piss
a person off, and that seems to be what you're feeling coming from your
expectations.  Tom Christiansen believes man pages should exist for
any runnable command on a UNIX box (and ideally more than just that)
(right?).  Tom Christiansen does not find any for Python.  Tom
Christiansen is pissed.

Anyway, I seem to be entirely unable to quickly and concisely make a
statement anymore :)  I guess I more or less agree with you, I just
don't feel as strongly about it as you do for many reasons which are
spelled out in both of our messages.

>:I don't know, your little jab there in an otherwise great reference
>:document posting seemed completely petty to me.  It makes me think
>:you stuck it in there as a little "See, I'm dissing them like I am
>:supposed to!" due to the fact that you posted the message to both
>:c.l.perl and c.l.python.
>
>Don't be silly.  That wasn't that at all.

OK, sorry.  I was really hoping that wasn't the case.

>That's why we have "pod" as base docs, which can convert into HTML,
>text, info, latex, frame, troff (manpages), etc.  It makes it easy to
>run grep or find programs on.  This is very important.  And each module
>automatically installs that module's manpage (and optionally html doc,
>but this is less popular amongst perl folks).  That gets it added to
>the apropos and whatis and man commands automatically.  This is about
>0.002% of what the MakeMaker thingie in Perl does, but it's the part
>that matters for docs.  I've surely heard Python folks drooling over it
>for a long time.

Indeed, something like pod would be great, and many Pythoners definitely
do agree.

And before someone suggests gendoc, I've tried to get 'gendoc' and whatever
it used to be called to simply install and function properly 3 separate
times now over the last 2 years and have given up after an hour of work
and editing source code each time.