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

[Fredrik Lundh]

> An immediate problem is that Framemaker isn't universally available
> this choice will limit who can participate in the documentation project.

True.  Rule me out, for example.

 Being an ex-technical writer/graphics designer, I don't see why we
cannot just use plain old ASCII editors to write the core reference
stuff.  A reference manual really doesn't need much fancy formatting;
its more important to make it easy for anyone to contribute than to
get a tool that allows you do all sorts of formatting stunts from the
beginning.

I'd vote for something very simple:

int
PyArg_GetChar(PyObject* args, int nargs, int i, char* p_arg)

	If _args_ can be interpreted as a character, copy it to
	p_arg[0] and return 1.  Otherwise, raise an exception
	and return 0.

	For details on the other arguments, see _PyArg_GetObject_.

	Old name: _getichararg_

int
PyArg_GetDoubleArray(PyObject* args, int nargs, int i, int n, double* p_arg)

	If _args_ can be interpreted as an array of floating
	point values of length _n_, extract it to _p_arg[0..n-1]_
	and return 1.  Otherwise, raise an exception and return
	0.

	Args can be either a tuple or a sequence.

	For details on the other arguments, see _PyArg_GetObject_.

	Old name: _getidoublearray_

Add a python script that create headings for each function, renders
the function names in boldface and the arguments in italics, and
outputs it all in HTML:

<H3>PyArg_GetDoubleArray</H3>

<b>int<br>
<b>PyArg_GetDoubleArray(<i>PyObject* args, int nargs, int i, int n, double* p_arg)</b></i>
<p>
If <i>args</i> can be interpreted as an array of floating
point values of length <i>n</i>, extract it to <i>p_arg[0..n-1]</i>
and return 1.  Otherwise, raise an exception and return
0.
<p>
Args can be either a tuple or a sequence.
<p>
For details on the other arguments, see <b>PyArg_GetObject</b>.
<p>
Old name: <b>getidoublearray</b>
<p>

>From there, you can convert it to whatever, and add cross-references,
"see alsos", etc.  Anyone not happy with this can write in whatever
tool he prefers, and convert from there to HTML.  The only thing that
needs to be agreed on is the basic layout issues (mainly if and where
to use boldface/italic...).

And hey, my new mail client allows me to write directly in HTML :-)

	/F

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

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