[Python-Dev] Online help PEP

[Paul Prescod]

Guido van Rossum wrote:
> 
>...
> >         help( "string" ) -- built-in topic or global
> 
> Why does a global require string quotes?

It doesn't, but if you happen to say 

help( "dir" ) instead of help( dir ), I think it should do the right
thing.

> I'm missing
> 
>           help() -- table of contents
> 
> I'm not sure if the table of contents should be printed by the repr
> output.

I don't see any benefit in having different behaviors for help and
help().

> >     If you ask for a global, it can be a fully-qualfied name such as
> >     help("xml.dom").
> 
> Why are the string quotes needed?  When are they useful?

When you haven't imported the thing you are asking about. Or when the
string comes from another UI like an editor window, command line or web
form.

> >     You can also use the facility from a command-line
> >
> >     python --help if
> 
> Is this really useful?  Sounds like Perlism to me.

I'm just trying to make it easy to quickly get answers to Python
questions. I could totally see someone writing code in VIM switching to
a bash window to type:

python --help os.path.dirname

That's alot easier than:

$ python
Python 2.0 (#8, Oct 16 2000, 17:27:58) [MSC 32 bit (Intel)] on win32
Type "copyright", "credits" or "license" for more information.
>>> import os
>>> help(os.path.dirname)

And what does it hurt?

> >     In either situation, the output does paging similar to the "more"
> >     command.
> 
> Agreed.  But how to implement paging in a platform-dependent manner?
> On Unix, os.system("more") or "$PAGER" is likely to work.  On Windows,
> I suppose we could use its MORE, although that's pretty braindead.  On
> the Mac?  Also, inside IDLE or Pythonwin, invoking the system pager
> isn't a good idea.

The current implementation does paging internally. You could override it
to use the system pager (or no pager).

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

> >     It should also be possible to override the help display function by
> >     assigning to onlinehelp.displayhelp(object_or_string).
> 
> Good idea.  Pythonwin and IDLE could use this.  But I'd like it to
> work at least "okay" if they don't.

Agreed. 

> >     The module should be able to extract module information from either
> >     the HTML or LaTeX versions of the Python documentation. Links should
> >     be accommodated in a "lynx-like" manner.
> 
> I think this is beyond the scope.  

Well, we have to do one of:

 * re-write a subset of the docs in a form that can be accessed from the
command line
 * access the existing docs in a form that's installed
 * auto-convert the docs into a form that's compatible

I've already implemented HTML parsing and LaTeX parsing is actually not
that far off. I just need impetus to finish a LaTeX-parsing project I
started on my last vacation.

The reason that LaTeX is interesting is because it would be nice to be
able to move documentation from existing LaTeX files into docstrings.

> The LaTeX isn't installed anywhere
> (and processing would be too much work).  
> The HTML is installed only
> on Windows, where there already is a way to get it to pop up in your
> browser (actually two: it's in the Start menu, and also in IDLE's Help
> menu).

If the documentation becomes an integral part of the Python code, then
it will be installed. It's ridiculous that it isn't already.
ActivePython does install the docs on all platforms.

> A standard syntax for docstrings is under development, PEP 216.  I
> don't agree with the proposal there, but in any case the help PEP
> should not attempt to legalize a different format than PEP 216.

I won't hold my breath for a standard Python docstring format. I've gone
out of my way to make the code format independent..

> Neat.  I noticed that in a 24-line screen, the pagesize must be set to
> 21 to avoid stuff scrolling off the screen.  Maybe there's an off-by-3
> error somewhere?

Yes.

> I also noticed that it always prints '1' when invoked as a function.
> The new license pager in site.py avoids this problem.

Okay.

> help("operators") and several others raise an
> AttributeError('handledocrl').

Fixed.

> The "lynx-line links" don't work.

I don't think that's implemented yet.

> I think it's naive to expect this help facility to replace browsing
> the website or the full documentation package.  There should be one
> entry that says to point your browser there (giving the local
> filesystem URL if available), and that's it.  The rest of the online
> help facility should be concerned with exposing doc strings.

I don't want to replace the documentation. But there is no reason we
should set out to make it incomplete. If its integrated with the HTML
then people can choose whatever access mechanism is easiest for them
right now

I'm trying hard not to be "naive". Realistically, nobody is going to
write a million docstrings between now and Python 2.1. It is much more
feasible to leverage the existing documentation that Fred and others
have spent months on.

> > Security Issues
> > 
> >     This module will attempt to import modules with the same names as
> >     requested topics. Don't use the modules if you are not confident
> >     that everything in your pythonpath is from a trusted source.
> Yikes!  Another reason to avoid the "string" -> global variable
> option.

I don't think we should lose that option. People will want to look up
information from non-executable environments like command lines, GUIs
and web pages. Perhaps you can point me to techniques for extracting
information from Python modules and packages without executing them.

 Paul