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

[Guido van Rossum]

>     1. 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.

Notice that the default is that no references are consumed on
arguments, and a reference is produced on output (thanks for this
terminology).  Only the deviations from this rule have to be noted.

>     3. I'd like the most commonly used stuff documented first.  In my
>     limited experience that would be things like argument passing (PyArg*),
>     sequence (PySequence*, PyList*, PyTuple*) and mapping (PyMapping*,
>     PyDict*) Get/Set/Slice functions, and object creation. Every module
>     function has to deal with one or more of those areas to some degree.
>     Many of the other C API names appear much less frequently in common
>     usage, and may even not be meant for general programmer use, but are
>     just meant for communication between different parts of the run-time
>     system.

Hmm, the abstrct interface makes use of these a lot less necessary.

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

>     4. 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.  I believe tools like latex2html can take advantage of them to
>     generate links and indexes in generated HTML.

This needs to be considered per manual.  For the library manual, at
the moment I think I agree.  For the tutorial and reference manual, I
think there should be one author (me) and FrameMaker is a serious
candidate.  For the extensions manual, I guess there are two parts --
the C API for which the same as for the library reference applies, and
the running text, which works more like a tutorial.  I guess the
proper thing to do is to split the Python C API off into a separate
manual!

--Guido van Rossum (home page: http://www.python.org/~guido/)

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

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