[PYTHON DOC-SIG] PyCAPI 1.00a2 (now 133 entries and an index)
Guido van Rossum
Wed, 21 Aug 1996 14:28:46 -0400
> 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
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
--Guido van Rossum (home page: http://www.python.org/~guido/)
DOC-SIG - SIG for the Python Documentation Project
send messages to: email@example.com
administrivia to: firstname.lastname@example.org