Revise prologue and frontmatter to use latex2e (not in 2.09 compatibility

mode) and take advantage of changes in myformat.sty.

Change "C" to "\C{}" and "\code{NULL}" to "\NULL{}" everywhere for consistency
and control.

Started a description of PyArg_ParseTupleAndKeywords().

1 files changed, 136 insertions, 132 deletions

diff --git a/Doc/ext.tex b/Doc/ext.tex
index 6626130..f658f72 100644
--- a/Doc/ext.tex
+++ b/Doc/ext.tex
@@ -1,4 +1,5 @@
-\documentstyle[twoside,11pt,myformat]{report}
+\documentclass[twoside]{report}
+\usepackage{myformat}
 
 % XXX PM Modulator
 
@@ -11,6 +12,7 @@
 
 \begin{document}
 
+\pagestyle{empty}
 \pagenumbering{roman}
 
 \maketitle
@@ -21,7 +23,7 @@
 
 \noindent
 Python is an interpreted, object-oriented programming language.  This
-document describes how to write modules in C or \Cpp{} to extend the
+document describes how to write modules in \C{} or \Cpp{} to extend the
 Python interpreter with new modules.  Those modules can define new
 functions but also new object types and their methods.  The document
 also describes how to embed the Python interpreter in another
@@ -37,8 +39,8 @@ Python Library Reference documents the existing object types,
 functions and modules (both built-in and written in Python) that give
 the language its wide application range.
 
-For a detailed description of the whole Python/C API, see the separate
-Python/C API Reference Manual.  \strong{Note:} While that manual is
+For a detailed description of the whole Python/\C{} API, see the separate
+Python/\C{} API Reference Manual.  \strong{Note:} While that manual is
 still in a state of flux, it is safe to say that it is much more up to
 date than the manual you're reading currently (which has been in need
 for an upgrade for some time now).
@@ -46,32 +48,25 @@ for an upgrade for some time now).
 
 \end{abstract}
 
-\pagebreak
-
-{
-\parskip = 0mm
-\tableofcontents
-}
-
-\pagebreak
+\mytableofcontents
 
 \pagenumbering{arabic}
 
 
-\chapter{Extending Python with C or \Cpp{} code}
+\chapter{Extending Python with \C{} or \Cpp{} code}
 
 
 \section{Introduction}
 
 It is quite easy to add new built-in modules to Python, if you know
-how to program in C.  Such \dfn{extension modules} can do two things
+how to program in \C{}.  Such \dfn{extension modules} can do two things
 that can't be done directly in Python: they can implement new built-in
-object types, and they can call C library functions and system calls.
+object types, and they can call \C{} library functions and system calls.
 
 To support extensions, the Python API (Application Programmers
 Interface) defines a set of functions, macros and variables that
 provide access to most aspects of the Python run-time system.  The
-Python API is incorporated in a C source file by including the header
+Python API is incorporated in a \C{} source file by including the header
 \code{"Python.h"}.
 
 The compilation of an extension module depends on its intended use as
@@ -82,7 +77,7 @@ well as on your system setup; details are given in a later section.
 
 Let's create an extension module called \samp{spam} (the favorite food
 of Monty Python fans...) and let's say we want to create a Python
-interface to the C library function \code{system()}.\footnote{An
+interface to the \C{} library function \code{system()}.\footnote{An
 interface for this function already exists in the standard module
 \code{os} --- it was chosen as a simple and straightfoward example.}
 This function takes a null-terminated character string as argument and
@@ -95,7 +90,7 @@ as follows:
 \end{verbatim}\ecode
 %
 Begin by creating a file \samp{spammodule.c}.  (In general, if a
-module is called \samp{spam}, the C file containing its implementation
+module is called \samp{spam}, the \C{} file containing its implementation
 is called \file{spammodule.c}; if the module name is very long, like
 \samp{spammify}, the module name can be just \file{spammify.c}.)
 
@@ -117,7 +112,7 @@ interpreter, \code{"Python.h"} includes a few standard header files:
 system, it declares the functions \code{malloc()}, \code{free()} and
 \code{realloc()} directly.
 
-The next thing we add to our module file is the C function that will
+The next thing we add to our module file is the \C{} function that will
 be called when the Python expression \samp{spam.system(\var{string})}
 is evaluated (we'll see shortly how it ends up being called):
 
@@ -138,23 +133,23 @@ is evaluated (we'll see shortly how it ends up being called):
 %
 There is a straightforward translation from the argument list in
 Python (e.g.\ the single expression \code{"ls -l"}) to the arguments
-passed to the C function.  The C function always has two arguments,
+passed to the \C{} function.  The \C{} function always has two arguments,
 conventionally named \var{self} and \var{args}.
 
-The \var{self} argument is only used when the C function implements a
+The \var{self} argument is only used when the \C{} function implements a
 builtin method.  This will be discussed later. In the example,
-\var{self} will always be a \code{NULL} pointer, since we are defining
+\var{self} will always be a \NULL{} pointer, since we are defining
 a function, not a method.  (This is done so that the interpreter
-doesn't have to understand two different types of C functions.)
+doesn't have to understand two different types of \C{} functions.)
 
 The \var{args} argument will be a pointer to a Python tuple object
 containing the arguments.  Each item of the tuple corresponds to an
 argument in the call's argument list.  The arguments are Python
-objects -- in order to do anything with them in our C function we have
-to convert them to C values.  The function \code{PyArg_ParseTuple()}
-in the Python API checks the argument types and converts them to C
+objects -- in order to do anything with them in our \C{} function we have
+to convert them to \C{} values.  The function \code{PyArg_ParseTuple()}
+in the Python API checks the argument types and converts them to \C{}
 values.  It uses a template string to determine the required types of
-the arguments as well as the types of the C variables into which to
+the arguments as well as the types of the \C{} variables into which to
 store the converted values.  More about this later.
 
 \code{PyArg_ParseTuple()} returns true (nonzero) if all arguments have
@@ -162,20 +157,20 @@ the right type and its components have been stored in the variables
 whose addresses are passed.  It returns false (zero) if an invalid
 argument list was passed.  In the latter case it also raises an
 appropriate exception by so the calling function can return
-\code{NULL} immediately (as we saw in the example).
+\NULL{} immediately (as we saw in the example).
 
 
 \section{Intermezzo: Errors and Exceptions}
 
 An important convention throughout the Python interpreter is the
 following: when a function fails, it should set an exception condition
-and return an error value (usually a \code{NULL} pointer).  Exceptions
+and return an error value (usually a \NULL{} pointer).  Exceptions
 are stored in a static global variable inside the interpreter; if this
-variable is \code{NULL} no exception has occurred.  A second global
+variable is \NULL{} no exception has occurred.  A second global
 variable stores the ``associated value'' of the exception (the second
 argument to \code{raise}).  A third variable contains the stack
 traceback in case the error originated in Python code.  These three
-variables are the C equivalents of the Python variables
+variables are the \C{} equivalents of the Python variables
 \code{sys.exc_type}, \code{sys.exc_value} and \code{sys.exc_traceback}
 (see the section on module \code{sys} in the Library Reference
 Manual).  It is important to know about them to understand how errors
@@ -185,8 +180,8 @@ The Python API defines a number of functions to set various types of
 exceptions.
 
 The most common one is \code{PyErr_SetString()}.  Its arguments are an
-exception object and a C string.  The exception object is usually a
-predefined object like \code{PyExc_ZeroDivisionError}.  The C string
+exception object and a \C{} string.  The exception object is usually a
+predefined object like \code{PyExc_ZeroDivisionError}.  The \C{} string
 indicates the cause of the error and is converted to a Python string
 object and stored as the ``associated value'' of the exception.
 
@@ -199,13 +194,13 @@ arguments, the exception and its associated value.  You don't need to
 
 You can test non-destructively whether an exception has been set with
 \code{PyErr_Occurred()}.  This returns the current exception object,
-or \code{NULL} if no exception has occurred.  You normally don't need
+or \NULL{} if no exception has occurred.  You normally don't need
 to call \code{PyErr_Occurred()} to see whether an error occurred in a
 function call, since you should be able to tell from the return value.
 
 When a function \var{f} that calls another function \var{g} detects
 that the latter fails, \var{f} should itself return an error value
-(e.g. \code{NULL} or \code{-1}).  It should \emph{not} call one of the
+(e.g. \NULL{} or \code{-1}).  It should \emph{not} call one of the
 \code{PyErr_*()} functions --- one has already been called by \var{g}.
 \var{f}'s caller is then supposed to also return an error indication
 to \emph{its} caller, again \emph{without} calling \code{PyErr_*()},
@@ -223,7 +218,7 @@ to be lost: most operations can fail for a variety of reasons.)
 
 To ignore an exception set by a function call that failed, the exception
 condition must be cleared explicitly by calling \code{PyErr_Clear()}. 
-The only time C code should call \code{PyErr_Clear()} is if it doesn't
+The only time \C{} code should call \code{PyErr_Clear()} is if it doesn't
 want to pass the error on to the interpreter but wants to handle it
 completely by itself (e.g. by trying something else or pretending
 nothing happened).
@@ -245,7 +240,7 @@ or \code{Py_DECREF()} calls for objects you have already created) when
 you return an error indicator!
 
 The choice of which exception to raise is entirely yours.  There are
-predeclared C objects corresponding to all built-in Python exceptions,
+predeclared \C{} objects corresponding to all built-in Python exceptions,
 e.g. \code{PyExc_ZeroDevisionError} which you can use directly.  Of
 course, you should choose exceptions wisely --- don't use
 \code{PyExc_TypeError} to mean that a file couldn't be opened (that
@@ -296,12 +291,12 @@ understand this statement:
             return NULL;
 \end{verbatim}\ecode
 %
-It returns \code{NULL} (the error indicator for functions returning
+It returns \NULL{} (the error indicator for functions returning
 object pointers) if an error is detected in the argument list, relying
 on the exception set by \code{PyArg_ParseTuple()}.  Otherwise the
 string value of the argument has been copied to the local variable
 \code{command}.  This is a pointer assignment and you are not supposed
-to modify the string to which it points (so in Standard C, the variable
+to modify the string to which it points (so in Standard \C{}, the variable
 \code{command} should properly be declared as \samp{const char
 *command}).
 
@@ -316,7 +311,7 @@ Our \code{spam.system()} function must return the value of \code{sts}
 as a Python object.  This is done using the function
 \code{Py_BuildValue()}, which is something like the inverse of
 \code{PyArg_ParseTuple()}: it takes a format string and an arbitrary
-number of C values, and returns a new Python object.  More info on
+number of \C{} values, and returns a new Python object.  More info on
 \code{Py_BuildValue()} is given later.
 
 \bcode\begin{verbatim}
@@ -326,7 +321,7 @@ number of C values, and returns a new Python object.  More info on
 In this case, it will return an integer object.  (Yes, even integers
 are objects on the heap in Python!)
 
-If you have a C function that returns no useful argument (a function
+If you have a \C{} function that returns no useful argument (a function
 returning \code{void}), the corresponding Python function must return
 \code{None}.   You need this idiom to do so:
 
@@ -335,8 +330,8 @@ returning \code{void}), the corresponding Python function must return
         return Py_None;
 \end{verbatim}\ecode
 %
-\code{Py_None} is the C name for the special Python object
-\code{None}.  It is a genuine Python object (not a \code{NULL}
+\code{Py_None} is the \C{} name for the special Python object
+\code{None}.  It is a genuine Python object (not a \NULL{}
 pointer, which means ``error'' in most contexts, as we have seen).
 
 
@@ -349,17 +344,26 @@ table'':
 \bcode\begin{verbatim}
     static PyMethodDef SpamMethods[] = {
         ...
-        {"system",  spam_system, 1},
+        {"system",  spam_system, METH_VARARGS},
         ...
         {NULL,      NULL}        /* Sentinel */
     };
 \end{verbatim}\ecode
 %
-Note the third entry (\samp{1}).  This is a flag telling the
-interpreter the calling convention to be used for the C function.  It
-should normally always be \samp{1}; a value of \samp{0} means that an
+Note the third entry (\samp{METH_VARARGS}).  This is a flag telling
+the interpreter the calling convention to be used for the \C{}
+function.  It should normally always be \samp{METH_VARARGS} or
+\samp{METH_VARARGS | METH_KEYWORDS}; a value of \samp{0} means that an
 obsolete variant of \code{PyArg_ParseTuple()} is used.
 
+The \code{METH_KEYWORDS} bit may be set in the third field if keyword
+arguments should be passed to the function.  In this case, the \C{}
+function should accept a third \samp{PyObject *} parameter which will
+be a dictionary of keywords.  Use \code{PyArg_ParseTupleAndKeywords()} 
+to parse the arguemts to such a function.
+
+XXX --- need to explain PyArg_ParseTupleAndKeywords() in detail.
+
 The method table must be passed to the interpreter in the module's
 initialization function (which should be the only non-\code{static}
 item defined in the module file):
@@ -416,15 +420,15 @@ be listed on the line in the \file{Setup} file as well, for instance:
     spam spammodule.o -lX11
 \end{verbatim}\ecode
 %
-\section{Calling Python Functions From C}
+\section{Calling Python Functions From \C{}}
 
-So far we have concentrated on making C functions callable from
-Python.  The reverse is also useful: calling Python functions from C.
+So far we have concentrated on making \C{} functions callable from
+Python.  The reverse is also useful: calling Python functions from \C{}.
 This is especially the case for libraries that support so-called
-``callback'' functions.  If a C interface makes use of callbacks, the
+``callback'' functions.  If a \C{} interface makes use of callbacks, the
 equivalent Python often needs to provide a callback mechanism to the
 Python programmer; the implementation will require calling the Python
-callback functions from a C callback.  Other uses are also imaginable.
+callback functions from a \C{} callback.  Other uses are also imaginable.
 
 Fortunately, the Python interpreter is easily called recursively, and
 there is a standard interface to call a Python function.  (I won't
@@ -458,10 +462,10 @@ definition:
 %
 The macros \code{Py_XINCREF()} and \code{Py_XDECREF()} increment/decrement
 the reference count of an object and are safe in the presence of
-\code{NULL} pointers.  More info on them in the section on Reference
+\NULL{} pointers.  More info on them in the section on Reference
 Counts below.
 
-Later, when it is time to call the function, you call the C function
+Later, when it is time to call the function, you call the \C{} function
 \code{PyEval_CallObject()}.  This function has two arguments, both
 pointers to arbitrary Python objects: the Python function, and the
 argument list.  The argument list must always be a tuple object, whose
@@ -497,8 +501,8 @@ global variable, you should somehow \code{Py_DECREF()} the result,
 even (especially!) if you are not interested in its value.
 
 Before you do this, however, it is important to check that the return
-value isn't \code{NULL}.  If it is, the Python function terminated by raising
-an exception.  If the C code that called \code{PyEval_CallObject()} is
+value isn't \NULL{}.  If it is, the Python function terminated by raising
+an exception.  If the \C{} code that called \code{PyEval_CallObject()} is
 called from Python, it should now return an error indication to its
 Python caller, so the interpreter can print a stack trace, or the
 calling Python code can handle the exception.  If this is not possible
@@ -549,7 +553,7 @@ The \code{PyArg_ParseTuple()} function is declared as follows:
 \end{verbatim}\ecode
 %
 The \var{arg} argument must be a tuple object containing an argument
-list passed from Python to a C function.  The \var{format} argument
+list passed from Python to a \C{} function.  The \var{format} argument
 must be a format string, whose syntax is explained below.  The
 remaining arguments must be addresses of variables whose type is
 determined by the format string.  For the conversion to succeed, the
@@ -558,7 +562,7 @@ exhausted.
 
 Note that while \code{PyArg_ParseTuple()} checks that the Python
 arguments have the required types, it cannot check the validity of the
-addresses of C variables passed to the call: if you make mistakes
+addresses of \C{} variables passed to the call: if you make mistakes
 there, your code will probably crash or at least overwrite random bits
 in memory.  So be careful!
 
@@ -569,72 +573,72 @@ format unit that is not a parenthesized sequence normally corresponds
 to a single address argument to \code{PyArg_ParseTuple()}.  In the
 following description, the quoted form is the format unit; the entry
 in (round) parentheses is the Python object type that matches the
-format unit; and the entry in [square] brackets is the type of the C
+format unit; and the entry in [square] brackets is the type of the \C{}
 variable(s) whose address should be passed.  (Use the \samp{\&}
 operator to pass a variable's address.)
 
 \begin{description}
 
 \item[\samp{s} (string) [char *]]
-Convert a Python string to a C pointer to a character string.  You
+Convert a Python string to a \C{} pointer to a character string.  You
 must not provide storage for the string itself; a pointer to an
 existing string is stored into the character pointer variable whose
-address you pass.  The C string is null-terminated.  The Python string
+address you pass.  The \C{} string is null-terminated.  The Python string
 must not contain embedded null bytes; if it does, a \code{TypeError}
 exception is raised.
 
 \item[\samp{s\#} (string) {[char *, int]}]
-This variant on \code{'s'} stores into two C variables, the first one
+This variant on \code{'s'} stores into two \C{} variables, the first one
 a pointer to a character string, the second one its length.  In this
 case the Python string may contain embedded null bytes.
 
 \item[\samp{z} (string or \code{None}) {[char *]}]
 Like \samp{s}, but the Python object may also be \code{None}, in which
-case the C pointer is set to \code{NULL}.
+case the \C{} pointer is set to \NULL{}.
 
 \item[\samp{z\#} (string or \code{None}) {[char *, int]}]
 This is to \code{'s\#'} as \code{'z'} is to \code{'s'}.
 
 \item[\samp{b} (integer) {[char]}]
-Convert a Python integer to a tiny int, stored in a C \code{char}.
+Convert a Python integer to a tiny int, stored in a \C{} \code{char}.
 
 \item[\samp{h} (integer) {[short int]}]
-Convert a Python integer to a C \code{short int}.
+Convert a Python integer to a \C{} \code{short int}.
 
 \item[\samp{i} (integer) {[int]}]
-Convert a Python integer to a plain C \code{int}.
+Convert a Python integer to a plain \C{} \code{int}.
 
 \item[\samp{l} (integer) {[long int]}]
-Convert a Python integer to a C \code{long int}.
+Convert a Python integer to a \C{} \code{long int}.
 
 \item[\samp{c} (string of length 1) {[char]}]
 Convert a Python character, represented as a string of length 1, to a
-C \code{char}.
+\C{} \code{char}.
 
 \item[\samp{f} (float) {[float]}]
-Convert a Python floating point number to a C \code{float}.
+Convert a Python floating point number to a \C{} \code{float}.
 
 \item[\samp{d} (float) {[double]}]
-Convert a Python floating point number to a C \code{double}.
+Convert a Python floating point number to a \C{} \code{double}.
 
 \item[\samp{O} (object) {[PyObject *]}]
-Store a Python object (without any conversion) in a C object pointer.
-The C program thus receives the actual object that was passed.  The
+Store a Python object (without any conversion) in a \C{} object pointer.
+The \C{} program thus receives the actual object that was passed.  The
 object's reference count is not increased.  The pointer stored is not
-\code{NULL}.
+\NULL{}.
 
 \item[\samp{O!} (object) {[\var{typeobject}, PyObject *]}]
-Store a Python object in a C object pointer.  This is similar to
-\samp{O}, but takes two C arguments: the first is the address of a
-Python type object, the second is the address of the C variable (of
+Store a Python object in a \C{} object pointer.  This is similar to
+\samp{O}, but takes two \C{} arguments: the first is the address of a
+Python type object, the second is the address of the \C{} variable (of
 type \code{PyObject *}) into which the object pointer is stored.
 If the Python object does not have the required type, a
 \code{TypeError} exception is raised.
 
 \item[\samp{O\&} (object) {[\var{converter}, \var{anything}]}]
-Convert a Python object to a C variable through a \var{converter}
+Convert a Python object to a \C{} variable through a \var{converter}
 function.  This takes two arguments: the first is a function, the
-second is the address of a C variable (of arbitrary type), converted
+second is the address of a \C{} variable (of arbitrary type), converted
 to \code{void *}.  The \var{converter} function in turn is called as
 follows:
 
@@ -649,12 +653,12 @@ should raise an exception.
 
 \item[\samp{S} (string) {[PyStringObject *]}]
 Like \samp{O} but raises a \code{TypeError} exception that the object
-is a string object.  The C variable may also be declared as
+is a string object.  The \C{} variable may also be declared as
 \code{PyObject *}.
 
 \item[\samp{(\var{items})} (tuple) {[\var{matching-items}]}]
 The object must be a Python tuple whose length is the number of format
-units in \var{items}.  The C arguments must correspond to the
+units in \var{items}.  The \C{} arguments must correspond to the
 individual format units in \var{items}.  Format units for tuples may
 be nested.
 
@@ -664,7 +668,7 @@ It is possible to pass Python long integers where integers are
 requested; however no proper range checking is done -- the most
 significant bits are silently truncated when the receiving field is
 too small to receive the value (actually, the semantics are inherited
-from downcasts in C --- your milage may vary).
+from downcasts in \C{} --- your milage may vary).
 
 A few other characters have a meaning in a format string.  These may
 not occur inside nested parentheses.  They are:
@@ -673,10 +677,10 @@ not occur inside nested parentheses.  They are:
 
 \item[\samp{|}]
 Indicates that the remaining arguments in the Python argument list are
-optional.  The C variables corresponding to optional arguments should
+optional.  The \C{} variables corresponding to optional arguments should
 be initialized to their default value --- when an optional argument is
 not specified, the \code{PyArg_ParseTuple} does not touch the contents
-of the corresponding C variable(s).
+of the corresponding \C{} variable(s).
 
 \item[\samp{:}]
 The list of format units ends here; the string after the colon is used
@@ -692,7 +696,7 @@ Clearly, \samp{:} and \samp{;} mutually exclude each other.
 
 Some example calls:
 
-\bcode\begin{verbatim}
+\begin{verbatim}
     int ok;
     int i, j;
     long k, l;
@@ -701,13 +705,13 @@ Some example calls:
 
     ok = PyArg_ParseTuple(args, ""); /* No arguments */
         /* Python call: f() */
-    
+
     ok = PyArg_ParseTuple(args, "s", &s); /* A string */
         /* Possible Python call: f('whoops!') */
 
     ok = PyArg_ParseTuple(args, "lls", &k, &l, &s); /* Two longs and a string */
         /* Possible Python call: f(1, 2, 'three') */
-    
+
     ok = PyArg_ParseTuple(args, "(ii)s#", &i, &j, &s, &size);
         /* A pair of ints and a string, whose size is also returned */
         /* Possible Python call: f((1, 2), 'three') */
@@ -732,7 +736,7 @@ Some example calls:
                  /* Possible Python call:
                     f(((0, 0), (400, 300)), (10, 10)) */
     }
-\end{verbatim}\ecode
+\end{verbatim}
 %
 \section{The {\tt Py_BuildValue()} Function}
 
@@ -746,7 +750,7 @@ declared as follows:
 It recognizes a set of format units similar to the ones recognized by
 \code{PyArg_ParseTuple()}, but the arguments (which are input to the
 function, not output) must not be pointers, just values.  It returns a
-new Python object, suitable for returning from a C function called
+new Python object, suitable for returning from a \C{} function called
 from Python.
 
 One difference with \code{PyArg_ParseTuple()}: while the latter
@@ -761,7 +765,7 @@ to return a tuple of size 0 or one, parenthesize the format string.
 In the following description, the quoted form is the format unit; the
 entry in (round) parentheses is the Python object type that the format
 unit will return; and the entry in [square] brackets is the type of
-the C value(s) to be passed.
+the \C{} value(s) to be passed.
 
 The characters space, tab, colon and comma are ignored in format
 strings (but not within format units such as \samp{s\#}).  This can be
@@ -770,12 +774,12 @@ used to make long format strings a tad more readable.
 \begin{description}
 
 \item[\samp{s} (string) {[char *]}]
-Convert a null-terminated C string to a Python object.  If the C
-string pointer is \code{NULL}, \code{None} is returned.
+Convert a null-terminated \C{} string to a Python object.  If the \C{}
+string pointer is \NULL{}, \code{None} is returned.
 
 \item[\samp{s\#} (string) {[char *, int]}]
-Convert a C string and its length to a Python object.  If the C string
-pointer is \code{NULL}, the length is ignored and \code{None} is
+Convert a \C{} string and its length to a Python object.  If the \C{} string
+pointer is \NULL{}, the length is ignored and \code{None} is
 returned.
 
 \item[\samp{z} (string or \code{None}) {[char *]}]
@@ -785,7 +789,7 @@ Same as \samp{s}.
 Same as \samp{s\#}.
 
 \item[\samp{i} (integer) {[int]}]
-Convert a plain C \code{int} to a Python integer object.
+Convert a plain \C{} \code{int} to a Python integer object.
 
 \item[\samp{b} (integer) {[char]}]
 Same as \samp{i}.
@@ -794,24 +798,24 @@ Same as \samp{i}.
 Same as \samp{i}.
 
 \item[\samp{l} (integer) {[long int]}]
-Convert a C \code{long int} to a Python integer object.
+Convert a \C{} \code{long int} to a Python integer object.
 
 \item[\samp{c} (string of length 1) {[char]}]
-Convert a C \code{int} representing a character to a Python string of
+Convert a \C{} \code{int} representing a character to a Python string of
 length 1.
 
 \item[\samp{d} (float) {[double]}]
-Convert a C \code{double} to a Python floating point number.
+Convert a \C{} \code{double} to a Python floating point number.
 
 \item[\samp{f} (float) {[float]}]
 Same as \samp{d}.
 
 \item[\samp{O} (object) {[PyObject *]}]
 Pass a Python object untouched (except for its reference count, which
-is incremented by one).  If the object passed in is a \code{NULL}
+is incremented by one).  If the object passed in is a \NULL{}
 pointer, it is assumed that this was caused because the call producing
 the argument found an error and set an exception.  Therefore,
-\code{Py_BuildValue()} will return \code{NULL} but won't raise an
+\code{Py_BuildValue()} will return \NULL{} but won't raise an
 exception.  If no exception has been raised yet,
 \code{PyExc_SystemError} is set.
 
@@ -822,25 +826,25 @@ Same as \samp{O}.
 Convert \var{anything} to a Python object through a \var{converter}
 function.  The function is called with \var{anything} (which should be
 compatible with \code{void *}) as its argument and should return a
-``new'' Python object, or \code{NULL} if an error occurred.
+``new'' Python object, or \NULL{} if an error occurred.
 
 \item[\samp{(\var{items})} (tuple) {[\var{matching-items}]}]
-Convert a sequence of C values to a Python tuple with the same number
+Convert a sequence of \C{} values to a Python tuple with the same number
 of items.
 
 \item[\samp{[\var{items}]} (list) {[\var{matching-items}]}]
-Convert a sequence of C values to a Python list with the same number
+Convert a sequence of \C{} values to a Python list with the same number
 of items.
 
 \item[\samp{\{\var{items}\}} (dictionary) {[\var{matching-items}]}]
-Convert a sequence of C values to a Python dictionary.  Each pair of
-consecutive C values adds one item to the dictionary, serving as key
+Convert a sequence of \C{} values to a Python dictionary.  Each pair of
+consecutive \C{} values adds one item to the dictionary, serving as key
 and value, respectively.
 
 \end{description}
 
 If there is an error in the format string, the
-\code{PyExc_SystemError} exception is raised and \code{NULL} returned.
+\code{PyExc_SystemError} exception is raised and \NULL{} returned.
 
 Examples (to the left the call, to the right the resulting Python value):
 
@@ -866,8 +870,8 @@ Examples (to the left the call, to the right the resulting Python value):
 
 \subsection{Introduction}
 
-In languages like C or \Cpp{}, the programmer is responsible for
-dynamic allocation and deallocation of memory on the heap.  In C, this
+In languages like \C{} or \Cpp{}, the programmer is responsible for
+dynamic allocation and deallocation of memory on the heap.  In \C{}, this
 is done using the functions \code{malloc()} and \code{free()}.  In
 \Cpp{}, the operators \code{new} and \code{delete} are used with
 essentially the same meaning; they are actually implemented using
@@ -916,12 +920,12 @@ collection strategy, hence my use of ``automatic'' to distinguish the
 two.)  The big advantage of automatic garbage collection is that the
 user doesn't need to call \code{free()} explicitly.  (Another claimed
 advantage is an improvement in speed or memory usage --- this is no
-hard fact however.)  The disadvantage is that for C, there is no
+hard fact however.)  The disadvantage is that for \C{}, there is no
 truly portable automatic garbage collector, while reference counting
 can be implemented portably (as long as the functions \code{malloc()}
-and \code{free()} are available --- which the C Standard guarantees).
+and \code{free()} are available --- which the \C{} Standard guarantees).
 Maybe some day a sufficiently portable automatic garbage collector
-will be available for C.  Until then, we'll have to live with
+will be available for \C{}.  Until then, we'll have to live with
 reference counts.
 
 \subsection{Reference Counting in Python}
@@ -1008,14 +1012,14 @@ take over ownership of the item passed to them --- even if they fail!
 (Note that \code{PyDict_SetItem()} and friends don't take over
 ownership --- they are ``normal''.)
 
-When a C function is called from Python, it borrows references to its
+When a \C{} function is called from Python, it borrows references to its
 arguments from the caller.  The caller owns a reference to the object,
 so the borrowed reference's lifetime is guaranteed until the function
 returns.  Only when such a borrowed reference must be stored or passed
 on, it must be turned into an owned reference by calling
 \code{Py_INCREF()}.
 
-The object reference returned from a C function that is called from
+The object reference returned from a \C{} function that is called from
 Python must be an owned reference --- ownership is tranferred from the
 function to its caller.
 
@@ -1074,7 +1078,7 @@ no_bug(PyObject *list) {
 \end{verbatim}\ecode
 %
 This is a true story.  An older version of Python contained variants
-of this bug and someone spent a considerable amount of time in a C
+of this bug and someone spent a considerable amount of time in a \C{}
 debugger to figure out why his \code{__del__()} methods would fail...
 
 The second case of problems with a borrowed reference is a variant
@@ -1101,36 +1105,36 @@ bug(PyObject *list) {
 \subsection{NULL Pointers}
 
 In general, functions that take object references as arguments don't
-expect you to pass them \code{NULL} pointers, and will dump core (or
+expect you to pass them \NULL{} pointers, and will dump core (or
 cause later core dumps) if you do so.  Functions that return object
-references generally return \code{NULL} only to indicate that an
-exception occurred.  The reason for not testing for \code{NULL}
+references generally return \NULL{} only to indicate that an
+exception occurred.  The reason for not testing for \NULL{}
 arguments is that functions often pass the objects they receive on to
-other function --- if each function were to test for \code{NULL},
+other function --- if each function were to test for \NULL{},
 there would be a lot of redundant tests and the code would run slower.
 
-It is better to test for \code{NULL} only at the ``source'', i.e.\
-when a pointer that may be \code{NULL} is received, e.g.\ from
+It is better to test for \NULL{} only at the ``source'', i.e.\
+when a pointer that may be \NULL{} is received, e.g.\ from
 \code{malloc()} or from a function that may raise an exception.
 
 The macros \code{Py_INCREF()} and \code{Py_DECREF()}
-don't check for \code{NULL} pointers --- however, their variants
+don't check for \NULL{} pointers --- however, their variants
 \code{Py_XINCREF()} and \code{Py_XDECREF()} do.
 
 The macros for checking for a particular object type
-(\code{Py\var{type}_Check()}) don't check for \code{NULL} pointers ---
+(\code{Py\var{type}_Check()}) don't check for \NULL{} pointers ---
 again, there is much code that calls several of these in a row to test
 an object against various different expected types, and this would
-generate redundant tests.  There are no variants with \code{NULL}
+generate redundant tests.  There are no variants with \NULL{}
 checking.
 
-The C function calling mechanism guarantees that the argument list
-passed to C functions (\code{args} in the examples) is never
-\code{NULL} --- in fact it guarantees that it is always a tuple.%
+The \C{} function calling mechanism guarantees that the argument list
+passed to \C{} functions (\code{args} in the examples) is never
+\NULL{} --- in fact it guarantees that it is always a tuple.%
 \footnote{These guarantees don't hold when you use the ``old'' style
 calling convention --- this is still found in much existing code.}
 
-It is a severe error to ever let a \code{NULL} pointer ``escape'' to
+It is a severe error to ever let a \NULL{} pointer ``escape'' to
 the Python user.  
 
 
@@ -1138,7 +1142,7 @@ the Python user.
 
 It is possible to write extension modules in \Cpp{}.  Some restrictions
 apply.  If the main program (the Python interpreter) is compiled and
-linked by the C compiler, global or static objects with constructors
+linked by the \C{} compiler, global or static objects with constructors
 cannot be used.  This is not a problem if the main program is linked
 by the \Cpp{} compiler.  All functions that will be called directly or
 indirectly (i.e. via function pointers) by the Python interpreter will
@@ -1146,7 +1150,7 @@ have to be declared using \code{extern "C"}; this applies to all
 ``methods'' as well as to the module's initialization function.
 It is unnecessary to enclose the Python header files in
 \code{extern "C" \{...\}} --- they use this form already if the symbol
-\samp{__cplusplus} is defined (all recent C++ compilers define this
+\samp{__cplusplus} is defined (all recent \Cpp{} compilers define this
 symbol).
 
 \chapter{Embedding Python in another application}
@@ -1188,7 +1192,7 @@ itself using \Cpp{}.
 \chapter{Dynamic Loading}
 
 On most modern systems it is possible to configure Python to support
-dynamic loading of extension modules implemented in C.  When shared
+dynamic loading of extension modules implemented in \C{}.  When shared
 libraries are used dynamic loading is configured automatically;
 otherwise you have to select it as a build option (see below).  Once
 configured, dynamic loading is trivial to use: when a Python program
@@ -1200,7 +1204,7 @@ module acts just like a built-in extension module.
 
 The advantages of dynamic loading are twofold: the ``core'' Python
 binary gets smaller, and users can extend Python with their own
-modules implemented in C without having to build and maintain their
+modules implemented in \C{} without having to build and maintain their
 own copy of the Python interpreter.  There are also disadvantages:
 dynamic loading isn't available on all systems (this just means that
 on some systems you have to use static loading), and dynamically
@@ -1289,7 +1293,7 @@ described earlier).
 
 Note that in all cases you will have to create your own Makefile that
 compiles your module file(s).  This Makefile will have to pass two
-\samp{-I} arguments to the C compiler which will make it find the
+\samp{-I} arguments to the \C{} compiler which will make it find the
 Python header files.  If the Make variable \var{PYTHONTOP} points to
 the toplevel Python directory, your \var{CFLAGS} Make variable should
 contain the options \samp{-I\$(PYTHONTOP) -I\$(PYTHONTOP)/Include}.
@@ -1333,7 +1337,7 @@ along the Python module search path.
 \subsection{SGI IRIX 4 Dynamic Loading}
 
 {\bf IMPORTANT:} You must compile your extension module with the
-additional C flag \samp{-G0} (or \samp{-G 0}).  This instruct the
+additional \C{} flag \samp{-G0} (or \samp{-G 0}).  This instruct the
 assembler to generate position-independent code.
 
 You don't need to link the resulting \file{spammodule.o} file; just