--- Python-Docs-2.4/./api/init.tex	2004-10-11 11:40:35.000000000 +0900
+++ Python-Docs-2.5/./api/init.tex	2006-08-11 07:45:34.000000000 +0900
@@ -131,6 +131,12 @@
   objects may affect the wrong (sub-)interpreter's dictionary of
   loaded modules.  (XXX This is a hard-to-fix bug that will be
   addressed in a future release.)
+
+  Also note that the use of this functionality is incompatible with
+  extension modules such as PyObjC and ctypes that use the
+  \cfunction{PyGILState_*} APIs (and this is inherent in the way the
+  \cfunction{PyGILState_*} functions work).  Simple things may work,
+  but confusing behavior will always be near.
 \end{cfuncdesc}
 
 \begin{cfuncdesc}{void}{Py_EndInterpreter}{PyThreadState *tstate}
@@ -178,7 +184,7 @@
   variable in the top-level \file{Makefile} and the
   \longprogramopt{prefix} argument to the \program{configure} script
   at build time.  The value is available to Python code as
-  \code{sys.prefix}.  It is only useful on \UNIX.  See also the next
+  \code{sys.prefix}.  It is only useful on \UNIX{}.  See also the next
   function.
 \end{cfuncdesc}
 
@@ -239,9 +245,8 @@
   program name (set by \cfunction{Py_SetProgramName()} above) and some
   environment variables.  The returned string consists of a series of
   directory names separated by a platform dependent delimiter
-  character.  The delimiter character is \character{:} on \UNIX,
-  \character{;} on Windows, and \character{\e n} (the \ASCII{}
-  newline character) on Macintosh.  The returned string points into
+  character.  The delimiter character is \character{:} on \UNIX and Mac OS X,
+  \character{;} on Windows.  The returned string points into
   static storage; the caller should not modify its value.  The value
   is available to Python code as the list
   \code{sys.path}\withsubitem{(in module sys)}{\ttindex{path}}, which
@@ -267,12 +272,19 @@
   \withsubitem{(in module sys)}{\ttindex{version}}
 \end{cfuncdesc}
 
+\begin{cfuncdesc}{const char*}{Py_GetBuildNumber}{}
+  Return a string representing the Subversion revision that this Python
+  executable was built from.  This number is a string because it may contain a
+  trailing 'M' if Python was built from a mixed revision source tree.
+  \versionadded{2.5}
+\end{cfuncdesc}
+
 \begin{cfuncdesc}{const char*}{Py_GetPlatform}{}
   Return the platform identifier for the current platform.  On \UNIX,
   this is formed from the ``official'' name of the operating system,
   converted to lower case, followed by the major revision number;
   e.g., for Solaris 2.x, which is also known as SunOS 5.x, the value
-  is \code{'sunos5'}.  On Macintosh, it is \code{'mac'}.  On Windows,
+  is \code{'sunos5'}.  On Mac OS X, it is \code{'darwin'}.  On Windows,
   it is \code{'win'}.  The returned string points into static storage;
   the caller should not modify its value.  The value is available to
   Python code as \code{sys.platform}.
@@ -319,7 +331,7 @@
   \withsubitem{(in module sys)}{\ttindex{version}}
 \end{cfuncdesc}
 
-\begin{cfuncdesc}{int}{PySys_SetArgv}{int argc, char **argv}
+\begin{cfuncdesc}{void}{PySys_SetArgv}{int argc, char **argv}
   Set \code{sys.argv} based on \var{argc} and \var{argv}.  These
   parameters are similar to those passed to the program's
   \cfunction{main()}\ttindex{main()} function with the difference that
@@ -455,19 +467,10 @@
 pointer, release the lock, and finally free their thread state data
 structure.
 
-When creating a thread data structure, you need to provide an
-interpreter state data structure.  The interpreter state data
-structure holds global data that is shared by all threads in an
-interpreter, for example the module administration
-(\code{sys.modules}).  Depending on your needs, you can either create
-a new interpreter state data structure, or share the interpreter state
-data structure used by the Python main thread (to access the latter,
-you must obtain the thread state and access its \member{interp} member;
-this must be done by a thread that is created by Python or by the main
-thread after Python is initialized).
-
-Assuming you have access to an interpreter object, the typical idiom
-for calling into Python from a C thread is
+Beginning with version 2.3, threads can now take advantage of the 
+\cfunction{PyGILState_*()} functions to do all of the above
+automatically.  The typical idiom for calling into Python from a C
+thread is now:
 
 \begin{verbatim}
     PyGILState_STATE gstate;
@@ -481,6 +484,13 @@
     PyGILState_Release(gstate);
 \end{verbatim}
 
+Note that the \cfunction{PyGILState_*()} functions assume there is
+only one global interpreter (created automatically by
+\cfunction{Py_Initialize()}).  Python still supports the creation of
+additional interpreters (using \cfunction{Py_NewInterpreter()}), but
+mixing multiple interpreters and the \cfunction{PyGILState_*()} API is
+unsupported.
+
 \begin{ctypedesc}{PyInterpreterState}
   This data structure represents the state shared by a number of
   cooperating threads.  Threads belonging to the same interpreter
@@ -686,30 +696,30 @@
 \end{cfuncdesc}
 
 \begin{cfuncdesc}{int}{PyThreadState_SetAsyncExc}{long id, PyObject *exc}
-  Asynchronously raise an exception in a thread. 
+  Asynchronously raise an exception in a thread.
   The \var{id} argument is the thread id of the target thread;
   \var{exc} is the exception object to be raised.
   This function does not steal any references to \var{exc}.
-  To prevent naive misuse, you must write your own C extension 
-  to call this.  Must be called with the GIL held. 
-  Returns the number of thread states modified; if it returns a number 
-  greater than one, you're in trouble, and you should call it again 
-  with \var{exc} set to \constant{NULL} to revert the effect.
+  To prevent naive misuse, you must write your own C extension
+  to call this.  Must be called with the GIL held.
+  Returns the number of thread states modified; this is normally one, but
+  will be zero if the thread id isn't found.  If \var{exc} is
+  \constant{NULL}, the pending exception (if any) for the thread is cleared.
   This raises no exceptions.
   \versionadded{2.3}
 \end{cfuncdesc}
 
 \begin{cfuncdesc}{PyGILState_STATE}{PyGILState_Ensure}{}
-Ensure that the current thread is ready to call the Python
-C API regardless of the current state of Python, or of its
-thread lock.  This may be called as many times as desired
-by a thread as long as each call is matched with a call to 
-\cfunction{PyGILState_Release()}.  
-In general, other thread-related APIs may 
-be used between \cfunction{PyGILState_Ensure()} and \cfunction{PyGILState_Release()} calls as long as the 
-thread state is restored to its previous state before the Release().
-For example, normal usage of the \csimplemacro{Py_BEGIN_ALLOW_THREADS}
-and \csimplemacro{Py_END_ALLOW_THREADS} macros is acceptable.
+Ensure that the current thread is ready to call the Python C API
+regardless of the current state of Python, or of its thread lock.
+This may be called as many times as desired by a thread as long as
+each call is matched with a call to \cfunction{PyGILState_Release()}.
+In general, other thread-related APIs may be used between
+\cfunction{PyGILState_Ensure()} and \cfunction{PyGILState_Release()}
+calls as long as the thread state is restored to its previous state
+before the Release().  For example, normal usage of the
+\csimplemacro{Py_BEGIN_ALLOW_THREADS} and
+\csimplemacro{Py_END_ALLOW_THREADS} macros is acceptable.
     
 The return value is an opaque "handle" to the thread state when
 \cfunction{PyGILState_Acquire()} was called, and must be passed to
