Mailing List Archive

>What's all this about no Python manpages?

$ man python
No manual entry for python
[Exit 1]

$ locate python.1
[Exit 1]

That there appears to be running a 1.5.1 version on a Redhat
Linux system. I haven't tried a from-scratch build. I'm
happy to blame RH. Their doc situation is nasty.

--tom

On Thu, Aug 19, 1999 at 02:43:26PM -0600, Tom Christiansen wrote:
> >What's all this about no Python manpages?
>
> $ man python
> No manual entry for python
> [Exit 1]
>
> $ locate python.1
> [Exit 1]
>
> That there appears to be running a 1.5.1 version on a Redhat
> Linux system. I haven't tried a from-scratch build. I'm
> happy to blame RH. Their doc situation is nasty.

Ahhhhhhhhhh, that seems to be the problem. I just tried it on a recently
built (RedHat)SparcLinux box and got the same thing.

Having followed the manpage discussion a bit, I see two arguments that might
have gotten confused by this new info:

1) There should at least be a python(1) manpage that tells you command
line args, some basic information about the interpreter, etc.

2) There should be manpages documenting all aspects of the language.

If your problem was mostly with 1) then I concur, and so would most Unix
types, I think. The rest of this debate seems centered around issue 2), and
I'm not sure that was your main point. I agree that 1) should be the
minimum, but I would tend to look for web-based cross-referenced
hypertextified documentation for more detailed information. Though I've
definitely found "man perlfunc" to be extremely useful when I want to get at
something quick, so I agree that Python manpages would be a nice addition.

- John Landahl / jpl@digex.net

>If your problem was mostly with 1) then I concur, and so would most Unix
>types, I think. The rest of this debate seems centered around issue 2), and
>I'm not sure that was your main point. I agree that 1) should be the
>minimum, but I would tend to look for web-based cross-referenced
>hypertextified documentation for more detailed information. Though I've
>definitely found "man perlfunc" to be extremely useful when I want to get at
>something quick, so I agree that Python manpages would be a nice addition.

% (echo 'import os' ; echo 'print os.execv.__doc__' ) | python
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. :-)

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. :-)

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

--tom

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

[snip]


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. |

John Landahl wrote:

> What's all this about no Python manpages?
>
> $ man python
> Reformatting page. Wait... done
>
> Misc. Reference Manual Pages PYTHON(10 April, 1998)

It's there, but I think "perldoc perl" still has more
to say. Why not offer all possible resources?
Even tcl has more...

-Per.
--
Per Kistler kistler@fnmail.com / kistler@gmx.net
------------------------------------------------------------

Tom Christiansen wrote:
>
> That there appears to be running a 1.5.1 version on a Redhat
> Linux system. I haven't tried a from-scratch build. I'm
> happy to blame RH. Their doc situation is nasty.

Would that be the same RH5.2 that caused me a day's frustration because
their
Perl is so broken it can't handle PerlTk? You want to be careful
building Python 1.5.2, also, as a little misstep will break RH's
'glint', 'linuxconfig' and other Python based oddities.

--
Bear Technology Making Montana safe for Grizzlies

http://people.montana.com/~bowman/

bowman> You want to be careful building Python 1.5.2, also, as a little
bowman> misstep will break RH's 'glint', 'linuxconfig' and other Python
bowman> based oddities.

There are two or three scripts that need to have their function def's fixed
to not have default args after non-default args. If anyone needs them I can
build a context diff. Just let me know.

Skip Montanaro | http://www.mojam.com/
skip@mojam.com | http://www.musi-cal.com/~skip/
847-971-7098

Skip Montanaro wrote:

> bowman> You want to be careful building Python 1.5.2, also, as a little
> bowman> misstep will break RH's 'glint', 'linuxconfig' and other Python
> bowman> based oddities.
>
> There are two or three scripts that need to have their function def's fixed
> to not have default args after non-default args. If anyone needs them I can
> build a context diff. Just let me know.
>

Those of us on the Python4Linux issues are ironing these issues out.
Hopefully,
we will submit an SRPM that the major distributions will accept in order to
upgrade their next supported releases to 1.5.2 (Debian seems to have 1.5.2
available in their unstable release already).

Those wanting to know more can subscribe or see the archives:

http://starship.python.net/mailman/listinfo/python4linux

Look at my posting titled "Evaluation packages now online", which will lead
you to packages for Redhat that will work for Python 1.5.2 (well, not glint
actually)

Chad Netzer
chad@vision.arc.nasa.gov