metadocumentation (keyword help)

[David Boddie]

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

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

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