[PYTHON DOC-SIG] PyCAPI 1.00a2 (now 133 entries and an index)

[Fredrik Lundh]

Various people wrote various things:

> And on another note - the best way for this to be done would be for
> people to be able to contribute individual functions - what's the best
> way of doing this?

I use a plain text format; I'm not fluent in tex, and Word et al are
not as efficient as emacs for terse, kill/yank/macro-intensive editing
like this.  So I write plain text, and process it with a small Python
script to add the necessary formatting.  Here's a sample:

PyObject*
PyInstance_New(PyObject* class, PyObject* arg, PyObject* kw)

	Construct a new _class_ instance object.  If the class
	defines an __init__ method, it is called with _arg_ (a tuple)
	and _kw_ (a dictionary) as arguments.  Otherwise, an empty
	instance is created.

	Exceptions: _err_badcall_, _TypeError_ (constructor takes
	no arguments), _MemoryError_

	Old name: _newinstanceobject_

So to contribute, simply write things down in plain old ASCII using a
style similar to that in the document, use _underscore_ to mark which
words to highlight (the formatter chooses where to use boldface and
italics), and I'll fix the rest in no time at all.

>
> One of the most critical pieces of information to document is
> reference counting behavior of the various functions.  It's the most
> difficult thing for a programmer to get right.  For each function
> input and output I'd like to know if references are consumed or
> produced by the function, for instance.

As Guido answered, the library is usually very consistent in how
things are done.  When things have stabilised, and most of the
functions are covered, I'll add an introduction describing such common
behaviour, and stuff like the object implementation, etc.

>
> BTW the PyArg_GetLong() etc. family of functions is not very useful
> -- they are mostly macros around the preferred PyArg_ParseTuple().

This is important info.  When rushing through the header and source
files, its not always easy to quickly tell whats the preferred way to
do things, and whats internal/obsolete stuff.  We don't need a
Schulman for Python (not yet, at least ;-)

So more of this, please.

>
> I still think LaTeX or TeXinfo would be better vehicles for the
> actual text processing than HTML.  For one thing, TeX and it's
> various spinoff macro packages already have good cross-reference and
> index features.

Well, I wanted to avoid the usual tool-religous wars that tend to halt
many projects before they've even started, collaborative or not...
This far, I've spent some 4 hours on this (including the scripts); I
might be able to finish it off in less than 10 hours in total, but not
if someone forces me to learn one or more new tools in the process.
Its simply a matter of using the available time efficiently.  We can
always convert the stuff later.

(If that strategy isn't acceptable, feel free to write your own C
reference manual.  But if you use my text, don't forget mentioning my
name...)

>
> I'd like to see a more stratified top-level structure, something
> like:

Yep.  But that's obviously a much larger effort.

As for things like a full-blown C programmers reference with a good
narrative section, I think we should consider leaving that to the
professional publishers.  They have enormous resources when it comes
to formatting, copy-editing, indexing, etc; and the author gets a
little money for his efforts as well.  More Python books will
definitely not hurt Python, and more books are already underway.

Besides language tutorial/references, I'd say the aim should be to
keep the freely available documentation complete but terse.  Better to
spend that time on programming...

>
> I want to know how Fredrik manages to find the time for all this!

Well, I'm actually a group of people, working on similar things and
posting from a single account.  So when I contradict myself, say
something utterly stupid, or write very bad English, its probably
someone else.  Or something.

Cheers	/F

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

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