473,382 Members | 1,593 Online
Bytes | Software Development & Data Engineering Community
Post Job

Home Posts Topics Members FAQ

Join Bytes to post your question to a community of 473,382 software developers and data experts.

metadocumentation (keyword help)

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" ?
Jul 18 '05 #1
10 2228
On Tue, Jan 06, 2004 at 03:27:06PM +0100, Jacek Generowicz 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 ?


"Quote them"

help('if')

Jp
Jul 18 '05 #2
sdd
Jp Calderone wrote:
On Tue, Jan 06, 2004 at 03:27:06PM +0100, Jacek Generowicz 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 ?

"Quote them"

help('if')

Jp

Or simply use help()
and interactively enter lines.
Jul 18 '05 #3
sdd <da*****@dsl-only.net> writes:
Jp Calderone wrote:
On Tue, Jan 06, 2004 at 03:27:06PM +0100, Jacek Generowicz 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 ?

"Quote them"

help('if')

Jp


Or simply use help()
and interactively enter lines.

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')


?
Jul 18 '05 #4
Jacek Generowicz <ja**************@cern.ch> writes:
sdd <da*****@dsl-only.net> writes:
Jp Calderone wrote:
> On Tue, Jan 06, 2004 at 03:27:06PM +0100, Jacek Generowicz 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 ?
> "Quote them"

> help('if')

> Jp


Or simply use help()
and interactively enter lines.

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.

Thomas
Jul 18 '05 #5
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 <th*****@python.net> writes:
Jacek Generowicz <ja**************@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 <ja**************@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.
Jul 18 '05 #6
Jacek Generowicz <ja**************@cern.ch> writes:
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 ...".
[...]
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.


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

Thomas
Jul 18 '05 #7
Thomas Heller <th*****@python.net> writes:
So why don't you try to find out yourself???


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.
Jul 18 '05 #8
Jacek Generowicz <ja**************@cern.ch> wrote in message news:<ty*************@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/...ule-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?
Jul 18 '05 #9
David,

Thank you for your refreshingly constructive followup.

da****@mcs.st-and.ac.uk (David Boddie) writes:
Jacek Generowicz <ja**************@cern.ch> wrote in message news:<ty*************@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/...ule-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.
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 hadn't thought of that opiton. Thanks.
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. :-/


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

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


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

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 ?
Jul 18 '05 #10
Jacek Generowicz <ja**************@cern.ch> wrote in message news:<ty*************@pcepsft001.cern.ch>...
Thank you for your refreshingly constructive followup.
No problem.
da****@mcs.st-and.ac.uk (David Boddie) writes:
Jacek Generowicz <ja**************@cern.ch> wrote in message news:<ty*************@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/...ule-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
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]
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:

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.

?


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

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

http://www.python.org/doc/<python-version>/download.html

?


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,
or something?
Furthermore, is there anyway of getting help of keywords via pydoc ?


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

David
Jul 18 '05 #11

This thread has been closed and replies have been disabled. Please start a new discussion.

Similar topics

1
by: Fuzzyman | last post by:
A colleague and I have built a Validator object for use with ConfigObj and other general schema situations. A config file is used to store a schema that specifies how to test a value that it is...
12
by: Ioannis Vranos | last post by:
Just some thought on it, wanting to see any explanations. It was advised in this newsgroups that we should avoid the use of keyword register. However it is a language feature, and if it...
9
by: Bryan Parkoff | last post by:
I have noticed that C programmers put static keyword beside global variable and global functions in C source codes. I believe that it is not necessary and it is not the practice in C++. Static...
3
by: flat_ross | last post by:
For anyone who is just getting into VB.NET and/or is starting to work with inheritance I would like to point out a potential pitfall. We found this confusion recently when code-reviewing an...
4
by: geetha | last post by:
Dear all, I have a database with all the research capabilities of professors of a university. I need to implement a "keyword search" feature in my welcome page which will actually work like a...
6
by: tom | last post by:
Hi I try to check whether a given input is keyword or not. However this script won't identify keyword input as a keyword. How should I modify it to make it work? #!usr/bin/env python import...
2
by: rlemusic | last post by:
Hi everybody, Iím creating a database in Access (I believe itís 2000) to catalogue items in the archives of a small museum. Iím a total n00b as far as using Access goes, but by looking at some...
5
by: kanley | last post by:
I have a main table with a text description field. In this field, its populated with a string of data. I need to identify from this string of data the name of the vendor using some keywords. I...
1
adelemb
by: adelemb | last post by:
Hi, I'm trying to make a SQL statement work and am getting quite mixed up with it, I hope someone can help! I have a form with a textbox named "keyword". I want the user to enter a keyword and...
1
by: CloudSolutions | last post by:
Introduction: For many beginners and individual users, requiring a credit card and email registration may pose a barrier when starting to use cloud servers. However, some cloud server providers now...
0
by: Faith0G | last post by:
I am starting a new it consulting business and it's been a while since I setup a new website. Is wordpress still the best web based software for hosting a 5 page website? The webpages will be...
0
isladogs
by: isladogs | last post by:
The next Access Europe User Group meeting will be on Wednesday 3 Apr 2024 starting at 18:00 UK time (6PM UTC+1) and finishing by 19:30 (7.30PM). In this session, we are pleased to welcome former...
0
by: Charles Arthur | last post by:
How do i turn on java script on a villaon, callus and itel keypad mobile phone
0
by: ryjfgjl | last post by:
If we have dozens or hundreds of excel to import into the database, if we use the excel import function provided by database editors such as navicat, it will be extremely tedious and time-consuming...
0
by: ryjfgjl | last post by:
In our work, we often receive Excel tables with data in the same format. If we want to analyze these data, it can be difficult to analyze them because the data is spread across multiple Excel files...
1
by: nemocccc | last post by:
hello, everyone, I want to develop a software for my android phone for daily needs, any suggestions?
1
by: Sonnysonu | last post by:
This is the data of csv file 1 2 3 1 2 3 1 2 3 1 2 3 2 3 2 3 3 the lengths should be different i have to store the data by column-wise with in the specific length. suppose the i have to...
0
by: Hystou | last post by:
There are some requirements for setting up RAID: 1. The motherboard and BIOS support RAID configuration. 2. The motherboard has 2 or more available SATA protocol SSD/HDD slots (including MSATA, M.2...

By using Bytes.com and it's services, you agree to our Privacy Policy and Terms of Use.

To disable or enable advertisements and analytics tracking please visit the manage ads & tracking page.