[Python-Dev] Online help PEP

[Paul Prescod]

Guido van Rossum wrote:
> 
> Having the repr() overloading invoke the pager is dangerous.  The beta
> version of the license command did this, and it caused some strange
> side effects, e.g. vars(__builtins__) would start reading from input
> and confuse the users.  The new version's repr() returns the desired
> string if it's less than a page, and 'Type license() to see the full
> license text' if the pager would need to be invoked.

I'll add this to the PEP.

> The implied import is a major liability.  If you can do this without
> importing (e.g. by source code inspection), fine.  Otherwise, you
> might issue some kind of message like "you must first import XXX.YYY".

Okay, I'll add to the PEP that an open issue is what strategy to use,
but that we want to avoid implicit import.

> The hurt is code bloat in the interpreter and creeping featurism.  If
> you need command line access to the docs (which may be a reasonable
> thing to ask for, although to me it sounds backwards :-), it's better
> to provide a separate command, e.g. pythondoc.  (Analog to perldoc.)

Okay, I'll add a pythondoc proposal to the PEP.

> Yes.  Please add that option to the PEP.

Done.

> > > What does "demand-loaded" mean in a Python context?
> >
> > When you "touch" the help object, it loads the onlinehelp module which
> > has the real implementation. The thing in __builtins__ is just a
> > lightweight proxy.
> 
> Please suggest an implementation.

In the PEP.

> Glad You'Re So Agreeable. :)

What happened to your capitalization? elisp gone awry? 

> ...
> To Tell You The Truth, I'M Not Holding My Breath Either. :-)  So your
> code should just dump the doc string on stdout without interpreting it
> in any way (except for paging).

I'll do this for the first version.

> It's buggier than just that.  The output of the pager prints an extra
> "| " at the start of each page except for the first, and the first
> page is a line longer than subsequent pages.

For some reason that I now I forget, that code is pretty hairy.

> BTW, another bug: try help(cgi).  It's nice that it gives the default
> value for arguments, but the defaults for FieldStorage.__init__ happen
> to include os.environ.  Its entire value is dumped -- which causes the
> pager to be off (it wraps over about 20 lines for me).  I think you
> may have to truncate long values a bit, e.g. by using the repr module.

Okay. There are a lot of little things we need to figure out. Such as
whether we should print out docstrings for private methods etc.

>...
> I don't know specific tools, but any serious docstring processing tool
> ends up parsing the source code for this very reason, so there's
> probably plenty of prior art.

Okay, I'll look into it.

 Paul