[Python-Dev] Online help PEP

[Guido van Rossum]

I approve of the general idea.  Barry, please assign a PEP number.

> PEP: ???
> Title: Python Online Help
> Version: $Revision: 1.0 $
> Author: paul@prescod.net, paulp@activestate.com (Paul Prescod)
> Status: Draft
> Type: Standards Track
> Python-Version: 2.1
> Status: Incomplete
> 
> Abstract
> 
>     This PEP describes a command-line driven online help facility
>     for Python. The facility should be able to build on existing
>     documentation facilities such as the Python documentation 
>     and docstrings. It should also be extensible for new types and
>     modules.
> 
> Interactive use:
> 
>     Simply typing "help" describes the help function (through repr 
>     overloading).

Cute -- like license, copyright, credits I suppose.

>     "help" can also be used as a function:
> 
>     The function takes the following forms of input:
> 
>         help( "string" ) -- built-in topic or global

Why does a global require string quotes?

>         help( <ob> ) -- docstring from object or type
>         help( "doc:filename" ) -- filename from Python documentation

I'm missing

          help() -- table of contents

I'm not sure if the table of contents should be printed by the repr
output.

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

>     You can also use the facility from a command-line
> 
>     python --help if

Is this really useful?  Sounds like Perlism to me.

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

> Implementation
> 
>     The help function is implemented in an onlinehelp module which is
>     demand-loaded.

What does "demand-loaded" mean in a Python context?

>     There should be options for fetching help information from
>     environments other than the command line through the onlinehelp
>     module:
> 
>         onelinehelp.gethelp(object_or_string) -> string

Good idea.

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

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

>     Over time, it should also be able to recognize when docstrings are 
>     in "special" syntaxes like structured text, HTML and LaTeX and
>     decode them appropriately.

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.

>     A prototype implementation is available with the Python source 
>     distribution as nondist/sandbox/doctools/onlinehelp.py.

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?

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

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

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

> Built-in Topics
> 
>     help( "intro" )  - What is Python? Read this first!
>     help( "keywords" )  - What are the keywords?
>     help( "syntax" )  - What is the overall syntax?
>     help( "operators" )  - What operators are available?
>     help( "builtins" )  - What functions, types, etc. are built-in?
>     help( "modules" )  - What modules are in the standard library?
>     help( "copyright" )  - Who owns Python?
>     help( "moreinfo" )  - Where is there more information?
>     help( "changes" )  - What changed in Python 2.0?
>     help( "extensions" )  - What extensions are installed?
>     help( "faq" )  - What questions are frequently asked?
>     help( "ack" )  - Who has done work on Python lately?

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.

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

--Guido van Rossum (home page: http://www.python.org/~guido/)