Markup consistency & nits.

Fix typo in a C code example:  KeyError is spelled PyExc_KeyError in C; the
"K" is upper case!

Some index entries.

On function signatures, always use parameter names.  Make return types match
what's in the header files.  When the return type is a pointer, always omit
the space between te type name and the "*"; leaving it in results in

	type * func(..)

and having two spaces there just looks terrible.

Doc/api.tex

@@ -55,7 +55,7 @@ Python in other applications since its early existence, the process of
 embedding Python is less straightforward that writing an extension.  
 Python 1.5 introduces a number of new API functions as well as some 
 changes to the build process that make embedding much simpler.  
-This manual describes the \version\ state of affair.
+This manual describes the \version\ state of affairs.
 % XXX Eventually, take the historical notes out
 
 Many API functions are useful independent of whether you're embedding 
@@ -200,6 +200,7 @@ the moment; a better way to code this is shown below anyway):
 
 \begin{verbatim}
 PyObject *t;
+
 t = PyTuple_New(3);
 PyTuple_SetItem(t, 0, PyInt_FromLong(1L));
 PyTuple_SetItem(t, 1, PyInt_FromLong(2L));
@@ -220,6 +221,7 @@ difference between the two (the extra \cfunction{Py_DECREF()} calls):
 
 \begin{verbatim}
 PyObject *l, *x;
+
 l = PyList_New(3);
 x = PyInt_FromLong(1L);
 PySequence_SetItem(l, 0, x); Py_DECREF(x);
@@ -239,6 +241,7 @@ also takes care of the error checking):
 
 \begin{verbatim}
 PyObject *t, *l;
+
 t = Py_BuildValue("(iis)", 1, 2, "three");
 l = Py_BuildValue("[iis]", 1, 2, "three");
 \end{verbatim}
@@ -256,6 +259,7 @@ item:
 int set_all(PyObject *target, PyObject *item)
 {
     int i, n;
+
     n = PyObject_Length(target);
     if (n < 0)
         return -1;
@@ -299,6 +303,7 @@ long sum_list(PyObject *list)
     int i, n;
     long total = 0;
     PyObject *item;
+
     n = PyList_Size(list);
     if (n < 0)
         return -1; /* Not a list */
@@ -364,7 +369,7 @@ ambiguous return value, and require explicit testing for errors with
 
 Exception state is maintained in per-thread storage (this is 
 equivalent to using global storage in an unthreaded application).  A 
-thread can be on one of two states: an exception has occurred, or not.
+thread can be in one of two states: an exception has occurred, or not.
 The function \cfunction{PyErr_Occurred()} can be used to check for
 this: it returns a borrowed reference to the exception type object
 when an exception has occurred, and \NULL{} otherwise.  There are a
@@ -384,7 +389,7 @@ exception state only exists while an exception is being passed on
 between \C{} functions until it reaches the Python interpreter, which
 takes care of transferring it to \code{sys.exc_type} and friends.
 
-(Note that starting with Python 1.5, the preferred, thread-safe way to 
+Note that starting with Python 1.5, the preferred, thread-safe way to 
 access the exception state from Python code is to call the function 
 \function{sys.exc_info()}, which returns the per-thread exception state 
 for Python code.  Also, the semantics of both ways to access the 
@@ -394,7 +399,7 @@ preserve the exception state of its caller.  This prevents common bugs
 in exception handling code caused by an innocent-looking function 
 overwriting the exception being handled; it also reduces the often 
 unwanted lifetime extension for objects that are referenced by the 
-stack frames in the traceback.)
+stack frames in the traceback.
 
 As a general principle, a function that calls another function to 
 perform some task should check whether the called function raised an 
@@ -431,8 +436,8 @@ int incr_item(PyObject *dict, PyObject *key)
 
     item = PyObject_GetItem(dict, key);
     if (item == NULL) {
-        /* Handle keyError only: */
+        /* Handle KeyError only: */
-        if (!PyErr_ExceptionMatches(PyExc_keyError)) goto error;
+        if (!PyErr_ExceptionMatches(PyExc_KeyError)) goto error;
 
         /* Clear the error and use zero: */
         PyErr_Clear();
@@ -489,7 +494,8 @@ This initializes the table of loaded modules, and creates the
 fundamental modules \module{__builtin__}\refbimodindex{__builtin__},
 \module{__main__}\refbimodindex{__main__} and 
 \module{sys}\refbimodindex{sys}.  It also initializes the module
-search path (\code{sys.path}).
+search path (\code{sys.path}).%
+\indexiii{module}{search}{path}
 
 \cfunction{Py_Initialize()} does not set the ``script argument list'' 
 (\code{sys.argv}).  If this variable is needed by Python code that 
@@ -506,21 +512,21 @@ interpreter executable.  In particular, it looks for a directory named
 \file{lib/python\version} (replacing \file{\version} with the current
 interpreter version) relative to the parent directory where the
 executable named \file{python} is found on the shell command search
-path (the environment variable \code{\$PATH}).
+path (the environment variable \envvar{PATH}).
 
 For instance, if the Python executable is found in
 \file{/usr/local/bin/python}, it will assume that the libraries are in
 \file{/usr/local/lib/python\version}.  (In fact, this particular path
 is also the ``fallback'' location, used when no executable file named
-\file{python} is found along \code{\$PATH}.)  The user can override
+\file{python} is found along \envvar{PATH}.)  The user can override
-this behavior by setting the environment variable \code{\$PYTHONHOME},
+this behavior by setting the environment variable \envvar{PYTHONHOME},
 or insert additional directories in front of the standard path by
-setting \code{\$PYTHONPATH}.
+setting \envvar{PYTHONPATH}.
 
 The embedding application can steer the search by calling 
 \code{Py_SetProgramName(\var{file})} \emph{before} calling 
-\cfunction{Py_Initialize()}.  Note that \code{\$PYTHONHOME} still
+\cfunction{Py_Initialize()}.  Note that \envvar{PYTHONHOME} still
-overrides this and \code{\$PYTHONPATH} is still inserted in front of
+overrides this and \envvar{PYTHONPATH} is still inserted in front of
 the standard path.  An application that requires total control has to
 provide its own implementation of \cfunction{Py_GetPath()},
 \cfunction{Py_GetPrefix()}, \cfunction{Py_GetExecPrefix()},
@@ -544,34 +550,41 @@ The functions in this chapter will let you execute Python source code
 given in a file or a buffer, but they will not let you interact in a
 more detailed way with the interpreter.
 
-\begin{cfuncdesc}{int}{PyRun_AnyFile}{FILE *, char *}
+\begin{cfuncdesc}{int}{PyRun_AnyFile}{FILE *fp, char *filename}
 \end{cfuncdesc}
 
-\begin{cfuncdesc}{int}{PyRun_SimpleString}{char *}
+\begin{cfuncdesc}{int}{PyRun_SimpleString}{char *command}
 \end{cfuncdesc}
 
-\begin{cfuncdesc}{int}{PyRun_SimpleFile}{FILE *, char *}
+\begin{cfuncdesc}{int}{PyRun_SimpleFile}{FILE *fp, char *filename}
 \end{cfuncdesc}
 
-\begin{cfuncdesc}{int}{PyRun_InteractiveOne}{FILE *, char *}
+\begin{cfuncdesc}{int}{PyRun_InteractiveOne}{FILE *fp, char *filename}
 \end{cfuncdesc}
 
-\begin{cfuncdesc}{int}{PyRun_InteractiveLoop}{FILE *, char *}
+\begin{cfuncdesc}{int}{PyRun_InteractiveLoop}{FILE *fp, char *filename}
 \end{cfuncdesc}
 
-\begin{cfuncdesc}{struct _node *}{PyParser_SimpleParseString}{char *, int}
+\begin{cfuncdesc}{struct _node*}{PyParser_SimpleParseString}{char *str,
+                                                             int start}
 \end{cfuncdesc}
 
-\begin{cfuncdesc}{struct _node *}{PyParser_SimpleParseFile}{FILE *, char *, int}
+\begin{cfuncdesc}{struct _node*}{PyParser_SimpleParseFile}{FILE *fp,
+                                 char *filename, int start}
 \end{cfuncdesc}
 
-\begin{cfuncdesc}{PyObject *}{PyRun_String}{char *, int, PyObject *, PyObject *}
+\begin{cfuncdesc}{PyObject*}{PyRun_String}{char *str, int start,
+                                           PyObject *globals,
+                                           PyObject *locals}
 \end{cfuncdesc}
 
-\begin{cfuncdesc}{PyObject *}{PyRun_File}{FILE *, char *, int, PyObject *, PyObject *}
+\begin{cfuncdesc}{PyObject*}{PyRun_File}{FILE *fp, char *filename,
+                                         int start, PyObject *globals,
+                                         PyObject *locals}
 \end{cfuncdesc}
 
-\begin{cfuncdesc}{PyObject *}{Py_CompileString}{char *, char *, int}
+\begin{cfuncdesc}{PyObject*}{Py_CompileString}{char *str, char *filename,
+                                               int start}
 \end{cfuncdesc}
 
 
@@ -582,7 +595,7 @@ The macros in this section are used for managing reference counts
 of Python objects.
 
 \begin{cfuncdesc}{void}{Py_INCREF}{PyObject *o}
-Increment the reference count for object \code{o}.  The object must
+Increment the reference count for object \var{o}.  The object must
 not be \NULL{}; if you aren't sure that it isn't \NULL{}, use
 \cfunction{Py_XINCREF()}.
 \end{cfuncdesc}
@@ -798,7 +811,8 @@ the effect of a \constant{SIGINT} signal arriving --- the next time
 \end{cfuncdesc}
 
 \begin{cfuncdesc}{PyObject*}{PyErr_NewException}{char *name,
-PyObject *base, PyObject *dict}
+                                                 PyObject *base,
+                                                 PyObject *dict}
 This utility function creates and returns a new exception object.  The
 \var{name} argument must be the name of the new exception, a \C{} string
 of the form \code{module.class}.  The \var{base} and \var{dict}
@@ -925,7 +939,7 @@ effect when \var{name} in fact specifies a subpackage instead of a
 submodule: the submodules specified in the package's \code{__all__}
 variable are loaded.)  Return a new reference to the imported module,
 or \NULL{} with an exception set on failure (the module may still
-be created in this case).
+be created in this case --- examine \code{sys.modules} to find out).
 \end{cfuncdesc}
 
 \begin{cfuncdesc}{PyObject*}{PyImport_ImportModuleEx}{char *name, PyObject *globals, PyObject *locals, PyObject *fromlist}
@@ -1003,11 +1017,11 @@ Empty the module table.  For internal use only.
 Finalize the import mechanism.  For internal use only.
 \end{cfuncdesc}
 
-\begin{cfuncdesc}{extern PyObject *}{_PyImport_FindExtension}{char *, char *}
+\begin{cfuncdesc}{PyObject*}{_PyImport_FindExtension}{char *, char *}
 For internal use only.
 \end{cfuncdesc}
 
-\begin{cfuncdesc}{extern PyObject *}{_PyImport_FixupExtension}{char *, char *}
+\begin{cfuncdesc}{PyObject*}{_PyImport_FixupExtension}{char *, char *}
 For internal use only.
 \end{cfuncdesc}
 
@@ -1022,8 +1036,10 @@ already imported.)
 
 \begin{ctypedesc}{struct _frozen}
 This is the structure type definition for frozen module descriptors,
-as generated by the \code{freeze} utility (see \file{Tools/freeze/} in
+as generated by the \program{freeze}\index{freeze utility} utility
-the Python source distribution).  Its definition is:
+(see \file{Tools/freeze/} in the Python source distribution).  Its
+definition is:
+
 \begin{verbatim}
 struct _frozen {
     char *name;
@@ -1037,7 +1053,7 @@ struct _frozen {
 This pointer is initialized to point to an array of \code{struct
 _frozen} records, terminated by one whose members are all \NULL{}
 or zero.  When a frozen module is imported, it is searched in this
-table.  Third party code could play tricks with this to provide a
+table.  Third-party code could play tricks with this to provide a
 dynamically created collection of frozen modules.
 \end{cvardesc}
 
@@ -1708,51 +1724,45 @@ This instance of \code{PyTypeObject} represents the Python string type.
 
 \end{cfuncdesc}
 
-\begin{cfuncdesc}{PyObject *}{PyString_FromStringAndSize}{const char *, int}
+\begin{cfuncdesc}{PyObject*}{PyString_FromStringAndSize}{const char *v,
+                                                          int len}
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{PyObject*}{PyString_FromString}{const char *v}
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{int}{PyString_Size}{PyObject *string}
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{char*}{PyString_AsString}{PyObject *string}
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{void}{PyString_Concat}{PyObject **string,
+                                         PyObject *newpart}
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{void}{PyString_ConcatAndDel}{PyObject **string,
+                                               PyObject *newpart}
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{int}{_PyString_Resize}{PyObject **string, int newsize}
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{PyObject*}{PyString_Format}{PyObject *format,
+                                              PyObject *args}
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{void}{PyString_InternInPlace}{PyObject **string}
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{PyObject*}{PyString_InternFromString}{const char *v}
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{char*}{PyString_AS_STRING}{PyObject *string}
 
 \end{cfuncdesc}
 
-\begin{cfuncdesc}{PyObject *}{PyString_FromString}{const char *}
+\begin{cfuncdesc}{int}{PyString_GET_SIZE}{PyObject *string}
-
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{int}{PyString_Size}{PyObject *}
-
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{char *}{PyString_AsString}{PyObject *}
-
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{void}{PyString_Concat}{PyObject **, PyObject *}
-
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{void}{PyString_ConcatAndDel}{PyObject **, PyObject *}
-
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{int}{_PyString_Resize}{PyObject **, int}
-
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{PyObject *}{PyString_Format}{PyObject *, PyObject *}
-
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{void}{PyString_InternInPlace}{PyObject **}
-
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{PyObject *}{PyString_InternFromString}{const char *}
-
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{char *}{PyString_AS_STRING}{PyStringObject *}
-
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{int}{PyString_GET_SIZE}{PyStringObject *}
 
 \end{cfuncdesc}
 
@@ -1772,7 +1782,7 @@ This instance of \code{PyTypeObject} represents the Python tuple type.
 Return true if the argument is a tuple object.
 \end{cfuncdesc}
 
-\begin{cfuncdesc}{PyTupleObject *}{PyTuple_New}{int s}
+\begin{cfuncdesc}{PyObject*}{PyTuple_New}{int s}
 Return a new tuple object of size \var{s}.
 \end{cfuncdesc}
 
@@ -1791,7 +1801,7 @@ raises an \exception{IndexError} exception.
 Does the same, but does no checking of its arguments.
 \end{cfuncdesc}
 
-\begin{cfuncdesc}{PyTupleObject *}{PyTuple_GetSlice}{PyTupleObject *p,
+\begin{cfuncdesc}{PyObject*}{PyTuple_GetSlice}{PyTupleObject *p,
             int low,
             int high}
 Takes a slice of the tuple pointed to by \var{p} from
@@ -1813,7 +1823,7 @@ Does the same, but does no error checking, and
 should \emph{only} be used to fill in brand new tuples.
 \end{cfuncdesc}
 
-\begin{cfuncdesc}{PyTupleObject *}{_PyTuple_Resize}{PyTupleObject *p,
+\begin{cfuncdesc}{int}{_PyTuple_Resize}{PyTupleObject *p,
             int new,
             int last_is_sticky}
 Can be used to resize a tuple. Because tuples are
@@ -1842,55 +1852,47 @@ Returns true if its argument is a \code{PyListObject}.
 \end{cfuncdesc}
 
 \begin{cfuncdesc}{PyObject*}{PyList_New}{int size}
-
 \end{cfuncdesc}
 
-\begin{cfuncdesc}{int}{PyList_Size}{PyObject *}
+\begin{cfuncdesc}{int}{PyList_Size}{PyObject *list}
-
 \end{cfuncdesc}
 
-\begin{cfuncdesc}{PyObject *}{PyList_GetItem}{PyObject *, int}
+\begin{cfuncdesc}{PyObject*}{PyList_GetItem}{PyObject *list, int index}
-
 \end{cfuncdesc}
 
-\begin{cfuncdesc}{int}{PyList_SetItem}{PyObject *, int, PyObject *}
+\begin{cfuncdesc}{int}{PyList_SetItem}{PyObject *list, int index,
-
+                                       PyObject *item}
 \end{cfuncdesc}
 
-\begin{cfuncdesc}{int}{PyList_Insert}{PyObject *, int, PyObject *}
+\begin{cfuncdesc}{int}{PyList_Insert}{PyObject *list, int index,
-
+                                      PyObject *index}
 \end{cfuncdesc}
 
-\begin{cfuncdesc}{int}{PyList_Append}{PyObject *, PyObject *}
+\begin{cfuncdesc}{int}{PyList_Append}{PyObject *list, PyObject *item}
-
 \end{cfuncdesc}
 
-\begin{cfuncdesc}{PyObject *}{PyList_GetSlice}{PyObject *, int, int}
+\begin{cfuncdesc}{PyObject*}{PyList_GetSlice}{PyObject *list,
-
+                                              int low, int high}
 \end{cfuncdesc}
 
-\begin{cfuncdesc}{int}{PyList_SetSlice}{PyObject *, int, int, PyObject *}
+\begin{cfuncdesc}{int}{PyList_SetSlice}{PyObject *list,
-
+                                        int low, int high,
+                                        PyObject *itemlist}
 \end{cfuncdesc}
 
-\begin{cfuncdesc}{int}{PyList_Sort}{PyObject *}
+\begin{cfuncdesc}{int}{PyList_Sort}{PyObject *list}
-
 \end{cfuncdesc}
 
-\begin{cfuncdesc}{int}{PyList_Reverse}{PyObject *}
+\begin{cfuncdesc}{int}{PyList_Reverse}{PyObject *list}
-
 \end{cfuncdesc}
 
-\begin{cfuncdesc}{PyObject *}{PyList_AsTuple}{PyObject *}
+\begin{cfuncdesc}{PyObject*}{PyList_AsTuple}{PyObject *list}
-
 \end{cfuncdesc}
 
 \begin{cfuncdesc}{PyObject*}{PyList_GET_ITEM}{PyObject *list, int i}
-
 \end{cfuncdesc}
 
 \begin{cfuncdesc}{int}{PyList_GET_SIZE}{PyObject *list}
-
 \end{cfuncdesc}
 
 
@@ -1912,7 +1914,7 @@ This instance of \code{PyTypeObject} represents the Python dictionary type.
 Returns true if its argument is a \code{PyDictObject}.
 \end{cfuncdesc}
 
-\begin{cfuncdesc}{PyDictObject *}{PyDict_New}{}
+\begin{cfuncdesc}{PyObject*}{PyDict_New}{}
 Returns a new empty dictionary.
 \end{cfuncdesc}
 
@@ -1956,19 +1958,19 @@ Does the same, but \var{key} is specified as a
 \code{char *}, rather than a \code{PyObject *}.
 \end{cfuncdesc}
 
-\begin{cfuncdesc}{PyListObject *}{PyDict_Items}{PyDictObject *p}
+\begin{cfuncdesc}{PyObject*}{PyDict_Items}{PyDictObject *p}
 Returns a \code{PyListObject} containing all the items 
 from the dictionary, as in the mapping method \method{items()} (see
 the \emph{Python Library Reference}).
 \end{cfuncdesc}
 
-\begin{cfuncdesc}{PyListObject *}{PyDict_Keys}{PyDictObject *p}
+\begin{cfuncdesc}{PyObject*}{PyDict_Keys}{PyDictObject *p}
 Returns a \code{PyListObject} containing all the keys 
 from the dictionary, as in the mapping method \method{keys()} (see the
 \emph{Python Library Reference}).
 \end{cfuncdesc}
 
-\begin{cfuncdesc}{PyListObject *}{PyDict_Values}{PyDictObject *p}
+\begin{cfuncdesc}{PyObject*}{PyDict_Values}{PyDictObject *p}
 Returns a \code{PyListObject} containing all the values 
 from the dictionary \var{p}, as in the mapping method
 \method{values()} (see the \emph{Python Library Reference}).
@@ -2005,7 +2007,7 @@ integer type.
 
 \end{cfuncdesc}
 
-\begin{cfuncdesc}{PyIntObject *}{PyInt_FromLong}{long ival}
+\begin{cfuncdesc}{PyObject*}{PyInt_FromLong}{long ival}
 Creates a new integer object with a value of \var{ival}.
 
 The current implementation keeps an array of integer objects for all
@@ -2048,32 +2050,26 @@ integer type.
 Returns true if its argument is a \code{PyLongObject}.
 \end{cfuncdesc}
 
-\begin{cfuncdesc}{PyObject *}{PyLong_FromLong}{long}
+\begin{cfuncdesc}{PyObject*}{PyLong_FromLong}{long v}
-
 \end{cfuncdesc}
 
-\begin{cfuncdesc}{PyObject *}{PyLong_FromUnsignedLong}{unsigned long}
+\begin{cfuncdesc}{PyObject*}{PyLong_FromUnsignedLong}{unsigned long v}
-
 \end{cfuncdesc}
 
-\begin{cfuncdesc}{PyObject *}{PyLong_FromDouble}{double}
+\begin{cfuncdesc}{PyObject*}{PyLong_FromDouble}{double v}
-
 \end{cfuncdesc}
 
-\begin{cfuncdesc}{long}{PyLong_AsLong}{PyObject *}
+\begin{cfuncdesc}{long}{PyLong_AsLong}{PyObject *pylong}
-
 \end{cfuncdesc}
 
-\begin{cfuncdesc}{unsigned long}{PyLong_AsUnsignedLong}{PyObject }
+\begin{cfuncdesc}{unsigned long}{PyLong_AsUnsignedLong}{PyObject *pylong}
-
 \end{cfuncdesc}
 
-\begin{cfuncdesc}{double}{PyLong_AsDouble}{PyObject *}
+\begin{cfuncdesc}{double}{PyLong_AsDouble}{PyObject *pylong}
-
 \end{cfuncdesc}
 
-\begin{cfuncdesc}{PyObject *}{PyLong_FromString}{char *, char **, int}
+\begin{cfuncdesc}{PyObject*}{PyLong_FromString}{char *str, char **pend,
-
+                                                int base}
 \end{cfuncdesc}
 
 
@@ -2094,16 +2090,13 @@ point type.
 Returns true if its argument is a \code{PyFloatObject}.
 \end{cfuncdesc}
 
-\begin{cfuncdesc}{PyObject *}{PyFloat_FromDouble}{double}
+\begin{cfuncdesc}{PyObject*}{PyFloat_FromDouble}{double v}
-
 \end{cfuncdesc}
 
-\begin{cfuncdesc}{double}{PyFloat_AsDouble}{PyObject *}
+\begin{cfuncdesc}{double}{PyFloat_AsDouble}{PyObject *pyfloat}
-
 \end{cfuncdesc}
 
-\begin{cfuncdesc}{double}{PyFloat_AS_DOUBLE}{PyFloatObject *}
+\begin{cfuncdesc}{double}{PyFloat_AS_DOUBLE}{PyObject *pyfloat}
-
 \end{cfuncdesc}
 
 
@@ -2137,48 +2130,38 @@ number type.
 Returns true if its argument is a \code{PyComplexObject}.
 \end{cfuncdesc}
 
-\begin{cfuncdesc}{Py_complex}{_Py_c_sum}{Py_complex, Py_complex}
+\begin{cfuncdesc}{Py_complex}{_Py_c_sum}{Py_complex left, Py_complex right}
-
 \end{cfuncdesc}
 
-\begin{cfuncdesc}{Py_complex}{_Py_c_diff}{Py_complex, Py_complex}
+\begin{cfuncdesc}{Py_complex}{_Py_c_diff}{Py_complex left, Py_complex right}
-
 \end{cfuncdesc}
 
-\begin{cfuncdesc}{Py_complex}{_Py_c_neg}{Py_complex}
+\begin{cfuncdesc}{Py_complex}{_Py_c_neg}{Py_complex complex}
-
 \end{cfuncdesc}
 
-\begin{cfuncdesc}{Py_complex}{_Py_c_prod}{Py_complex, Py_complex}
+\begin{cfuncdesc}{Py_complex}{_Py_c_prod}{Py_complex left, Py_complex right}
-
 \end{cfuncdesc}
 
-\begin{cfuncdesc}{Py_complex}{_Py_c_quot}{Py_complex, Py_complex}
+\begin{cfuncdesc}{Py_complex}{_Py_c_quot}{Py_complex dividend,
-
+                                          Py_complex divisor}
 \end{cfuncdesc}
 
-\begin{cfuncdesc}{Py_complex}{_Py_c_pow}{Py_complex, Py_complex}
+\begin{cfuncdesc}{Py_complex}{_Py_c_pow}{Py_complex num, Py_complex exp}
-
 \end{cfuncdesc}
 
-\begin{cfuncdesc}{PyObject *}{PyComplex_FromCComplex}{Py_complex}
+\begin{cfuncdesc}{PyObject*}{PyComplex_FromCComplex}{Py_complex v}
-
 \end{cfuncdesc}
 
 \begin{cfuncdesc}{PyObject*}{PyComplex_FromDoubles}{double real, double imag}
-
 \end{cfuncdesc}
 
 \begin{cfuncdesc}{double}{PyComplex_RealAsDouble}{PyObject *op}
-
 \end{cfuncdesc}
 
 \begin{cfuncdesc}{double}{PyComplex_ImagAsDouble}{PyObject *op}
-
 \end{cfuncdesc}
 
 \begin{cfuncdesc}{Py_complex}{PyComplex_AsCComplex}{PyObject *op}
-
 \end{cfuncdesc}
 
 
@@ -2217,11 +2200,11 @@ closed.
 Returns the file object associated with \var{p} as a \code{FILE *}.
 \end{cfuncdesc}
 
-\begin{cfuncdesc}{PyStringObject *}{PyFile_GetLine}{PyObject *p, int n}
+\begin{cfuncdesc}{PyObject*}{PyFile_GetLine}{PyObject *p, int n}
 undocumented as yet
 \end{cfuncdesc}
 
-\begin{cfuncdesc}{PyStringObject *}{PyFile_Name}{PyObject *p}
+\begin{cfuncdesc}{PyObject*}{PyFile_Name}{PyObject *p}
 Returns the name of the file specified by \var{p} as a 
 \code{PyStringObject}.
 \end{cfuncdesc}
@@ -2233,17 +2216,19 @@ only be called immediately after file object creation.
 
 \begin{cfuncdesc}{int}{PyFile_SoftSpace}{PyFileObject *p, int newflag}
 Sets the \code{softspace} attribute of \var{p} to \var{newflag}.
-Returns the previosu value.  This function clears any errors, and will
+Returns the previous value.  This function clears any errors, and will
 return \code{0} as the previous value if the attribute either does not
 exist or if there were errors in retrieving it.  There is no way to
 detect errors from this function, but doing so should not be needed.
 \end{cfuncdesc}
 
-\begin{cfuncdesc}{int}{PyFile_WriteObject}{PyObject *obj, PyFileObject *p}
+\begin{cfuncdesc}{int}{PyFile_WriteObject}{PyObject *obj, PyFileObject *p,
+                                           int flags}
 Writes object \var{obj} to file object \var{p}.
 \end{cfuncdesc}
 
-\begin{cfuncdesc}{int}{PyFile_WriteString}{char *s, PyFileObject *p}
+\begin{cfuncdesc}{int}{PyFile_WriteString}{char *s, PyFileObject *p,
+                                           int flags}
 Writes string \var{s} to file object \var{p}.
 \end{cfuncdesc}
 

Doc/api/api.tex

@@ -55,7 +55,7 @@ Python in other applications since its early existence, the process of
 embedding Python is less straightforward that writing an extension.  
 Python 1.5 introduces a number of new API functions as well as some 
 changes to the build process that make embedding much simpler.  
-This manual describes the \version\ state of affair.
+This manual describes the \version\ state of affairs.
 % XXX Eventually, take the historical notes out
 
 Many API functions are useful independent of whether you're embedding 
@@ -200,6 +200,7 @@ the moment; a better way to code this is shown below anyway):
 
 \begin{verbatim}
 PyObject *t;
+
 t = PyTuple_New(3);
 PyTuple_SetItem(t, 0, PyInt_FromLong(1L));
 PyTuple_SetItem(t, 1, PyInt_FromLong(2L));
@@ -220,6 +221,7 @@ difference between the two (the extra \cfunction{Py_DECREF()} calls):
 
 \begin{verbatim}
 PyObject *l, *x;
+
 l = PyList_New(3);
 x = PyInt_FromLong(1L);
 PySequence_SetItem(l, 0, x); Py_DECREF(x);
@@ -239,6 +241,7 @@ also takes care of the error checking):
 
 \begin{verbatim}
 PyObject *t, *l;
+
 t = Py_BuildValue("(iis)", 1, 2, "three");
 l = Py_BuildValue("[iis]", 1, 2, "three");
 \end{verbatim}
@@ -256,6 +259,7 @@ item:
 int set_all(PyObject *target, PyObject *item)
 {
     int i, n;
+
     n = PyObject_Length(target);
     if (n < 0)
         return -1;
@@ -299,6 +303,7 @@ long sum_list(PyObject *list)
     int i, n;
     long total = 0;
     PyObject *item;
+
     n = PyList_Size(list);
     if (n < 0)
         return -1; /* Not a list */
@@ -364,7 +369,7 @@ ambiguous return value, and require explicit testing for errors with
 
 Exception state is maintained in per-thread storage (this is 
 equivalent to using global storage in an unthreaded application).  A 
-thread can be on one of two states: an exception has occurred, or not.
+thread can be in one of two states: an exception has occurred, or not.
 The function \cfunction{PyErr_Occurred()} can be used to check for
 this: it returns a borrowed reference to the exception type object
 when an exception has occurred, and \NULL{} otherwise.  There are a
@@ -384,7 +389,7 @@ exception state only exists while an exception is being passed on
 between \C{} functions until it reaches the Python interpreter, which
 takes care of transferring it to \code{sys.exc_type} and friends.
 
-(Note that starting with Python 1.5, the preferred, thread-safe way to 
+Note that starting with Python 1.5, the preferred, thread-safe way to 
 access the exception state from Python code is to call the function 
 \function{sys.exc_info()}, which returns the per-thread exception state 
 for Python code.  Also, the semantics of both ways to access the 
@@ -394,7 +399,7 @@ preserve the exception state of its caller.  This prevents common bugs
 in exception handling code caused by an innocent-looking function 
 overwriting the exception being handled; it also reduces the often 
 unwanted lifetime extension for objects that are referenced by the 
-stack frames in the traceback.)
+stack frames in the traceback.
 
 As a general principle, a function that calls another function to 
 perform some task should check whether the called function raised an 
@@ -431,8 +436,8 @@ int incr_item(PyObject *dict, PyObject *key)
 
     item = PyObject_GetItem(dict, key);
     if (item == NULL) {
-        /* Handle keyError only: */
+        /* Handle KeyError only: */
-        if (!PyErr_ExceptionMatches(PyExc_keyError)) goto error;
+        if (!PyErr_ExceptionMatches(PyExc_KeyError)) goto error;
 
         /* Clear the error and use zero: */
         PyErr_Clear();
@@ -489,7 +494,8 @@ This initializes the table of loaded modules, and creates the
 fundamental modules \module{__builtin__}\refbimodindex{__builtin__},
 \module{__main__}\refbimodindex{__main__} and 
 \module{sys}\refbimodindex{sys}.  It also initializes the module
-search path (\code{sys.path}).
+search path (\code{sys.path}).%
+\indexiii{module}{search}{path}
 
 \cfunction{Py_Initialize()} does not set the ``script argument list'' 
 (\code{sys.argv}).  If this variable is needed by Python code that 
@@ -506,21 +512,21 @@ interpreter executable.  In particular, it looks for a directory named
 \file{lib/python\version} (replacing \file{\version} with the current
 interpreter version) relative to the parent directory where the
 executable named \file{python} is found on the shell command search
-path (the environment variable \code{\$PATH}).
+path (the environment variable \envvar{PATH}).
 
 For instance, if the Python executable is found in
 \file{/usr/local/bin/python}, it will assume that the libraries are in
 \file{/usr/local/lib/python\version}.  (In fact, this particular path
 is also the ``fallback'' location, used when no executable file named
-\file{python} is found along \code{\$PATH}.)  The user can override
+\file{python} is found along \envvar{PATH}.)  The user can override
-this behavior by setting the environment variable \code{\$PYTHONHOME},
+this behavior by setting the environment variable \envvar{PYTHONHOME},
 or insert additional directories in front of the standard path by
-setting \code{\$PYTHONPATH}.
+setting \envvar{PYTHONPATH}.
 
 The embedding application can steer the search by calling 
 \code{Py_SetProgramName(\var{file})} \emph{before} calling 
-\cfunction{Py_Initialize()}.  Note that \code{\$PYTHONHOME} still
+\cfunction{Py_Initialize()}.  Note that \envvar{PYTHONHOME} still
-overrides this and \code{\$PYTHONPATH} is still inserted in front of
+overrides this and \envvar{PYTHONPATH} is still inserted in front of
 the standard path.  An application that requires total control has to
 provide its own implementation of \cfunction{Py_GetPath()},
 \cfunction{Py_GetPrefix()}, \cfunction{Py_GetExecPrefix()},
@@ -544,34 +550,41 @@ The functions in this chapter will let you execute Python source code
 given in a file or a buffer, but they will not let you interact in a
 more detailed way with the interpreter.
 
-\begin{cfuncdesc}{int}{PyRun_AnyFile}{FILE *, char *}
+\begin{cfuncdesc}{int}{PyRun_AnyFile}{FILE *fp, char *filename}
 \end{cfuncdesc}
 
-\begin{cfuncdesc}{int}{PyRun_SimpleString}{char *}
+\begin{cfuncdesc}{int}{PyRun_SimpleString}{char *command}
 \end{cfuncdesc}
 
-\begin{cfuncdesc}{int}{PyRun_SimpleFile}{FILE *, char *}
+\begin{cfuncdesc}{int}{PyRun_SimpleFile}{FILE *fp, char *filename}
 \end{cfuncdesc}
 
-\begin{cfuncdesc}{int}{PyRun_InteractiveOne}{FILE *, char *}
+\begin{cfuncdesc}{int}{PyRun_InteractiveOne}{FILE *fp, char *filename}
 \end{cfuncdesc}
 
-\begin{cfuncdesc}{int}{PyRun_InteractiveLoop}{FILE *, char *}
+\begin{cfuncdesc}{int}{PyRun_InteractiveLoop}{FILE *fp, char *filename}
 \end{cfuncdesc}
 
-\begin{cfuncdesc}{struct _node *}{PyParser_SimpleParseString}{char *, int}
+\begin{cfuncdesc}{struct _node*}{PyParser_SimpleParseString}{char *str,
+                                                             int start}
 \end{cfuncdesc}
 
-\begin{cfuncdesc}{struct _node *}{PyParser_SimpleParseFile}{FILE *, char *, int}
+\begin{cfuncdesc}{struct _node*}{PyParser_SimpleParseFile}{FILE *fp,
+                                 char *filename, int start}
 \end{cfuncdesc}
 
-\begin{cfuncdesc}{PyObject *}{PyRun_String}{char *, int, PyObject *, PyObject *}
+\begin{cfuncdesc}{PyObject*}{PyRun_String}{char *str, int start,
+                                           PyObject *globals,
+                                           PyObject *locals}
 \end{cfuncdesc}
 
-\begin{cfuncdesc}{PyObject *}{PyRun_File}{FILE *, char *, int, PyObject *, PyObject *}
+\begin{cfuncdesc}{PyObject*}{PyRun_File}{FILE *fp, char *filename,
+                                         int start, PyObject *globals,
+                                         PyObject *locals}
 \end{cfuncdesc}
 
-\begin{cfuncdesc}{PyObject *}{Py_CompileString}{char *, char *, int}
+\begin{cfuncdesc}{PyObject*}{Py_CompileString}{char *str, char *filename,
+                                               int start}
 \end{cfuncdesc}
 
 
@@ -582,7 +595,7 @@ The macros in this section are used for managing reference counts
 of Python objects.
 
 \begin{cfuncdesc}{void}{Py_INCREF}{PyObject *o}
-Increment the reference count for object \code{o}.  The object must
+Increment the reference count for object \var{o}.  The object must
 not be \NULL{}; if you aren't sure that it isn't \NULL{}, use
 \cfunction{Py_XINCREF()}.
 \end{cfuncdesc}
@@ -798,7 +811,8 @@ the effect of a \constant{SIGINT} signal arriving --- the next time
 \end{cfuncdesc}
 
 \begin{cfuncdesc}{PyObject*}{PyErr_NewException}{char *name,
-PyObject *base, PyObject *dict}
+                                                 PyObject *base,
+                                                 PyObject *dict}
 This utility function creates and returns a new exception object.  The
 \var{name} argument must be the name of the new exception, a \C{} string
 of the form \code{module.class}.  The \var{base} and \var{dict}
@@ -925,7 +939,7 @@ effect when \var{name} in fact specifies a subpackage instead of a
 submodule: the submodules specified in the package's \code{__all__}
 variable are loaded.)  Return a new reference to the imported module,
 or \NULL{} with an exception set on failure (the module may still
-be created in this case).
+be created in this case --- examine \code{sys.modules} to find out).
 \end{cfuncdesc}
 
 \begin{cfuncdesc}{PyObject*}{PyImport_ImportModuleEx}{char *name, PyObject *globals, PyObject *locals, PyObject *fromlist}
@@ -1003,11 +1017,11 @@ Empty the module table.  For internal use only.
 Finalize the import mechanism.  For internal use only.
 \end{cfuncdesc}
 
-\begin{cfuncdesc}{extern PyObject *}{_PyImport_FindExtension}{char *, char *}
+\begin{cfuncdesc}{PyObject*}{_PyImport_FindExtension}{char *, char *}
 For internal use only.
 \end{cfuncdesc}
 
-\begin{cfuncdesc}{extern PyObject *}{_PyImport_FixupExtension}{char *, char *}
+\begin{cfuncdesc}{PyObject*}{_PyImport_FixupExtension}{char *, char *}
 For internal use only.
 \end{cfuncdesc}
 
@@ -1022,8 +1036,10 @@ already imported.)
 
 \begin{ctypedesc}{struct _frozen}
 This is the structure type definition for frozen module descriptors,
-as generated by the \code{freeze} utility (see \file{Tools/freeze/} in
+as generated by the \program{freeze}\index{freeze utility} utility
-the Python source distribution).  Its definition is:
+(see \file{Tools/freeze/} in the Python source distribution).  Its
+definition is:
+
 \begin{verbatim}
 struct _frozen {
     char *name;
@@ -1037,7 +1053,7 @@ struct _frozen {
 This pointer is initialized to point to an array of \code{struct
 _frozen} records, terminated by one whose members are all \NULL{}
 or zero.  When a frozen module is imported, it is searched in this
-table.  Third party code could play tricks with this to provide a
+table.  Third-party code could play tricks with this to provide a
 dynamically created collection of frozen modules.
 \end{cvardesc}
 
@@ -1708,51 +1724,45 @@ This instance of \code{PyTypeObject} represents the Python string type.
 
 \end{cfuncdesc}
 
-\begin{cfuncdesc}{PyObject *}{PyString_FromStringAndSize}{const char *, int}
+\begin{cfuncdesc}{PyObject*}{PyString_FromStringAndSize}{const char *v,
+                                                          int len}
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{PyObject*}{PyString_FromString}{const char *v}
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{int}{PyString_Size}{PyObject *string}
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{char*}{PyString_AsString}{PyObject *string}
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{void}{PyString_Concat}{PyObject **string,
+                                         PyObject *newpart}
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{void}{PyString_ConcatAndDel}{PyObject **string,
+                                               PyObject *newpart}
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{int}{_PyString_Resize}{PyObject **string, int newsize}
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{PyObject*}{PyString_Format}{PyObject *format,
+                                              PyObject *args}
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{void}{PyString_InternInPlace}{PyObject **string}
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{PyObject*}{PyString_InternFromString}{const char *v}
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{char*}{PyString_AS_STRING}{PyObject *string}
 
 \end{cfuncdesc}
 
-\begin{cfuncdesc}{PyObject *}{PyString_FromString}{const char *}
+\begin{cfuncdesc}{int}{PyString_GET_SIZE}{PyObject *string}
-
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{int}{PyString_Size}{PyObject *}
-
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{char *}{PyString_AsString}{PyObject *}
-
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{void}{PyString_Concat}{PyObject **, PyObject *}
-
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{void}{PyString_ConcatAndDel}{PyObject **, PyObject *}
-
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{int}{_PyString_Resize}{PyObject **, int}
-
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{PyObject *}{PyString_Format}{PyObject *, PyObject *}
-
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{void}{PyString_InternInPlace}{PyObject **}
-
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{PyObject *}{PyString_InternFromString}{const char *}
-
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{char *}{PyString_AS_STRING}{PyStringObject *}
-
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{int}{PyString_GET_SIZE}{PyStringObject *}
 
 \end{cfuncdesc}
 
@@ -1772,7 +1782,7 @@ This instance of \code{PyTypeObject} represents the Python tuple type.
 Return true if the argument is a tuple object.
 \end{cfuncdesc}
 
-\begin{cfuncdesc}{PyTupleObject *}{PyTuple_New}{int s}
+\begin{cfuncdesc}{PyObject*}{PyTuple_New}{int s}
 Return a new tuple object of size \var{s}.
 \end{cfuncdesc}
 
@@ -1791,7 +1801,7 @@ raises an \exception{IndexError} exception.
 Does the same, but does no checking of its arguments.
 \end{cfuncdesc}
 
-\begin{cfuncdesc}{PyTupleObject *}{PyTuple_GetSlice}{PyTupleObject *p,
+\begin{cfuncdesc}{PyObject*}{PyTuple_GetSlice}{PyTupleObject *p,
             int low,
             int high}
 Takes a slice of the tuple pointed to by \var{p} from
@@ -1813,7 +1823,7 @@ Does the same, but does no error checking, and
 should \emph{only} be used to fill in brand new tuples.
 \end{cfuncdesc}
 
-\begin{cfuncdesc}{PyTupleObject *}{_PyTuple_Resize}{PyTupleObject *p,
+\begin{cfuncdesc}{int}{_PyTuple_Resize}{PyTupleObject *p,
             int new,
             int last_is_sticky}
 Can be used to resize a tuple. Because tuples are
@@ -1842,55 +1852,47 @@ Returns true if its argument is a \code{PyListObject}.
 \end{cfuncdesc}
 
 \begin{cfuncdesc}{PyObject*}{PyList_New}{int size}
-
 \end{cfuncdesc}
 
-\begin{cfuncdesc}{int}{PyList_Size}{PyObject *}
+\begin{cfuncdesc}{int}{PyList_Size}{PyObject *list}
-
 \end{cfuncdesc}
 
-\begin{cfuncdesc}{PyObject *}{PyList_GetItem}{PyObject *, int}
+\begin{cfuncdesc}{PyObject*}{PyList_GetItem}{PyObject *list, int index}
-
 \end{cfuncdesc}
 
-\begin{cfuncdesc}{int}{PyList_SetItem}{PyObject *, int, PyObject *}
+\begin{cfuncdesc}{int}{PyList_SetItem}{PyObject *list, int index,
-
+                                       PyObject *item}
 \end{cfuncdesc}
 
-\begin{cfuncdesc}{int}{PyList_Insert}{PyObject *, int, PyObject *}
+\begin{cfuncdesc}{int}{PyList_Insert}{PyObject *list, int index,
-
+                                      PyObject *index}
 \end{cfuncdesc}
 
-\begin{cfuncdesc}{int}{PyList_Append}{PyObject *, PyObject *}
+\begin{cfuncdesc}{int}{PyList_Append}{PyObject *list, PyObject *item}
-
 \end{cfuncdesc}
 
-\begin{cfuncdesc}{PyObject *}{PyList_GetSlice}{PyObject *, int, int}
+\begin{cfuncdesc}{PyObject*}{PyList_GetSlice}{PyObject *list,
-
+                                              int low, int high}
 \end{cfuncdesc}
 
-\begin{cfuncdesc}{int}{PyList_SetSlice}{PyObject *, int, int, PyObject *}
+\begin{cfuncdesc}{int}{PyList_SetSlice}{PyObject *list,
-
+                                        int low, int high,
+                                        PyObject *itemlist}
 \end{cfuncdesc}
 
-\begin{cfuncdesc}{int}{PyList_Sort}{PyObject *}
+\begin{cfuncdesc}{int}{PyList_Sort}{PyObject *list}
-
 \end{cfuncdesc}
 
-\begin{cfuncdesc}{int}{PyList_Reverse}{PyObject *}
+\begin{cfuncdesc}{int}{PyList_Reverse}{PyObject *list}
-
 \end{cfuncdesc}
 
-\begin{cfuncdesc}{PyObject *}{PyList_AsTuple}{PyObject *}
+\begin{cfuncdesc}{PyObject*}{PyList_AsTuple}{PyObject *list}
-
 \end{cfuncdesc}
 
 \begin{cfuncdesc}{PyObject*}{PyList_GET_ITEM}{PyObject *list, int i}
-
 \end{cfuncdesc}
 
 \begin{cfuncdesc}{int}{PyList_GET_SIZE}{PyObject *list}
-
 \end{cfuncdesc}
 
 
@@ -1912,7 +1914,7 @@ This instance of \code{PyTypeObject} represents the Python dictionary type.
 Returns true if its argument is a \code{PyDictObject}.
 \end{cfuncdesc}
 
-\begin{cfuncdesc}{PyDictObject *}{PyDict_New}{}
+\begin{cfuncdesc}{PyObject*}{PyDict_New}{}
 Returns a new empty dictionary.
 \end{cfuncdesc}
 
@@ -1956,19 +1958,19 @@ Does the same, but \var{key} is specified as a
 \code{char *}, rather than a \code{PyObject *}.
 \end{cfuncdesc}
 
-\begin{cfuncdesc}{PyListObject *}{PyDict_Items}{PyDictObject *p}
+\begin{cfuncdesc}{PyObject*}{PyDict_Items}{PyDictObject *p}
 Returns a \code{PyListObject} containing all the items 
 from the dictionary, as in the mapping method \method{items()} (see
 the \emph{Python Library Reference}).
 \end{cfuncdesc}
 
-\begin{cfuncdesc}{PyListObject *}{PyDict_Keys}{PyDictObject *p}
+\begin{cfuncdesc}{PyObject*}{PyDict_Keys}{PyDictObject *p}
 Returns a \code{PyListObject} containing all the keys 
 from the dictionary, as in the mapping method \method{keys()} (see the
 \emph{Python Library Reference}).
 \end{cfuncdesc}
 
-\begin{cfuncdesc}{PyListObject *}{PyDict_Values}{PyDictObject *p}
+\begin{cfuncdesc}{PyObject*}{PyDict_Values}{PyDictObject *p}
 Returns a \code{PyListObject} containing all the values 
 from the dictionary \var{p}, as in the mapping method
 \method{values()} (see the \emph{Python Library Reference}).
@@ -2005,7 +2007,7 @@ integer type.
 
 \end{cfuncdesc}
 
-\begin{cfuncdesc}{PyIntObject *}{PyInt_FromLong}{long ival}
+\begin{cfuncdesc}{PyObject*}{PyInt_FromLong}{long ival}
 Creates a new integer object with a value of \var{ival}.
 
 The current implementation keeps an array of integer objects for all
@@ -2048,32 +2050,26 @@ integer type.
 Returns true if its argument is a \code{PyLongObject}.
 \end{cfuncdesc}
 
-\begin{cfuncdesc}{PyObject *}{PyLong_FromLong}{long}
+\begin{cfuncdesc}{PyObject*}{PyLong_FromLong}{long v}
-
 \end{cfuncdesc}
 
-\begin{cfuncdesc}{PyObject *}{PyLong_FromUnsignedLong}{unsigned long}
+\begin{cfuncdesc}{PyObject*}{PyLong_FromUnsignedLong}{unsigned long v}
-
 \end{cfuncdesc}
 
-\begin{cfuncdesc}{PyObject *}{PyLong_FromDouble}{double}
+\begin{cfuncdesc}{PyObject*}{PyLong_FromDouble}{double v}
-
 \end{cfuncdesc}
 
-\begin{cfuncdesc}{long}{PyLong_AsLong}{PyObject *}
+\begin{cfuncdesc}{long}{PyLong_AsLong}{PyObject *pylong}
-
 \end{cfuncdesc}
 
-\begin{cfuncdesc}{unsigned long}{PyLong_AsUnsignedLong}{PyObject }
+\begin{cfuncdesc}{unsigned long}{PyLong_AsUnsignedLong}{PyObject *pylong}
-
 \end{cfuncdesc}
 
-\begin{cfuncdesc}{double}{PyLong_AsDouble}{PyObject *}
+\begin{cfuncdesc}{double}{PyLong_AsDouble}{PyObject *pylong}
-
 \end{cfuncdesc}
 
-\begin{cfuncdesc}{PyObject *}{PyLong_FromString}{char *, char **, int}
+\begin{cfuncdesc}{PyObject*}{PyLong_FromString}{char *str, char **pend,
-
+                                                int base}
 \end{cfuncdesc}
 
 
@@ -2094,16 +2090,13 @@ point type.
 Returns true if its argument is a \code{PyFloatObject}.
 \end{cfuncdesc}
 
-\begin{cfuncdesc}{PyObject *}{PyFloat_FromDouble}{double}
+\begin{cfuncdesc}{PyObject*}{PyFloat_FromDouble}{double v}
-
 \end{cfuncdesc}
 
-\begin{cfuncdesc}{double}{PyFloat_AsDouble}{PyObject *}
+\begin{cfuncdesc}{double}{PyFloat_AsDouble}{PyObject *pyfloat}
-
 \end{cfuncdesc}
 
-\begin{cfuncdesc}{double}{PyFloat_AS_DOUBLE}{PyFloatObject *}
+\begin{cfuncdesc}{double}{PyFloat_AS_DOUBLE}{PyObject *pyfloat}
-
 \end{cfuncdesc}
 
 
@@ -2137,48 +2130,38 @@ number type.
 Returns true if its argument is a \code{PyComplexObject}.
 \end{cfuncdesc}
 
-\begin{cfuncdesc}{Py_complex}{_Py_c_sum}{Py_complex, Py_complex}
+\begin{cfuncdesc}{Py_complex}{_Py_c_sum}{Py_complex left, Py_complex right}
-
 \end{cfuncdesc}
 
-\begin{cfuncdesc}{Py_complex}{_Py_c_diff}{Py_complex, Py_complex}
+\begin{cfuncdesc}{Py_complex}{_Py_c_diff}{Py_complex left, Py_complex right}
-
 \end{cfuncdesc}
 
-\begin{cfuncdesc}{Py_complex}{_Py_c_neg}{Py_complex}
+\begin{cfuncdesc}{Py_complex}{_Py_c_neg}{Py_complex complex}
-
 \end{cfuncdesc}
 
-\begin{cfuncdesc}{Py_complex}{_Py_c_prod}{Py_complex, Py_complex}
+\begin{cfuncdesc}{Py_complex}{_Py_c_prod}{Py_complex left, Py_complex right}
-
 \end{cfuncdesc}
 
-\begin{cfuncdesc}{Py_complex}{_Py_c_quot}{Py_complex, Py_complex}
+\begin{cfuncdesc}{Py_complex}{_Py_c_quot}{Py_complex dividend,
-
+                                          Py_complex divisor}
 \end{cfuncdesc}
 
-\begin{cfuncdesc}{Py_complex}{_Py_c_pow}{Py_complex, Py_complex}
+\begin{cfuncdesc}{Py_complex}{_Py_c_pow}{Py_complex num, Py_complex exp}
-
 \end{cfuncdesc}
 
-\begin{cfuncdesc}{PyObject *}{PyComplex_FromCComplex}{Py_complex}
+\begin{cfuncdesc}{PyObject*}{PyComplex_FromCComplex}{Py_complex v}
-
 \end{cfuncdesc}
 
 \begin{cfuncdesc}{PyObject*}{PyComplex_FromDoubles}{double real, double imag}
-
 \end{cfuncdesc}
 
 \begin{cfuncdesc}{double}{PyComplex_RealAsDouble}{PyObject *op}
-
 \end{cfuncdesc}
 
 \begin{cfuncdesc}{double}{PyComplex_ImagAsDouble}{PyObject *op}
-
 \end{cfuncdesc}
 
 \begin{cfuncdesc}{Py_complex}{PyComplex_AsCComplex}{PyObject *op}
-
 \end{cfuncdesc}
 
 
@@ -2217,11 +2200,11 @@ closed.
 Returns the file object associated with \var{p} as a \code{FILE *}.
 \end{cfuncdesc}
 
-\begin{cfuncdesc}{PyStringObject *}{PyFile_GetLine}{PyObject *p, int n}
+\begin{cfuncdesc}{PyObject*}{PyFile_GetLine}{PyObject *p, int n}
 undocumented as yet
 \end{cfuncdesc}
 
-\begin{cfuncdesc}{PyStringObject *}{PyFile_Name}{PyObject *p}
+\begin{cfuncdesc}{PyObject*}{PyFile_Name}{PyObject *p}
 Returns the name of the file specified by \var{p} as a 
 \code{PyStringObject}.
 \end{cfuncdesc}
@@ -2233,17 +2216,19 @@ only be called immediately after file object creation.
 
 \begin{cfuncdesc}{int}{PyFile_SoftSpace}{PyFileObject *p, int newflag}
 Sets the \code{softspace} attribute of \var{p} to \var{newflag}.
-Returns the previosu value.  This function clears any errors, and will
+Returns the previous value.  This function clears any errors, and will
 return \code{0} as the previous value if the attribute either does not
 exist or if there were errors in retrieving it.  There is no way to
 detect errors from this function, but doing so should not be needed.
 \end{cfuncdesc}
 
-\begin{cfuncdesc}{int}{PyFile_WriteObject}{PyObject *obj, PyFileObject *p}
+\begin{cfuncdesc}{int}{PyFile_WriteObject}{PyObject *obj, PyFileObject *p,
+                                           int flags}
 Writes object \var{obj} to file object \var{p}.
 \end{cfuncdesc}
 
-\begin{cfuncdesc}{int}{PyFile_WriteString}{char *s, PyFileObject *p}
+\begin{cfuncdesc}{int}{PyFile_WriteString}{char *s, PyFileObject *p,
+                                           int flags}
 Writes string \var{s} to file object \var{p}.
 \end{cfuncdesc}