metadocumentation (keyword help)
davidb at mcs.st-and.ac.uk
Fri Jan 9 20:15:58 CET 2004
Jacek Generowicz <jacek.generowicz at cern.ch> wrote in message news:<tyffzepfofo.fsf at pcepsft001.cern.ch>...
> 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.
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
The page does link to a page which deals with the issue of feedback:
[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:
> 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::
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
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,
> Furthermore, is there anyway of getting help of keywords via pydoc ?
It's the same approach: PYTHONDOCS=<path> pydoc <keyword>
More information about the Python-list