Break the Python/C API manual into smaller files by chapter. This manual

has grown beyond what font-lock will work with using the default (X)Emacs
settings.

Indentation of the description has been made consistent, and a number of
smaller markup adjustments have been made as well.

Doc/api/refcounting.tex

@@ -0,0 +1,48 @@
+\chapter{Reference Counting \label{countingRefs}}
+
+
+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 \var{o}.  The object must
+  not be \NULL; if you aren't sure that it isn't \NULL, use
+  \cfunction{Py_XINCREF()}.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{void}{Py_XINCREF}{PyObject *o}
+  Increment the reference count for object \var{o}.  The object may be
+  \NULL, in which case the macro has no effect.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{void}{Py_DECREF}{PyObject *o}
+  Decrement 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_XDECREF()}.  If the reference count reaches zero, the
+  object's type's deallocation function (which must not be \NULL) is
+  invoked.
+
+  \warning{The deallocation function can cause arbitrary Python code
+  to be invoked (e.g. when a class instance with a \method{__del__()}
+  method is deallocated).  While exceptions in such code are not
+  propagated, the executed code has free access to all Python global
+  variables.  This means that any object that is reachable from a
+  global variable should be in a consistent state before
+  \cfunction{Py_DECREF()} is invoked.  For example, code to delete an
+  object from a list should copy a reference to the deleted object in
+  a temporary variable, update the list data structure, and then call
+  \cfunction{Py_DECREF()} for the temporary variable.}
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{void}{Py_XDECREF}{PyObject *o}
+  Decrement the reference count for object \var{o}.  The object may be
+  \NULL, in which case the macro has no effect; otherwise the effect
+  is the same as for \cfunction{Py_DECREF()}, and the same warning
+  applies.
+\end{cfuncdesc}
+
+The following functions or macros are only for use within the
+interpreter core: \cfunction{_Py_Dealloc()},
+\cfunction{_Py_ForgetReference()}, \cfunction{_Py_NewReference()}, as
+well as the global variable \cdata{_Py_RefTotal}.