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

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.  <fdrake at acm.org>
PythonLabs at Zope Corporation