metadocumentation (keyword help)

[Jacek Generowicz]

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

[Jp Calderone]

Re: metadocumentati on (keyword help)

On Tue, Jan 06, 2004 at 03:27:06PM +0100, Jacek Generowicz wrote:[color=blue]
> 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 ?[/color]

"Quote them"

help('if')

Jp

[sdd]

Re: metadocumentati on (keyword help)

Jp Calderone wrote:
[color=blue]
> On Tue, Jan 06, 2004 at 03:27:06PM +0100, Jacek Generowicz wrote:
>[color=green]
>>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
>>description s of Python keywords ?[/color]
>
>
> "Quote them"
>
> help('if')
>
> Jp
>
>[/color]
Or simply use help()
and interactively enter lines.

[Jacek Generowicz]

Re: metadocumentati on (keyword help)

sdd <daniels@dsl-only.net> writes:
[color=blue]
> Jp Calderone wrote:
>[color=green]
> > On Tue, Jan 06, 2004 at 03:27:06PM +0100, Jacek Generowicz wrote:
> >[/color]
>[color=green][color=darkred]
> >>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
> >>description s of Python keywords ?[/color]
> > "Quote them"[/color]
>[color=green]
> > help('if')[/color]
>[color=green]
> > Jp[/color]
>
> Or simply use help()
> and interactively enter lines.[/color]


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:
[color=blue][color=green][color=darkred]
>>> help('and')[/color][/color][/color]

?

[Thomas Heller]

Re: metadocumentati on (keyword help)

Jacek Generowicz <jacek.generowi cz@cern.ch> writes:
[color=blue]
> sdd <daniels@dsl-only.net> writes:
>[color=green]
>> Jp Calderone wrote:
>>[color=darkred]
>> > On Tue, Jan 06, 2004 at 03:27:06PM +0100, Jacek Generowicz wrote:
>> >[/color]
>>[color=darkred]
>> >>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
>> >>description s of Python keywords ?
>> > "Quote them"[/color]
>>[color=darkred]
>> > help('if')[/color]
>>[color=darkred]
>> > Jp[/color]
>>
>> Or simply use help()
>> and interactively enter lines.[/color]
>
>
> 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:
>[color=green][color=darkred]
> >>> help('and')[/color][/color]
>
> ?[/color]

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.

Thomas

[Jacek Generowicz]

Re: metadocumentati on (keyword help)

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@python .net> writes:
[color=blue]
> Jacek Generowicz <jacek.generowi cz@cern.ch> writes:
>[color=green]
> > 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:
> >[color=darkred]
> > >>> help('and')[/color]
> >
> > ?[/color]
>
> 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.[/color]

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


Jacek Generowicz <jacek.generowi cz@cern.ch> originally wrote:
[color=blue]
> 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" ?[/color]

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:
[color=blue]
> 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 ?[/color]

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.

[Thomas Heller]

Re: metadocumentati on (keyword help)

Jacek Generowicz <jacek.generowi cz@cern.ch> writes:
[color=blue]
> 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,
> Note, I did NOT say "How do I ...", I said "Where do I find
> [...] documentation ...".[/color]

[...]
[color=blue]
> 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.[/color]

So why don't you try to find out yourself???

Thomas

[Jacek Generowicz]

Re: metadocumentati on (keyword help)

Thomas Heller <theller@python .net> writes:
[color=blue]
> So why don't you try to find out yourself???[/color]

a) I have tried, and not found anything.

b) Because a quick and to-the-point response from someone who knows
could save me hours of searching.

I could go on, but this is getting dangerously far off-topic, so I'll
stop there.

[David Boddie]

Re: metadocumentati on (keyword help)

Jacek Generowicz <jacek.generowi cz@cern.ch> wrote in message news:<tyfbrpggc 6u.fsf@pcepsft0 01.cern.ch>...
[color=blue]
> 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.[/color]

Let's hope I'm answering your original question.
[color=blue]
> Does someone who writes
>[color=green][color=darkred]
> > > GNU/Linux, Mac OS X, and even Windoze[/color][/color]
> ^^^^ ^^^^
> really look like someone who is looking for instructions on fixing his
> Python installation on a M$ operating system ?[/color]

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:
[color=blue]
> 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:
>[color=green]
> > 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 ?[/color]
>
> Note, I did NOT say "How do I ...", I said "Where do I find
> [...] documentation ...".[/color]

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.
[color=blue]
> 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.[/color]

Well, I learned something from the recipes posted in this thread, even
if it isn't suitable for your purposes.
[color=blue]
> 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.[/color]

They could always be written up in the PythonInfo Wiki, then at
least you have a python.org URL to give your students.
[color=blue]
> 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.[/color]

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?

[Jacek Generowicz]

Re: metadocumentati on (keyword help)

David,

Thank you for your refreshingly constructive followup.

davidb@mcs.st-and.ac.uk (David Boddie) writes:
[color=blue]
> Jacek Generowicz <jacek.generowi cz@cern.ch> wrote in message news:<tyfbrpggc 6u.fsf@pcepsft0 01.cern.ch>...[color=green]
> > [...][/color]
>
> 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/...ule-pydoc.html[/color]

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.
[color=blue][color=green]
> > 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.[/color]
>
> They could always be written up in the PythonInfo Wiki, then at
> least you have a python.org URL to give your students.[/color]

I hadn't thought of that opiton. Thanks.
[color=blue][color=green]
> > 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.[/color]
>
> 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. :-/[/color]

That is exactly what I was implying with my use of the word "creating".
[color=blue]
> 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.[/color]

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.

?
[color=blue]
> 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?[/color]

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.


Now, currently one gets the following from Python's built-in help:
[color=blue][color=green][color=darkred]
>>> help('if')[/color][/color][/color]

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

?


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 ?


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

[David Boddie]

Re: metadocumentati on (keyword help)

Jacek Generowicz <jacek.generowi cz@cern.ch> wrote in message news:<tyffzepfo fo.fsf@pcepsft0 01.cern.ch>...
[color=blue]
> Thank you for your refreshingly constructive followup.[/color]

No problem.
[color=blue]
> davidb@mcs.st-and.ac.uk (David Boddie) writes:
>[color=green]
> > Jacek Generowicz <jacek.generowi cz@cern.ch> wrote in message news:<tyfbrpggc 6u.fsf@pcepsft0 01.cern.ch>...[color=darkred]
> > > [...][/color]
> >
> > 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/...ule-pydoc.html[/color]
>
> 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.[/color]

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]
[color=blue][color=green]
> > 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.[/color]
>
> 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.
>
> ?[/color]

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 reStructuredTex t
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.
[color=blue][color=green]
> > Enabling this by default
> > ------------------------
> > Any ideas?[/color]
>
> 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.[/color]

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.p y file; see the
site.py for information about this.
[color=blue]
> Now, currently one gets the following from Python's built-in help:
>[color=green][color=darkred]
> >>> help('if')[/color][/color]
>
> 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
>
> ?[/color]

Maybe you should forward this suggestion to one of the Python developers;
unless they're reading this thread already.
[color=blue]
> 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 ?[/color]

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?
[color=blue]
> Furthermore, is there anyway of getting help of keywords via pydoc ?[/color]

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

David