metadocumentation (keyword help)

[Jacek Generowicz]

I always wonder whether I should post concise articles, or wordy ones,
covering all possbile assumpitons and misconceptions.

It appears that, usually, I get the balance hopelessly wrong :-( Or,
maybe, that's just what life is like in a large public forum; whatever
you say, there will always be hundreds of people who misunderstand you.


Thomas Heller <theller at python.net> writes:

> Jacek Generowicz <jacek.generowicz at cern.ch> writes:
> 
> > Yes, but this actually does not work out of the box (on any of the
> > GNU/Linux, Mac OS X, and even Windoze installaitions I have tried). You
> > get an error message complaining about the absence of HTML
> > documentation and setting PYTHONDOCS. So, to rephrase my question ...
> >
> > Where can I find clear instructions on how to install and configure
> > the Python documentation which is necessary to make the following
> > work:
> >
> >    >>> help('and')
> >
> > ?
> 
> Download the HTML archive from
> <http://www.python.org/doc/current/download.html>, and unpack this in a
> temporary directory.  Leave the directory structure intact - in Winzip,
> make sure the 'Use Folder Names' checkbox is checked.
> 
> This creates a Python-Docs-2.3.3 subdirectory.  Copy everything in this
> directory (including subdirectories) into your c:\python23\Doc folder
> (normally there is a single Python23.chm file in it), and you're done.

Does someone who writes 

> > GNU/Linux, Mac OS X, and even Windoze
                             ^^^^    ^^^^
really look like someone who is looking for instructions on fixing his
Python installation on a M$ operating system ?


Jacek Generowicz <jacek.generowicz at cern.ch> originally wrote:

> Where can I find concise, clear documentation[*] describing what one has
> to do in order to enable Python's internal help to be able to provide
> descriptions of Python keywords ?
> 
> I am in a situation where I have to give Python novices the ability to
> fix this for themselves easily.
> 
> 
> [*] Failing "concise" and "clear", how about "complete and correct" ?

I teach an introductionary course on Python. One of the key messages
that I try to convey is that with Python's excellent introspection
capabilities, the built-in help, and the Python web site, you have
pretty much all the information you need at your fingertips. In the
course, I politely refuse to answer any questions which the student
can easily answer himself by using the interactive help. The point is
that I hope that the studens will go away with the ability to find
most things out for themselves. In this context, I would like them to
be able to find out for themselves how to fix the keyword
documentation, which is why I phrased my original question thus:

> Where can I find concise, clear documentation[*] describing what one
> has to do in order to enable Python's internal help to be able to
> provide descriptions of Python keywords ?

Note, I did NOT say "How do I ...", I said "Where do I find
[...] documentation ...".

I am NOT interested in a recipe posted here. I want to know where to
find the official instructions on how it is done, so that I can show
newbies how to find the information themselves.

"Give a man a fish, and he can eat for a day. Teach a man to fish ...",
and all that.

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.

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.