[Python-Dev] Searching Python docs (original) (raw)

Fred L. Drake, Jr. fdrake@acm.org
Fri, 5 Apr 2002 13:30:58 -0500

[This is cross-posted; followups to the Doc-SIG only, please!]

Thomas Heller writes:

Hm, in the good old days this was the only way ;-) because the chances where at most 50% that this stuff was undocumented.

I think a lot of us here remember when that 50% was less than 5%, and there was no C API manual. ;-) I still remember seeing the checkin message for api.tex 1.1.

But the docs have improved in the meantime, now you could also use them.

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

-Fred

-- Fred L. Drake, Jr. PythonLabs at Zope Corporation