[Python-checkins] CVS: python/dist/src/Doc/ext ext.tex,1.97,1.98

[Fred L. Drake]

Update of /cvsroot/python/python/dist/src/Doc/ext
In directory usw-pr-cvs1:/tmp/cvs-serv6324/ext

Modified Files:
	ext.tex 
Log Message:

Fix up a few style nits -- avoid "e.g." and "i.e." -- these make
translation more difficult, as well as reading the English more
difficult for non-native speakers.


Index: ext.tex
===================================================================
RCS file: /cvsroot/python/python/dist/src/Doc/ext/ext.tex,v
retrieving revision 1.97
retrieving revision 1.98
diff -C2 -r1.97 -r1.98
*** ext.tex	2001/06/20 21:37:34	1.97
--- ext.tex	2001/07/06 06:47:15	1.98
***************
*** 130,136 ****
  
  There is a straightforward translation from the argument list in
! Python (e.g.\ the single expression \code{"ls -l"}) to the arguments
! passed to the C function.  The C function always has two arguments,
! conventionally named \var{self} and \var{args}.
  
  The \var{self} argument is only used when the C function implements a
--- 130,136 ----
  
  There is a straightforward translation from the argument list in
! Python (for example, the single expression \code{"ls -l"}) to the
! arguments passed to the C function.  The C function always has two
! arguments, conventionally named \var{self} and \var{args}.
  
  The \var{self} argument is only used when the C function implements a
***************
*** 201,205 ****
  When a function \var{f} that calls another function \var{g} detects
  that the latter fails, \var{f} should itself return an error value
! (e.g.\ \NULL{} or \code{-1}).  It should \emph{not} call one of the
  \cfunction{PyErr_*()} functions --- one has already been called by \var{g}.
  \var{f}'s caller is then supposed to also return an error indication
--- 201,205 ----
  When a function \var{f} that calls another function \var{g} detects
  that the latter fails, \var{f} should itself return an error value
! (usually \NULL{} or \code{-1}).  It should \emph{not} call one of the
  \cfunction{PyErr_*()} functions --- one has already been called by \var{g}.
  \var{f}'s caller is then supposed to also return an error indication
***************
*** 221,226 ****
  The only time C code should call \cfunction{PyErr_Clear()} is if it doesn't
  want to pass the error on to the interpreter but wants to handle it
! completely by itself (e.g.\ by trying something else or pretending
! nothing happened).
  
  Every failing \cfunction{malloc()} call must be turned into an
--- 221,226 ----
  The only time C code should call \cfunction{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 \cfunction{malloc()} call must be turned into an
***************
*** 242,247 ****
  The choice of which exception to raise is entirely yours.  There are
  predeclared C objects corresponding to all built-in Python exceptions,
! e.g.\ \cdata{PyExc_ZeroDivisionError}, which you can use directly.  Of
! course, you should choose exceptions wisely --- don't use
  \cdata{PyExc_TypeError} to mean that a file couldn't be opened (that
  should probably be \cdata{PyExc_IOError}).  If something's wrong with
--- 242,247 ----
  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 should choose exceptions wisely --- don't use
  \cdata{PyExc_TypeError} to mean that a file couldn't be opened (that
  should probably be \cdata{PyExc_IOError}).  If something's wrong with
***************
*** 253,257 ****
  You can also define a new exception that is unique to your module.
  For this, you usually declare a static object variable at the
! beginning of your file, e.g.
  
  \begin{verbatim}
--- 253,257 ----
  You can also define a new exception that is unique to your module.
  For this, you usually declare a static object variable at the
! beginning of your file:
  
  \begin{verbatim}
***************
*** 260,264 ****
  
  and initialize it in your module's initialization function
! (\cfunction{initspam()}) with an exception object, e.g.\ (leaving out
  the error checking for now):
  
--- 260,264 ----
  
  and initialize it in your module's initialization function
! (\cfunction{initspam()}) with an exception object (leaving out
  the error checking for now):
  
***************
*** 1317,1321 ****
  \cfunction{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 (i.e., the new owner must
  dispose of the reference properly, as well as the previous owner).
  
--- 1317,1321 ----
  \cfunction{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).
  
***************
*** 1330,1334 ****
  Most functions that return a reference to an object pass on ownership
  with the reference.  In particular, all functions whose function it is
! to create a new object, e.g.\ \cfunction{PyInt_FromLong()} and
  \cfunction{Py_BuildValue()}, pass ownership to the receiver.  Even if in
  fact, in some cases, you don't receive a reference to a brand new
--- 1330,1334 ----
  Most functions that return a reference to an object pass on ownership
  with the reference.  In particular, all functions whose function it is
! to create a new object, such as \cfunction{PyInt_FromLong()} and
  \cfunction{Py_BuildValue()}, pass ownership to the receiver.  Even if in
  fact, in some cases, you don't receive a reference to a brand new
***************
*** 1468,1473 ****
  slowly.
  
! It is better to test for \NULL{} only at the ``source'', i.e.\ when a
! pointer that may be \NULL{} is received, e.g.\ from
  \cfunction{malloc()} or from a function that may raise an exception.
  
--- 1468,1473 ----
  slowly.
  
! It is better to test for \NULL{} only at the ``source:'' when a
! pointer that may be \NULL{} is received, for example, from
  \cfunction{malloc()} or from a function that may raise an exception.
  
***************
*** 1536,1544 ****
  The details of visibility depend on the operating system; some systems
  use one global namespace for the Python interpreter and all extension
! modules (e.g.\ Windows), whereas others require an explicit list of
! imported symbols at module link time (e.g.\ AIX), 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
--- 1536,1544 ----
  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
***************
*** 1550,1555 ****
  extension modules must be exported in a different way.
  
! Python provides a special mechanism to pass C-level information (i.e.
! 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
--- 1550,1555 ----
  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
***************
*** 1905,1909 ****
  \end{verbatim}
  
! This allocates the memory and then initializes the object (i.e.\ sets
  the reference count to one, makes the \cdata{ob_type} pointer point at
  the right place and maybe some other stuff, depending on build options).
--- 1905,1909 ----
  \end{verbatim}
  
! This allocates the memory and then initializes the object (sets
  the reference count to one, makes the \cdata{ob_type} pointer point at
  the right place and maybe some other stuff, depending on build options).