Tried Ruby (or, "what Python *really* needs" or "perldoc!")

[john_sips_tea at yahoo.com]

Jason Earl wrote:
> "msoulier" <msoulier at gmail.com> writes:
>
> >> I have found the Python sidebar VERY helpful:
> >
> > Personally, I can't use local docs on my desktop as they may not be
> > the same version of the docs for the Python distro running on the
> > server that I'm deploying on. I usually go to python.org and use the
> > wayback machine to look at the old docs for the release that I'm on.
>
> Why don't you instead install the info version of the Python
> documentation on your server.  Then you can do "info Python2.3-lib"
> and have at it.  If you are hacking in emacs then this is about as
> slick a documentation system as you could ask for, but even if you use
> some other editor info is a much better documentation tool than man.

You know, I'm pretty used to reading man pages. There's only a
few simple keystrokes I need to remember, and the only time I
ever touch "info" is when a very short man page tells me that the
real docs are in info and I need to look there. At that point, I have
to relearn how to use that info command. Info is complicated. It's
got some concept of nodes being hierarcical, but also they seem
to have some order to them (a la next and previous) as well. No
idea what the connection between those is. Also it's got "cross-
references" as well as menus -- dunno if they're different or not.
Bah. Why not just use html and browse it with lynx/links/links2/elinks?

I can't understand why we need two separate and distinct doc
formats: man and info. My take: write your docs in some markup
that can produce both man output and html. Done and done.
Seems like two good candidates for that are epytext and
reStructuredText ("reST").

> > But, if Python would match Perl for docs available on the
> > command-line, then I'd have it all at my fingertips. I simply don't
> > understand why this is not being done. When I'm coding in C, I use
> > the manpages on the remote host so that I know the docs are correct
> > for my target. Why can't I do that in Python? It's yet another thing
> > that my Perl-using coworkers point out as a Python weakness.
>
> Python does match (and exceed) Perl for docs available on the command
> line.  Once you get used to using the excellent info-based Python
> documentation using man is downright primitive.
>
> Jason

I think that may be wishful thinking. When I use the pydoc command,
I mostly get *very* short API docs with *no* example code or tutorial
notes at all.

Contrast that with perldoc which is categorized and complete docs
for the entire language plus tutorials, faqs, ports info, ... I mean,
have a look over at http://perldoc.perl.org/perl.html -- everything
there is at your fingertips from the terminal! And it's written by
folks
like Larry, Dominus, Randal Schwartz, Tom Christiansen, et al. I've
never come across a FLOSS software project with docs as good as
Perl's.

Now, the one big thing we have going for us is that since Python
is a simpler language, so it needs few docs overall anyway. :)

---John
http://www.simisen.com/jmg/cpd/