metadocumentation (keyword help)

[David Boddie]

Jacek Generowicz <jacek.generowicz at cern.ch> wrote in message news:<tyffzepfofo.fsf at pcepsft001.cern.ch>...

> Thank you for your refreshingly constructive followup.

No problem.

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

Well, it addresses part of the problem, but I mentioned it because it
reveals the inadequacy of the available information. Not that it's the
fault of the pydoc documentation author(s) for this shortcoming, of
course.

The page does link to a page which deals with the issue of feedback:

    http://www.python.org/dev/doc/devel/lib/about.html

;-)

[Draft document - Setting it up]

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

Perhaps. I'd hesitate to use "<python-version>" in the URL because it
may actually be displayed as a link in whichever browser is used to
display the documentation. Note that I'd used the "::" at the end of
the initial sentence because I'd subversively used reStructuredText
markup (http://docutils.sf.net/). How about the following text?

  If the documentation is required then go to::
  
    http://www.python.org/doc/download.html
 
  and download the HTML documention which is suitable for the version
  of Python you wish to use and install it in a place where it can be
  read by those who need it.

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

I meant, "How can one set up the interpreter so that PYTHONDOCS is
already set to the correct value?"

For example, on a Linux system, one could ensure that each user's
environment has this variable set up by modifying a relevant file
in their home directory. I don't know how you would do this on the Mac
or on Windows.

Another approach would be to modify the sitecustomize.py file; see the
site.py for information about this.

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

Maybe you should forward this suggestion to one of the Python developers;
unless they're reading this thread already.

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

This works for me, although I am using the docs from Python 2.2 with
the Python 2.3 interpreter. Which versions of each are you using?
Maybe something changed at some point - some files were reorganised,
or something?

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

It's the same approach: PYTHONDOCS=<path> pydoc <keyword>

David