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

[Nick Craig-Wood]

john_sips_tea at yahoo.com <john_sips_tea at yahoo.com> wrote:
>  IMO, Perl has docs nailed. I learned Perl before coming
>  to Python, and I can tell you that their docs kick butt.
>  I believe the reason why is (besides Larry's excellent
>  and entertaining writing) because of perldoc. Here's how
>  it works: they write special doc directives into their .pl
>  files that the interpreter ignores, but that the perldoc
>  command processes into a manpage for you. This is a *bit*
>  like what pydoc does, only pydoc just regurgitates docstrings,
>  while perldoc formats special directives into headings, code
>  listings, bulleted lists, etc.

As another perl refugee I agree with you 100% here.

"perldoc perltoc" then "perldoc xxxx" will find you anything in perl.

Its frustrating that pydoc is only half (or less) of the docs.

However having bedded into python for a few years, I now just reach
for my web browser for the global module index instead of pydoc.  Its
not as good as perldoc as it doesn't cover all the modules I've got
installed, but its very good documentation.  Some modules have good
pydoc-umentation but not all of them.  Code examples tend to be
missing.

I think a major problem with our way of thinking about
perldoc/pydoc/man pages is that it is a) unix centric, and b) possibly
a bit old fashioned!  a) and b) apply to perl certainly, but I don't
think they apply to python in the same way.

I'd love to have a unified documentation system where *all* the
documentation for *all* installed modules was available to pydoc *and*
the web browser and *all* this documentation was in .py files.

(Putting the code together with the documentation is essential in my
opinion and experience - if you seperate the two then the documention
will lag the code.)

PS I've used reST and perldoc.  reST is easier to use for the easy
things, but gets complicated for the hard things.

-- 
Nick Craig-Wood <nick at craig-wood.com> -- http://www.craig-wood.com/nick