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.
diff --git a/Doc/api/refcounting.tex b/Doc/api/refcounting.tex
new file mode 100644
index 0000000..03530f0
--- /dev/null
+++ b/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}.