metadocumentation (keyword help)

[Jacek Generowicz]

David,

Thank you for your refreshingly constructive followup.

davidb at mcs.st-and.ac.uk (David Boddie) writes:

> Jacek Generowicz <jacek.generowicz at cern.ch> wrote in message news:<tyfbrpggc6u.fsf at pcepsft001.cern.ch>...
> > [...] 
>
> revealed that the basic information about the PYTHONDOCS environment
> variable can be found at the foot of the following page:
> 
>     http://www.python.org/dev/doc/devel/lib/module-pydoc.html

This strikes me as not very helpful to someone looking to solve the
problem of _keyword_ documentation not working. Remember, we're
talking about poor lost newbies.

> > If these instructions are, as it seems, absent, then I would
> > appreciate advice on what I can do to make them appear in the
> > appropriate place, and what the appropriate place might be.
> 
> They could always be written up in the PythonInfo Wiki, then at
> least you have a python.org URL to give your students.

I hadn't thought of that opiton. Thanks.

> > I recognize my impatience with poor documentation as a pathological
> > flaw in my characer, which is why I am asking for help in
> > finding/creating this documentation here.
> 
> You're going to have to be quite patient, though. If the documents
> you want aren't obvious then it's probably up to you to write them. :-/

That is exactly what I was implying with my use of the word "creating".

> David
> 
> P.S. You'll note that I haven't come up with my own recipe so far.
> For what it's worth, a document describing how to obtain help on
> keywords might start in the following way:
> 
> Configuring Python to supply help on keywords
> =============================================
> 
> Introduction
> ------------
> Recent versions of Python include the ability to display help on
> existing objects, or to search for information on installed modules,
> from within the interactive environment. However, it is also possible
> to use the help system to display information on the keywords used
> in the language itself, such as "if" and "for. This feature appears
> to be less well-known, possibly because users seek basic language
> information elsewhere, but maybe also because it is not always
> enabled by default.
> 
> Requirements
> ------------
> In order to seek help on keywords from within the interactive
> environment, two things need to be done before Python is invoked:
> 
>  * The HTML documentation needs to be downloaded and installed in an
>    accessible location; this will depend on the operating system in
>    use.
>  
>  * The PYTHONDOCS environment variable will need to be set to the
>    path of the installed HTML files.
> 
> Setting it up
> -------------
> First of all, check whether the HTML documentation has already been
> installed for the version of Python you are using. This could save
> you the effort of downloading and installing it manually.
> 
> If the documentation is required then go to::
> 
>   http://www.python.org/download/
>
> and find the appropriate documentation. Download it and install it
> in a place where it can be read by those who will be using it.

How about 

  If the documentation is required then go to:
  
    http://www.python.org/doc/<python-version>/download.html
 
  and download the HTML documention and install it in a place where it
  can be read by those who will be using it.

?

> Checking it works
> -----------------
> Using the appropriate method provided by your operating system, set
> the PYTHONDOCS environment variable to the directory which contains
> the main index file for the documentation.
> 
> For example, you may have installed the documentation in
> /usr/share/doc/python so that the directory layout look like::
> 
>   /usr/share/doc/python
>   |- Misc
>   |- README
>   \- html
>      |- about.html
>      |- acks.html
>      |- api/
>      |- dist/
>      |- doc/
>      ...
> 
> and so on. Therefore, PYTHONDOCS should be set to /usr/share/doc/python/html
> since this contains the information required. On Linux systems, using the
> bash shell, you might type::
> 
>   export PYTHONDOCS=/usr/local/share/python/html python
> 
> to start the interpreter. Within the Python environment, typing::
> 
>   help("if")
> 
> should now cause something like the following to be displayed::
> 
>   7.1 The if statement
>   
>     The if statement is used for conditional execution:
>     
>           if_stmt   ::=    "if" expression[1] ":" suite[2]
>                            ( "elif" expression[3] ":" suite[4] )*
>                            ["else" ":" suite[5]]
>   
>     Download entire grammar as text.[6]
>   
>     It selects exactly one of the suites by evaluating the expressions one
>     by one until one is found to be true (see section 5.10[7] for the
>     definition of true and false); then that suite is executed (and no other
>     part of the if statement is executed or evaluated). If all expressions
>     are false, the suite of the else clause, if present, is executed.
> 
> Enabling this by default
> ------------------------
> Any ideas?

I guess this would require the HTML documentation to be bundled in
with the Python distribution tarball, and I can imagine that being an
unpopular suggestion.


Now, currently one gets the following from Python's built-in help:

  >>> help('if')
  
  Sorry, topic and keyword documentation is not available because the Python
  HTML documentation files could not be found.  If you have installed them,
  please set the environment variable PYTHONDOCS to indicate their location.

How about augemnting this with something like:

  The HTML documentation files can be obtained from 

    http://www.python.org/doc/<python-version>/download.html

?


And then there's the wart surrounding the following:

  lambda, and, not, or  

I always get 

  could not read docs from $PYTHONDOCS//ref/lambda.html

Note, I even get 'lambda.html' in the message when asking for help on
the other three. Any ideas what's going on there ?


Furthermore, is there anyway of getting help of keywords via pydoc ?