--- rest25/extending/extending.rst	2008-12-19 16:58:05.000000000 +0900
+++ rest262/extending/extending.rst	2009-04-07 00:06:52.000000000 +0900
@@ -1,36 +1,36 @@
 .. highlightlang:: c
 
 
-.. _intro:
+.. _extending-intro:
 
 ******************************
 Extending Python with C or C++
 ******************************
 
 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 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.
 
 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.h"``.
 
 The compilation of an extension module depends on its intended use as well as on
 your system setup; details are given in later chapters.
 
 
-.. _simpleexample:
+.. _extending-simpleexample:
 
 A Simple Example
 ================
 
 Let's create an extension module called ``spam`` (the favorite food of Monty
 Python fans...) and let's say we want to create a Python interface to the C
 library function :cfunc:`system`. [#]_ This function takes a null-terminated
 character string as argument and returns an integer.  We want this function to
 be callable from Python as follows::
 
    >>> import spam
    >>> status = spam.system("ls -l")
@@ -94,40 +94,40 @@
 :cfunc:`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
 store the converted values.  More about this later.
 
 :cfunc:`PyArg_ParseTuple` returns true (nonzero) if all arguments have 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 so the calling function can
 return *NULL* immediately (as we saw in the example).
 
 
-.. _errors:
+.. _extending-errors:
 
 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 *NULL* pointer).  Exceptions are stored in a static global variable
 inside the interpreter; if this variable is *NULL* no exception has occurred.  A
 second global variable stores the "associated value" of the exception (the
 second argument to :keyword:`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 ``sys.exc_type``,
 ``sys.exc_value`` and ``sys.exc_traceback`` (see the section on module
-:mod:`sys` in the Python Library Reference (XXX reference: ../lib/lib.html)).
-It is important to know about them to understand how errors are passed around.
+:mod:`sys` in the Python Library Reference).  It is important to know about them
+to understand how errors are passed around.
 
 The Python API defines a number of functions to set various types of exceptions.
 
 The most common one is :cfunc:`PyErr_SetString`.  Its arguments are an exception
 object and a C string.  The exception object is usually a predefined object like
 :cdata:`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.
 
 Another useful function is :cfunc:`PyErr_SetFromErrno`, which only takes an
 exception argument and constructs the associated value by inspection of the
 global variable :cdata:`errno`.  The most general function is
@@ -156,27 +156,27 @@
 fine to do so.  As a general rule, however, this is not necessary, and can cause
 information about the cause of the error 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 :cfunc:`PyErr_Clear`.  The only
 time C code should call :cfunc:`PyErr_Clear` is if it doesn't want to pass the
 error on to the interpreter but wants to handle it completely by itself
 (possibly by trying something else, or pretending nothing went wrong).
 
 Every failing :cfunc:`malloc` call must be turned into an exception --- the
 direct caller of :cfunc:`malloc` (or :cfunc:`realloc`) must call
-:cfunc:`PyErr_NoMemory` and return a failure indicator itself.  All the object-
-creating functions (for example, :cfunc:`PyInt_FromLong`) already do this, so
-this note is only relevant to those who call :cfunc:`malloc` directly.
+:cfunc:`PyErr_NoMemory` and return a failure indicator itself.  All the
+object-creating functions (for example, :cfunc:`PyInt_FromLong`) already do
+this, so this note is only relevant to those who call :cfunc:`malloc` directly.
 
 Also note that, with the important exception of :cfunc:`PyArg_ParseTuple` and
 friends, functions that return an integer status usually return a positive value
 or zero for success and ``-1`` for failure, like Unix system calls.
 
 Finally, be careful to clean up garbage (by making :cfunc:`Py_XDECREF` or
 :cfunc:`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, such as
 :cdata:`PyExc_ZeroDivisionError`, which you can use directly. Of course, you
@@ -192,35 +192,36 @@
 
    static PyObject *SpamError;
 
 and initialize it in your module's initialization function (:cfunc:`initspam`)
 with an exception object (leaving out the error checking for now)::
 
    PyMODINIT_FUNC
    initspam(void)
    {
        PyObject *m;
 
        m = Py_InitModule("spam", SpamMethods);
+       if (m == NULL)
+           return;
 
        SpamError = PyErr_NewException("spam.error", NULL, NULL);
        Py_INCREF(SpamError);
        PyModule_AddObject(m, "error", SpamError);
    }
 
 Note that the Python name for the exception object is :exc:`spam.error`.  The
 :cfunc:`PyErr_NewException` function may create a class with the base class
 being :exc:`Exception` (unless another class is passed in instead of *NULL*),
-described in the Python Library Reference (XXX reference: ../lib/lib.html) under
-"Built-in Exceptions."
+described in :ref:`bltin-exceptions`.
 
 Note also that the :cdata:`SpamError` variable retains a reference to the newly
 created exception class; this is intentional!  Since the exception could be
 removed from the module by external code, an owned reference to the class is
 needed to ensure that it will not be discarded, causing :cdata:`SpamError` to
 become a dangling pointer. Should it become a dangling pointer, C code which
 raises the exception could cause a core dump or other unintended side effects.
 
 We discuss the use of PyMODINIT_FUNC as a function return type later in this
 sample.
 
 
@@ -297,52 +298,52 @@
 parameters to be passed in as a tuple acceptable for parsing via
 :cfunc:`PyArg_ParseTuple`; more information on this function is provided below.
 
 The :const:`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 ``PyObject *`` parameter which will be a dictionary of keywords.
 Use :cfunc:`PyArg_ParseTupleAndKeywords` to parse the arguments to such a
 function.
 
 The method table must be passed to the interpreter in the module's
 initialization function.  The initialization function must be named
 :cfunc:`initname`, where *name* is the name of the module, and should be the
-only non-\ :keyword:`static` item defined in the module file::
+only non-\ ``static`` item defined in the module file::
 
    PyMODINIT_FUNC
    initspam(void)
    {
        (void) Py_InitModule("spam", SpamMethods);
    }
 
 Note that PyMODINIT_FUNC declares the function as ``void`` return type,
 declares any special linkage declarations required by the platform, and for  C++
 declares the function as ``extern "C"``.
 
 When the Python program imports module :mod:`spam` for the first time,
 :cfunc:`initspam` is called. (See below for comments about embedding Python.)
 It calls :cfunc:`Py_InitModule`, which creates a "module object" (which is
 inserted in the dictionary ``sys.modules`` under the key ``"spam"``), and
 inserts built-in function objects into the newly created module based upon the
 table (an array of :ctype:`PyMethodDef` structures) that was passed as its
 second argument. :cfunc:`Py_InitModule` returns a pointer to the module object
-that it creates (which is unused here).  It aborts with a fatal error if the
-module could not be initialized satisfactorily, so the caller doesn't need to
-check for errors.
+that it creates (which is unused here).  It may abort with a fatal error for
+certain errors, or return *NULL* if the module could not be initialized
+satisfactorily.
 
 When embedding Python, the :cfunc:`initspam` function is not called
 automatically unless there's an entry in the :cdata:`_PyImport_Inittab` table.
-The easiest way to handle this is to  statically initialize your statically-
+The easiest way to handle this is to statically initialize your
-linked modules by directly calling :cfunc:`initspam` after the call to
+statically-linked modules by directly calling :cfunc:`initspam` after the call
-:cfunc:`Py_Initialize`::
+to :cfunc:`Py_Initialize`::
 
    int
    main(int argc, char *argv[])
    {
        /* Pass argv[0] to the Python interpreter */
        Py_SetProgramName(argv[0]);
 
        /* Initialize the Python interpreter.  Required. */
        Py_Initialize();
 
        /* Add a static module */
        initspam();
@@ -413,25 +414,25 @@
 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 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.
 
 Fortunately, the Python interpreter is easily called recursively, and there is a
 standard interface to call a Python function.  (I won't dwell on how to call the
 Python parser with a particular string as input --- if you're interested, have a
 look at the implementation of the :option:`-c` command line option in
-:file:`Python/pythonmain.c` from the Python source code.)
+:file:`Modules/main.c` from the Python source code.)
 
 Calling a Python function is easy.  First, the Python program must somehow pass
 you the Python function object.  You should provide a function (or some other
 interface) to do this.  When this function is called, save a pointer to the
 Python function object (be careful to :cfunc:`Py_INCREF` it!) in a global
 variable --- or wherever you see fit. For example, the following function might
 be part of a module definition::
 
    static PyObject *my_callback = NULL;
 
    static PyObject *
    my_set_callback(PyObject *dummy, PyObject *args)
@@ -446,122 +447,134 @@
            }
            Py_XINCREF(temp);         /* Add a reference to new callback */
            Py_XDECREF(my_callback);  /* Dispose of previous callback */
            my_callback = temp;       /* Remember new callback */
            /* Boilerplate to return "None" */
            Py_INCREF(Py_None);
            result = Py_None;
        }
        return result;
    }
 
 This function must be registered with the interpreter using the
-:const:`METH_VARARGS` flag; this is described in section :ref:`methodtable`,
-"The Module's Method Table and Initialization Function."  The
+:const:`METH_VARARGS` flag; this is described in section :ref:`methodtable`.  The
 :cfunc:`PyArg_ParseTuple` function and its arguments are documented in section
-:ref:`parsetuple`, "Extracting Parameters in Extension Functions."
+:ref:`parsetuple`.
 
 The macros :cfunc:`Py_XINCREF` and :cfunc:`Py_XDECREF` increment/decrement the
 reference count of an object and are safe in the presence of *NULL* pointers
 (but note that *temp* will not be  *NULL* in this context).  More info on them
-in section :ref:`refcounts`, "Reference Counts."
+in section :ref:`refcounts`.
 
-.. index:: single: PyEval_CallObject()
+.. index:: single: PyObject_CallObject()
 
 Later, when it is time to call the function, you call the C function
-:cfunc:`PyEval_CallObject`.  This function has two arguments, both pointers to
+:cfunc:`PyObject_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 length is the number of
-arguments.  To call the Python function with no arguments, pass an empty tuple;
-to call it with one argument, pass a singleton tuple. :cfunc:`Py_BuildValue`
-returns a tuple when its format string consists of zero or more format codes
-between parentheses.  For example::
+arguments.  To call the Python function with no arguments, pass in NULL, or
+an empty tuple; to call it with one argument, pass a singleton tuple.
+:cfunc:`Py_BuildValue` returns a tuple when its format string consists of zero
+or more format codes between parentheses.  For example::
 
    int arg;
    PyObject *arglist;
    PyObject *result;
    ...
    arg = 123;
    ...
    /* Time to call the callback */
    arglist = Py_BuildValue("(i)", arg);
-   result = PyEval_CallObject(my_callback, arglist);
+   result = PyObject_CallObject(my_callback, arglist);
    Py_DECREF(arglist);
 
-:cfunc:`PyEval_CallObject` returns a Python object pointer: this is the return
-value of the Python function.  :cfunc:`PyEval_CallObject` is "reference-count-
-neutral" with respect to its arguments.  In the example a new tuple was created
-to serve as the argument list, which is :cfunc:`Py_DECREF`\ -ed immediately
-after the call.
+:cfunc:`PyObject_CallObject` returns a Python object pointer: this is the return
+value of the Python function.  :cfunc:`PyObject_CallObject` is
+"reference-count-neutral" with respect to its arguments.  In the example a new
+tuple was created to serve as the argument list, which is :cfunc:`Py_DECREF`\
+-ed immediately after the call.
 
-The return value of :cfunc:`PyEval_CallObject` is "new": either it is a brand
+The return value of :cfunc:`PyObject_CallObject` is "new": either it is a brand
 new object, or it is an existing object whose reference count has been
 incremented.  So, unless you want to save it in a global variable, you should
 somehow :cfunc:`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 *NULL*.  If it is, the Python function terminated by raising an exception.
-If the C code that called :cfunc:`PyEval_CallObject` is called from Python, it
+If the C code that called :cfunc:`PyObject_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 or desirable, the exception should be cleared by calling
 :cfunc:`PyErr_Clear`.  For example::
 
    if (result == NULL)
        return NULL; /* Pass error back */
    ...use result...
-   Py_DECREF(result); 
+   Py_DECREF(result);
 
 Depending on the desired interface to the Python callback function, you may also
-have to provide an argument list to :cfunc:`PyEval_CallObject`.  In some cases
+have to provide an argument list to :cfunc:`PyObject_CallObject`.  In some cases
 the argument list is also provided by the Python program, through the same
 interface that specified the callback function.  It can then be saved and used
 in the same manner as the function object.  In other cases, you may have to
 construct a new tuple to pass as the argument list.  The simplest way to do this
 is to call :cfunc:`Py_BuildValue`.  For example, if you want to pass an integral
 event code, you might use the following code::
 
    PyObject *arglist;
    ...
    arglist = Py_BuildValue("(l)", eventcode);
-   result = PyEval_CallObject(my_callback, arglist);
+   result = PyObject_CallObject(my_callback, arglist);
    Py_DECREF(arglist);
    if (result == NULL)
        return NULL; /* Pass error back */
    /* Here maybe use the result */
    Py_DECREF(result);
 
 Note the placement of ``Py_DECREF(arglist)`` immediately after the call, before
-the error check!  Also note that strictly spoken this code is not complete:
+the error check!  Also note that strictly speaking this code is not complete:
 :cfunc:`Py_BuildValue` may run out of memory, and this should be checked.
 
+You may also call a function with keyword arguments by using
+:cfunc:`PyObject_Call`, which supports arguments and keyword arguments.  As in
+the above example, we use :cfunc:`Py_BuildValue` to construct the dictionary. ::
+
+   PyObject *dict;
+   ...
+   dict = Py_BuildValue("{s:i}", "name", val);
+   result = PyObject_Call(my_callback, NULL, dict);
+   Py_DECREF(dict);
+   if (result == NULL)
+       return NULL; /* Pass error back */
+   /* Here maybe use the result */
+   Py_DECREF(result);
+
 
 .. _parsetuple:
 
 Extracting Parameters in Extension Functions
 ============================================
 
 .. index:: single: PyArg_ParseTuple()
 
 The :cfunc:`PyArg_ParseTuple` function is declared as follows::
 
    int PyArg_ParseTuple(PyObject *arg, char *format, ...);
 
 The *arg* argument must be a tuple object containing an argument list passed
 from Python to a C function.  The *format* argument must be a format string,
-whose syntax is explained in "Parsing arguments and building values (XXX
-reference: ../api/arg-parsing.html)" in the Python/C API Reference Manual (XXX
-reference: ../api/api.html).  The remaining arguments must be addresses of
-variables whose type is determined by the format string.
+whose syntax is explained in :ref:`arg-parsing` in the Python/C API Reference
+Manual.  The remaining arguments must be addresses of variables whose type is
+determined by the format string.
 
 Note that while :cfunc:`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 there, your code will probably crash or
 at least overwrite random bits in memory.  So be careful!
 
 Note that any Python object references which are provided to the caller are
 *borrowed* references; do not decrement their reference count!
 
 Some example calls::
 
    int ok;
@@ -644,47 +657,43 @@
 right.  On success, :cfunc:`PyArg_ParseTupleAndKeywords` returns true, otherwise
 it returns false and raises an appropriate exception.
 
 .. note::
 
    Nested tuples cannot be parsed when using keyword arguments!  Keyword parameters
    passed in which are not present in the *kwlist* will cause :exc:`TypeError` to
    be raised.
 
 .. index:: single: Philbrick, Geoff
 
 Here is an example module which uses keywords, based on an example by Geoff
-Philbrick (philbrick@hks.com):
-
-.. % 
-
-::
+Philbrick (philbrick@hks.com)::
 
    #include "Python.h"
 
    static PyObject *
    keywdarg_parrot(PyObject *self, PyObject *args, PyObject *keywds)
-   {  
+   {
        int voltage;
        char *state = "a stiff";
        char *action = "voom";
        char *type = "Norwegian Blue";
 
        static char *kwlist[] = {"voltage", "state", "action", "type", NULL};
 
-       if (!PyArg_ParseTupleAndKeywords(args, keywds, "i|sss", kwlist, 
+       if (!PyArg_ParseTupleAndKeywords(args, keywds, "i|sss", kwlist,
                                         &voltage, &state, &action, &type))
-           return NULL; 
+           return NULL;
 
-       printf("-- This parrot wouldn't %s if you put %i Volts through it.\n", 
+       printf("-- This parrot wouldn't %s if you put %i Volts through it.\n",
               action, voltage);
        printf("-- Lovely plumage, the %s -- It's %s!\n", type, state);
 
        Py_INCREF(Py_None);
 
        return Py_None;
    }
 
    static PyMethodDef keywdarg_methods[] = {
        /* The cast of the function is necessary since PyCFunction values
         * only take two PyObject* parameters, and keywdarg_parrot() takes
         * three.
@@ -744,26 +753,26 @@
                  "abc", 123, "def", 456)    {'abc': 123, 'def': 456}
    Py_BuildValue("((ii)(ii)) (ii)",
                  1, 2, 3, 4, 5, 6)          (((1, 2), (3, 4)), (5, 6))
 
 
 .. _refcounts:
 
 Reference Counts
 ================
 
 In languages like C or C++, the programmer is responsible for dynamic allocation
 and deallocation of memory on the heap.  In C, this is done using the functions
-:cfunc:`malloc` and :cfunc:`free`.  In C++, the operators :keyword:`new` and
-:keyword:`delete` are used with essentially the same meaning and we'll restrict
+:cfunc:`malloc` and :cfunc:`free`.  In C++, the operators ``new`` and
+``delete`` are used with essentially the same meaning and we'll restrict
 the following discussion to the C case.
 
 Every block of memory allocated with :cfunc:`malloc` should eventually be
 returned to the pool of available memory by exactly one call to :cfunc:`free`.
 It is important to call :cfunc:`free` at the right time.  If a block's address
 is forgotten but :cfunc:`free` is not called for it, the memory it occupies
 cannot be reused until the program terminates.  This is called a :dfn:`memory
 leak`.  On the other hand, if a program calls :cfunc:`free` for a block and then
 continues to use the block, it creates a conflict with re-use of the block
 through another :cfunc:`malloc` call.  This is called :dfn:`using freed memory`.
 It has the same bad consequences as referencing uninitialized data --- core
 dumps, wrong results, mysterious crashes.
@@ -806,25 +815,25 @@
 applications to not worry about creating direct or indirect circular references;
 these are the weakness of garbage collection implemented using only reference
 counting.  Reference cycles consist of objects which contain (possibly indirect)
 references to themselves, so that each object in the cycle has a reference count
 which is non-zero.  Typical reference counting implementations are not able to
 reclaim the memory belonging to any objects in a reference cycle, or referenced
 from the objects in the cycle, even though there are no further references to
 the cycle itself.
 
 The cycle detector is able to detect garbage cycles and can reclaim them so long
 as there are no finalizers implemented in Python (:meth:`__del__` methods).
 When there are such finalizers, the detector exposes the cycles through the
-:mod:`gc` module (XXX reference: ../lib/module-gc.html) (specifically, the
+:mod:`gc` module (specifically, the
 ``garbage`` variable in that module).  The :mod:`gc` module also exposes a way
 to run the detector (the :func:`collect` function), as well as configuration
 interfaces and the ability to disable the detector at runtime.  The cycle
 detector is considered an optional component; though it is included by default,
 it can be disabled at build time using the :option:`--without-cycle-gc` option
 to the :program:`configure` script on Unix platforms (including Mac OS X) or by
 removing the definition of ``WITH_CYCLE_GC`` in the :file:`pyconfig.h` header on
 other platforms.  If the cycle detector is disabled in this way, the :mod:`gc`
 module will not be available.
 
 
 .. _refcountsinpython:
@@ -848,25 +857,25 @@
 dispose of an owned reference: pass it on, store it, or call :cfunc:`Py_DECREF`.
 Forgetting to dispose of an owned reference creates a memory leak.
 
 It is also possible to :dfn:`borrow` [#]_ a reference to an object.  The
 borrower of a reference should not call :cfunc:`Py_DECREF`.  The borrower must
 not hold on to the object longer than the owner from which it was borrowed.
 Using a borrowed reference after the owner has disposed of it risks using freed
 memory and should be avoided completely. [#]_
 
 The advantage of borrowing over owning a reference is that you don't need to
 take care of disposing of the reference on all possible paths through the code
 --- in other words, with a borrowed reference you don't run the risk of leaking
-when a premature exit is taken.  The disadvantage of borrowing over leaking is
+when a premature exit is taken.  The disadvantage of borrowing over owning is
 that there are some subtle situations where in seemingly correct code a borrowed
 reference can be used after the owner from which it was borrowed has in fact
 disposed of it.
 
 A borrowed reference can be changed into an owned reference by calling
 :cfunc:`Py_INCREF`.  This does not affect the status of the owner from which the
 reference was borrowed --- it creates a new owned reference, and gives full
 owner responsibilities (the new owner must dispose of the reference properly, as
 well as the previous owner).
 
 
 .. _ownershiprules:
@@ -1018,29 +1027,28 @@
 The macros for checking for a particular object type (``Pytype_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 *NULL*
 checking.
 
 The C function calling mechanism guarantees that the argument list passed to C
 functions (``args`` in the examples) is never *NULL* --- in fact it guarantees
 that it is always a tuple. [#]_
 
 It is a severe error to ever let a *NULL* pointer "escape" to the Python user.
 
-.. % Frank Stajano:
-.. % A pedagogically buggy example, along the lines of the previous listing,
-.. % would be helpful here -- showing in more concrete terms what sort of
-.. % actions could cause the problem. I can't very well imagine it from the
-.. % description.
+.. Frank Stajano:
+   A pedagogically buggy example, along the lines of the previous listing, would
+   be helpful here -- showing in more concrete terms what sort of actions could
+   cause the problem. I can't very well imagine it from the description.
 
 
 .. _cplusplus:
 
 Writing Extensions in C++
 =========================
 
 It is possible to write extension modules in C++.  Some restrictions apply.  If
 the main program (the Python interpreter) is compiled and 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 C++ compiler.  Functions that
 will be called by the Python interpreter (in particular, module initialization
@@ -1058,38 +1066,38 @@
 .. sectionauthor:: Konrad Hinsen <hinsen@cnrs-orleans.fr>
 
 
 Many extension modules just provide new functions and types to be used from
 Python, but sometimes the code in an extension module can be useful for other
 extension modules. For example, an extension module could implement a type
 "collection" which works like lists without order. Just like the standard Python
 list type has a C API which permits extension modules to create and manipulate
 lists, this new collection type should have a set of C functions for direct
 manipulation from other extension modules.
 
 At first sight this seems easy: just write the functions (without declaring them
-:keyword:`static`, of course), provide an appropriate header file, and document
+``static``, of course), provide an appropriate header file, and document
 the C API. And in fact this would work if all extension modules were always
 linked statically with the Python interpreter. When modules are used as shared
 libraries, however, the symbols defined in one module may not be visible to
 another module. The details of visibility depend on the operating system; some
 systems use one global namespace for the Python interpreter and all extension
 modules (Windows, for example), whereas others require an explicit list of
 imported symbols at module link time (AIX is one example), or offer a choice of
 different strategies (most Unices). And even if symbols are globally visible,
 the module whose functions one wishes to call might not have been loaded yet!
 
 Portability therefore requires not to make any assumptions about symbol
 visibility. This means that all symbols in extension modules should be declared
-:keyword:`static`, except for the module's initialization function, in order to
+``static``, except for the module's initialization function, in order to
 avoid name clashes with other extension modules (as discussed in section
 :ref:`methodtable`). And it means that symbols that *should* be accessible from
 other extension modules must be exported in a different way.
 
 Python provides a special mechanism to pass C-level information (pointers) from
 one extension module to another one: CObjects. A CObject is a Python data type
 which stores a pointer (:ctype:`void \*`).  CObjects can only be created and
 accessed via their C API, but they can be passed around like any other Python
 object. In particular,  they can be assigned to a name in an extension module's
 namespace. Other extension modules can then import this module, retrieve the
 value of this name, and then retrieve the pointer from the CObject.
 
@@ -1099,32 +1107,32 @@
 various tasks of storing and retrieving the pointers can be distributed in
 different ways between the module providing the code and the client modules.
 
 The following example demonstrates an approach that puts most of the burden on
 the writer of the exporting module, which is appropriate for commonly used
 library modules. It stores all C API pointers (just one in the example!) in an
 array of :ctype:`void` pointers which becomes the value of a CObject. The header
 file corresponding to the module provides a macro that takes care of importing
 the module and retrieving its C API pointers; client modules only have to call
 this macro before accessing the C API.
 
 The exporting module is a modification of the :mod:`spam` module from section
-:ref:`simpleexample`. The function :func:`spam.system` does not call the C
-library function :cfunc:`system` directly, but a function
+:ref:`extending-simpleexample`. The function :func:`spam.system` does not call
+the C library function :cfunc:`system` directly, but a function
 :cfunc:`PySpam_System`, which would of course do something more complicated in
 reality (such as adding "spam" to every command). This function
 :cfunc:`PySpam_System` is also exported to other extension modules.
 
 The function :cfunc:`PySpam_System` is a plain C function, declared
-:keyword:`static` like everything else::
+``static`` like everything else::
 
    static int
    PySpam_System(const char *command)
    {
        return system(command);
    }
 
 The function :cfunc:`spam_system` is modified in a trivial way::
 
    static PyObject *
    spam_system(PyObject *self, PyObject *args)
    {
@@ -1149,36 +1157,38 @@
 The ``#define`` is used to tell the header file that it is being included in the
 exporting module, not a client module. Finally, the module's initialization
 function must take care of initializing the C API pointer array::
 
    PyMODINIT_FUNC
    initspam(void)
    {
        PyObject *m;
        static void *PySpam_API[PySpam_API_pointers];
        PyObject *c_api_object;
 
        m = Py_InitModule("spam", SpamMethods);
+       if (m == NULL)
+           return;
 
        /* Initialize the C API pointer array */
        PySpam_API[PySpam_System_NUM] = (void *)PySpam_System;
 
        /* Create a CObject containing the API pointer array's address */
        c_api_object = PyCObject_FromVoidPtr((void *)PySpam_API, NULL);
 
        if (c_api_object != NULL)
            PyModule_AddObject(m, "_C_API", c_api_object);
    }
 
-Note that ``PySpam_API`` is declared :keyword:`static`; otherwise the pointer
+Note that ``PySpam_API`` is declared ``static``; otherwise the pointer
 array would disappear when :func:`initspam` terminates!
 
 The bulk of the work is in the header file :file:`spammodule.h`, which looks
 like this::
 
    #ifndef Py_SPAMMODULE_H
    #define Py_SPAMMODULE_H
    #ifdef __cplusplus
    extern "C" {
    #endif
 
    /* Header file for spammodule */
@@ -1230,39 +1240,40 @@
 
    #endif /* !defined(Py_SPAMMODULE_H) */
 
 All that a client module must do in order to have access to the function
 :cfunc:`PySpam_System` is to call the function (or rather macro)
 :cfunc:`import_spam` in its initialization function::
 
    PyMODINIT_FUNC
    initclient(void)
    {
        PyObject *m;
 
-       Py_InitModule("client", ClientMethods);
+       m = Py_InitModule("client", ClientMethods);
+       if (m == NULL)
+           return;
        if (import_spam() < 0)
            return;
        /* additional initialization can happen here */
    }
 
 The main disadvantage of this approach is that the file :file:`spammodule.h` is
 rather complicated. However, the basic structure is the same for each function
 that is exported, so it has to be learned only once.
 
 Finally it should be mentioned that CObjects offer additional functionality,
 which is especially useful for memory allocation and deallocation of the pointer
 stored in a CObject. The details are described in the Python/C API Reference
-Manual (XXX reference: ../api/api.html) in the section "CObjects (XXX reference:
-../api/cObjects.html)" and in the implementation of CObjects (files
+Manual in the section :ref:`cobjects` and in the implementation of CObjects (files
 :file:`Include/cobject.h` and :file:`Objects/cobject.c` in the Python source
 code distribution).
 
 .. rubric:: Footnotes
 
 .. [#] An interface for this function already exists in the standard module :mod:`os`
    --- it was chosen as a simple and straightforward example.
 
 .. [#] The metaphor of "borrowing" a reference is not completely correct: the owner
    still has a copy of the reference.
 
 .. [#] Checking that the reference count is at least 1 **does not work** --- the
