[Doc-SIG] Re: [Python-Dev] Searching Python docs

Thomas Heller thomas.heller@ion-tof.com
Fri, 5 Apr 2002 20:53:56 +0200


From: "Fred L. Drake, Jr." <fdrake@acm.org>
> 
> [This is cross-posted; followups to the Doc-SIG only, please!]
(Great, the next mailing list for me to subscribe :-)
> 
> Which brings me to the issue of a decent index.  (What doesn't,
> eventually?)
> 
> We currently have two documents that discuss the C API, though they
> take (mostly) different approaches.  The API reference has a tolerable
> index (the symbols are there, at least), but the Extending & Embedding
> document doesn't have enough index entries to be very useful (so
> little we don't even include an index), even though it contains some
> strongly overlapping information.
> 
> I *think* it might be a good idea to merge the two documents, but I'm
> not certain I really like that.  There is a strong need to add good
> index entries to the existing Extending & Embedding document at the
> very least, and a combined index would be very valuable.  This is
> something that's been requested for the entire set of documents on
> many occaisions, and would be very handy.  (Especially if we provided
> a better interface for it!)

IMO an index is not needed for the tutorial style manuals, and Extending
& Embedding is one of them. I'm fine with the existing indexes for the
api, lib, and ref manuals. They contain the complete entries which I have
to look up from time to time.

My experience is as follows: I used to use the HTMLHelp version of
the Python docs most of the time, mainly for context-sensitive help
from the editor: Put the cursor on the 'PyObject_GetItemString' word,
press F1, and look at the docs for this function.
This is a use case which is very common for me, and I have not yet
been able to drive a web search engine to do that for me.
The problem is that I always have to locate and download (or even build)
the HTMLHelp version separately.

Therefore I wrote my pyhelp script which does the same from the
command line, and now also as CGI script. Again, in case anyone wants
a to look at a preview:
http://starship.python.net/crew/theller/cgi-bin/pyhelp.cgi
(Any comments/suggestions/flames greatly appreciated).

Enter PyDict_ and press the search button: I find it very useful.
Note that this script (which is in an early stage) finds the index
entries from the api, lib and ref manuals.

Thomas