Jacek Generowicz said:
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.
Let's hope I'm answering your original question.
Does someone who writes
^^^^ ^^^^
really look like someone who is looking for instructions on fixing his
Python installation on a M$ operating system ?
I don't know why you wrote that originally. I can only presume that you
were asking for a general solution because, otherwise, it would appear
that you were asking for assistance which you didn't want. Anyway, it
doesn't really matter.
The quoting gets confusing in your message, so I presume that all of
the following attributable to you:
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 ...".
Five minutes with Google failed to reveal any "official" document, if
you don't count mailing list archives. However, five seconds with the
search engine at
http://www.python.org/search/
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
I'm sorry if this isn't good enough for your purposes.
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.
Well, I learned something from the recipes posted in this thread, even
if it isn't suitable for your purposes.
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 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. :-/
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.
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
