python
diff --git a/‎Doc/ext.tex‎
Lines changed: 49 additions & 22 deletions b/‎Doc/ext.tex‎
Lines changed: 49 additions & 22 deletions
@@ -30,17 +30,17 @@
 operating system supports this feature.
 
 This document assumes basic knowledge about Python.  For an informal
-introduction to the language, see the Python Tutorial.  The Python
-Reference Manual gives a more formal definition of the language.  The
-Python Library Reference documents the existing object types,
+introduction to the language, see the Python Tutorial.  The \emph{Python
+Reference Manual} gives a more formal definition of the language.  The
+\emph{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
-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).
+\emph{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).
 
 
 \end{abstract}
@@ -51,7 +51,8 @@
 \chapter{Extending Python with \C{} or \Cpp{} code}
 
 
-\section{Introduction}
+%\section{Introduction}
+\label{intro}
 
 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
@@ -69,6 +70,7 @@ \section{Introduction}
 
 
 \section{A Simple Example}
+\label{simpleExample}
 
 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
@@ -141,13 +143,13 @@ \section{A Simple Example}
 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()}
+to convert them to \C{} values.  The function \cfunction{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.
 
-\code{PyArg_ParseTuple()} returns true (nonzero) if all arguments have
+\cfunction{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
@@ -156,6 +158,7 @@ \section{A Simple Example}
 
 
 \section{Intermezzo: Errors and Exceptions}
+\label{errors}
 
 An important convention throughout the Python interpreter is the
 following: when a function fails, it should set an exception condition
@@ -226,7 +229,7 @@ \section{Intermezzo: Errors and Exceptions}
 \code{malloc()} directly this note is of importance.
 
 Also note that, with the important exception of
-\code{PyArg_ParseTuple()} and friends, functions that return an
+\cfunction{PyArg_ParseTuple()} and friends, functions that return an
 integer status usually return a positive value or zero for success and
 \code{-1} for failure, like \UNIX{} system calls.
 
@@ -240,7 +243,7 @@ \section{Intermezzo: Errors and Exceptions}
 course, you should choose exceptions wisely --- don't use
 \code{PyExc_TypeError} to mean that a file couldn't be opened (that
 should probably be \code{PyExc_IOError}).  If something's wrong with
-the argument list, the \code{PyArg_ParseTuple()} function usually
+the argument list, the \cfunction{PyArg_ParseTuple()} function usually
 raises \code{PyExc_TypeError}.  If you have an argument whose value
 which must be in a particular range or must satisfy other conditions,
 \code{PyExc_ValueError} is appropriate.
@@ -277,6 +280,7 @@ \section{Intermezzo: Errors and Exceptions}
 
 
 \section{Back to the Example}
+\label{backToExample}
 
 Going back to our example function, you should now be able to
 understand this statement:
@@ -288,15 +292,15 @@ \section{Back to the Example}
 
 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
+on the exception set by \cfunction{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
 \code{command} should properly be declared as \samp{const char
 *command}).
 
 The next statement is a call to the \UNIX{} function \code{system()},
-passing it the string we just got from \code{PyArg_ParseTuple()}:
+passing it the string we just got from \cfunction{PyArg_ParseTuple()}:
 
 \begin{verbatim}
     sts = system(command);
@@ -305,7 +309,7 @@ \section{Back to the Example}
 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
+\cfunction{PyArg_ParseTuple()}: it takes a format string and an arbitrary
 number of \C{} values, and returns a new Python object.  More info on
 \code{Py_BuildValue()} is given later.
 
@@ -331,6 +335,7 @@ \section{Back to the Example}
 
 
 \section{The Module's Method Table and Initialization Function}
+\label{methodTable}
 
 I promised to show how \code{spam_system()} is called from Python
 programs.  First, we need to list its name and address in a ``method
@@ -349,7 +354,7 @@ \section{The Module's Method Table and Initialization Function}
 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.
+obsolete variant of \cfunction{PyArg_ParseTuple()} is used.
 
 When using only \samp{METH_VARARGS}, the function should expect
 the Python-level parameters to be passed in as a tuple acceptable for
@@ -359,7 +364,7 @@ \section{The Module's Method Table and Initialization Function}
 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()} 
+be a dictionary of keywords.  Use \cfunction{PyArg_ParseTupleAndKeywords()}
 to parse the arguemts to such a function.
 
 The method table must be passed to the interpreter in the module's
@@ -387,6 +392,7 @@ \section{The Module's Method Table and Initialization Function}
 
 
 \section{Compilation and Linkage}
+\label{compilation}
 
 There are two more things to do before you can use your new extension:
 compiling and linking it with the Python system.  If you use dynamic
@@ -419,6 +425,7 @@ \section{Compilation and Linkage}
 \end{verbatim}
 
 \section{Calling Python Functions From \C{}}
+\label{callingPython}
 
 So far we have concentrated on making \C{} functions callable from
 Python.  The reverse is also useful: calling Python functions from \C{}.
@@ -543,8 +550,9 @@ \section{Calling Python Functions From \C{}}
 
 
 \section{Format Strings for \sectcode{PyArg_ParseTuple()}}
+\label{parseTuple}
 
-The \code{PyArg_ParseTuple()} function is declared as follows:
+The \cfunction{PyArg_ParseTuple()} function is declared as follows:
 
 \begin{verbatim}
 int PyArg_ParseTuple(PyObject *arg, char *format, ...);
@@ -558,7 +566,7 @@ \section{Format Strings for \sectcode{PyArg_ParseTuple()}}
 \var{arg} object must match the format and the format must be
 exhausted.
 
-Note that while \code{PyArg_ParseTuple()} checks that the Python
+Note that while \cfunction{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
@@ -568,7 +576,7 @@ \section{Format Strings for \sectcode{PyArg_ParseTuple()}}
 unit describes one Python object; it is usually a single character or
 a parenthesized sequence of format units.  With a few exceptions, a
 format unit that is not a parenthesized sequence normally corresponds
-to a single address argument to \code{PyArg_ParseTuple()}.  In the
+to a single address argument to \cfunction{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{}
@@ -582,7 +590,7 @@ \section{Format Strings for \sectcode{PyArg_ParseTuple()}}
 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
-must not contain embedded null bytes; if it does, a \code{TypeError}
+must not contain embedded null bytes; if it does, a \exception{TypeError}
 exception is raised.
 
 \item[\samp{s\#} (string) {[char *, int]}]
@@ -748,6 +756,7 @@ \section{Format Strings for \sectcode{PyArg_ParseTuple()}}
 
 
 \section{Keyword Parsing with \sectcode{PyArg_ParseTupleAndKeywords()}}
+\label{parseTupleAndKeywords}
 
 The \cfunction{PyArg_ParseTupleAndKeywords()} function is declared as
 follows:
@@ -817,6 +826,7 @@ \section{Keyword Parsing with \sectcode{PyArg_ParseTupleAndKeywords()}}
 
 
 \section{The \sectcode{Py_BuildValue()} Function}
+\label{buildValue}
 
 This function is the counterpart to \code{PyArg_ParseTuple()}.  It is
 declared as follows:
@@ -945,8 +955,9 @@ \section{The \sectcode{Py_BuildValue()} Function}
 \end{verbatim}
 
 \section{Reference Counts}
+\label{refcounts}
 
-\subsection{Introduction}
+%\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
@@ -1007,6 +1018,7 @@ \subsection{Introduction}
 reference counts.
 
 \subsection{Reference Counting in Python}
+\label{refcountsInPython}
 
 There are two macros, \code{Py_INCREF(x)} and \code{Py_DECREF(x)},
 which handle the incrementing and decrementing of the reference count.
@@ -1054,6 +1066,7 @@ \subsection{Reference Counting in Python}
 dispose of the reference properly, as well as the previous owner).
 
 \subsection{Ownership Rules}
+\label{ownershipRules}
 
 Whenever an object reference is passed into or out of a function, it
 is part of the function's interface specification whether ownership is
@@ -1102,6 +1115,7 @@ \subsection{Ownership Rules}
 function to its caller.
 
 \subsection{Thin Ice}
+\label{thinIce}
 
 There are a few situations where seemingly harmless use of a borrowed
 reference can lead to problems.  These all have to do with implicit
@@ -1181,6 +1195,7 @@ \subsection{Thin Ice}
 \end{verbatim}
 
 \subsection{NULL Pointers}
+\label{nullPointers}
 
 In general, functions that take object references as arguments don't
 expect you to pass them \NULL{} pointers, and will dump core (or
@@ -1217,6 +1232,7 @@ \subsection{NULL Pointers}
 
 
 \section{Writing Extensions in \Cpp{}}
+\label{cplusplus}
 
 It is possible to write extension modules in \Cpp{}.  Some restrictions
 apply.  If the main program (the Python interpreter) is compiled and
@@ -1231,6 +1247,7 @@ \section{Writing Extensions in \Cpp{}}
 symbol).
 
 \chapter{Embedding Python in another application}
+\label{embedding}
 
 Embedding Python is similar to extending it, but not quite.  The
 difference is that when you extend Python, the main program of the
@@ -1258,6 +1275,7 @@ \chapter{Embedding Python in another application}
 
 
 \section{Embedding Python in \Cpp{}}
+\label{embeddingInCplusplus}
 
 It is also possible to embed Python in a \Cpp{} program; precisely how this
 is done will depend on the details of the \Cpp{} system used; in general you
@@ -1267,6 +1285,7 @@ \section{Embedding Python in \Cpp{}}
 
 
 \chapter{Dynamic Loading}
+\label{dynload}
 
 On most modern systems it is possible to configure Python to support
 dynamic loading of extension modules implemented in \C{}.  When shared
@@ -1290,12 +1309,14 @@ \chapter{Dynamic Loading}
 
 
 \section{Configuring and Building the Interpreter for Dynamic Loading}
+\label{dynloadConfig}
 
 There are three styles of dynamic loading: one using shared libraries,
 one using SGI IRIX 4 dynamic loading, and one using GNU dynamic
 loading.
 
 \subsection{Shared Libraries}
+\label{sharedlibs}
 
 The following systems support dynamic loading using shared libraries:
 SunOS 4; Solaris 2; SGI IRIX 5 (but not SGI IRIX 4!); and probably all
@@ -1308,6 +1329,7 @@ \subsection{Shared Libraries}
 loading.
 
 \subsection{SGI IRIX 4 Dynamic Loading}
+\label{irixDynload}
 
 Only SGI IRIX 4 supports dynamic loading of modules using SGI dynamic
 loading.  (SGI IRIX 5 might also support it but it is inferior to
@@ -1329,6 +1351,7 @@ \subsection{SGI IRIX 4 Dynamic Loading}
 \file{README} file in the toplevel Python directory.)
 
 \subsection{GNU Dynamic Loading}
+\label{gnuDynload}
 
 GNU dynamic loading supports (according to its \file{README} file) the
 following hardware and software combinations: VAX (Ultrix), Sun 3
@@ -1359,6 +1382,7 @@ \subsection{GNU Dynamic Loading}
 
 
 \section{Building a Dynamically Loadable Module}
+\label{makedynload}
 
 Since there are three styles of dynamic loading, there are also three
 groups of instructions for building a dynamically loadable module.
@@ -1379,6 +1403,7 @@ \section{Building a Dynamically Loadable Module}
 
 
 \subsection{Shared Libraries}
+\label{linking}
 
 You must link the \file{.o} file to produce a shared library.  This is 
 done using a special invocation of the \UNIX{} loader/linker,
@@ -1413,6 +1438,7 @@ \subsection{Shared Libraries}
 
 
 \subsection{SGI IRIX 4 Dynamic Loading}
+\label{irixLinking}
 
 \strong{IMPORTANT:} You must compile your extension module with the
 additional \C{} flag \samp{-G0} (or \samp{-G 0}).  This instruct the
@@ -1441,6 +1467,7 @@ \subsection{SGI IRIX 4 Dynamic Loading}
 
 
 \subsection{GNU Dynamic Loading}
+\label{gnuLinking}
 
 Just copy \file{spammodule.o} into a directory along the Python module
 search path.