No man pages? (was Re: More random python observations from a perl programmer)

[Robert Kern]

On Thu, 19 Aug 1999 15:55:47 -0600, Tom Christiansen
<tchrist at jhereg.perl.com> wrote:

[snip]

>% (echo 'import os' ; echo 'print os.execv.__doc__' ) | python 

You can simplify that to 
% python -c 'import os; print os.execv.__doc__'
:-)

>Execute an executable path with arguments, replacing current process.
>
>        path: path of executable file
>        args: tuple or list of strings
>
>Well, that's better than nothing.
>
>% (echo 'import os' ; echo 'print os.__doc__' ) | python 
>None
>
>But that isn't. :-)

True.  Missing doc-strings has been the perennial biggest problem with
Python's documentation.

>I'd guess for a module, you should traverse its members and
>print docs for all that have them.
>
>I'm still getting ideas for autogenerating manpages. :-)

We've probably thought of them, too (well, the autogeneration part at
least).  The biggest problem with using them on third-party modules is
that there is no consistent standard for them like pod.  We have
Guido's recommendations from his style guide, and we have things like
Structured Text, but we also have have a zillion other styles for
docstrings.  We could probably enforce a standard for the standard
library, though.  Use Deja.com to read a thread named "Pod" we had
here back in October and November of 1998 where we talked about most
of these things.  But ...

>But I haven't looked at the HTML or latex docs yet.  Probably
>won't till after the conference or so.

... more of the information you would want in a manpage is probably in
the latex sources (and, by extension, HTML) than in the docstrings.

Things will get even easier when the conversion to XML or SGML is made
(RSN).

>--tom

Robert Kern           |
----------------------|"In the fields of Hell where the grass grows high
This space            | Are the graves of dreams allowed to die."
intentionally         |           - Richard Harter
left blank.           |