[PYTHON DOC-SIG] Re: Do reference/user docs exist for the Py* API?

[Mark Lutz]

>> [stuff about Python C API documentation]
> 
> I had been hoping that Mark Lutz' book would cover things in more detail
> than the existing Python docs -- is that wrong (Mark?)?
 
I suppose it depends on what you mean by "more detail".
 
Yes, my book does go beyond the docs, and discusses C integration in
considerable detail.  In fact, that was one of its original goals: to
provide the extra perspective and context you can't get from manuals.
 
OTOH, my book doesn't replace the manuals; it's not an exhaustive
reference to every "extern" symbol in the Python system.  I think
manuals are a better vehicle for that sort of documentation.
 
A few more details...
The O'Reilly book discusses C integration, by working through examples.
There's a C extension module, a C extension type, extension wrapper
classes, an enhanced embedded-call API, and case studies on embedding
Python in C/C++.  Commonly-used API tools are documented along the way.
 
But it doesn't exhaustively document _every_ C API symbol in detail.
That's material for a reference manual IMHO.  For one thing, such a
reference could add hundreds of pages to an already-huge book.  For
another, the C API changes often; manuals can handle this better.
 
Of course, there is alot of language reference material in my book too,
and it's possible that more might creep in over time.  Which will all
make much more sense when the book finally comes out next month :-).
 
So, my $0.02 -- I think a C API doc outside any book would be a very
useful thing.  Better still, if this material can be put online in
HTML form, it can provide links that a book can't.
 
> I'm not sure what it would mean to help, but I've been writing a reasonable
> number of sets of Python bindings to C over the last several months, and I'd be
> happy to help if I can.
 
Sounds like a volunteer! :-).  BTW, the doc sig mail-list is digging into
this too; check out "doc-sig-request@python.org", unless you already have.
 
Cheers,
Mark L.

=================
DOC-SIG  - SIG for the Python Documentation Project

send messages to: doc-sig@python.org
administrivia to: doc-sig-request@python.org
=================