[Python-checkins] CVS: python/dist/src/Doc/ext embedding.tex,1.3,1.4 extending.tex,1.5,1.6 unix.tex,1.1,1.2 windows.tex,1.1,1.2

Tue, 27 Nov 2001 23:26:17 -0800

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

Modified Files:
	embedding.tex extending.tex unix.tex windows.tex 
Log Message:
Clean up some markup cruft.  A number of the macros that take no
parameters (like \UNIX) are commonly entered using an empty group to
separate the markup from a following inter-word space; this is not
needed when the next character is punctuation, or the markup is the
last thing in the enclosing group.  These cases were marked
inconsistently; the empty group is now *only* used when needed.

Index: embedding.tex
===================================================================
RCS file: /cvsroot/python/python/dist/src/Doc/ext/embedding.tex,v
retrieving revision 1.3
retrieving revision 1.4
diff -C2 -d -r1.3 -r1.4
*** embedding.tex	2001/11/17 06:50:42	1.3
--- embedding.tex	2001/11/28 07:26:14	1.4
***************
*** 273,284 ****

! \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
! will need to write the main program in \Cpp{}, and use the \Cpp{} compiler
  to compile and link your program.  There is no need to recompile Python
! itself using \Cpp{}.

--- 273,284 ----

! \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
! will need to write the main program in \Cpp, and use the \Cpp{} compiler
  to compile and link your program.  There is no need to recompile Python
! itself using \Cpp.

Index: extending.tex
===================================================================
RCS file: /cvsroot/python/python/dist/src/Doc/ext/extending.tex,v
retrieving revision 1.5
retrieving revision 1.6
diff -C2 -d -r1.5 -r1.6
*** extending.tex	2001/11/17 06:50:42	1.5
--- extending.tex	2001/11/28 07:26:15	1.6
***************
*** 1,3 ****
! \chapter{Extending Python with C or \Cpp{} \label{intro}}

--- 1,3 ----
! \chapter{Extending Python with C or \Cpp \label{intro}}

***************
*** 500,504 ****
  \ref{methodTable}, ``The Module's Method Table and Initialization
  Function.''  The \cfunction{PyArg_ParseTuple()} function and its
! arguments are documented in section \ref{parseTuple}, ``Extracting
  Parameters in Extension Functions.''

--- 500,504 ----
  \ref{methodTable}, ``The Module's Method Table and Initialization
  Function.''  The \cfunction{PyArg_ParseTuple()} function and its
! arguments are documented in section~\ref{parseTuple}, ``Extracting
  Parameters in Extension Functions.''

***************
*** 506,511 ****
  increment/decrement the reference count of an object and are safe in
  the presence of \NULL{} pointers (but note that \var{temp} will not be 
! \NULL{} in this context).  More info on them in section
! \ref{refcounts}, ``Reference Counts.''

  Later, when it is time to call the function, you call the C function
--- 506,511 ----
  increment/decrement the reference count of an object and are safe in
  the presence of \NULL{} pointers (but note that \var{temp} will not be 
! \NULL{} in this context).  More info on them in
! section~\ref{refcounts}, ``Reference Counts.''

  Later, when it is time to call the function, you call the C function
***************
*** 545,549 ****

  Before you do this, however, it is important to check that the return
! value isn't \NULL{}.  If it is, the Python function terminated by
  raising an exception.  If the C code that called
  \cfunction{PyEval_CallObject()} is called from Python, it should now
--- 545,549 ----

  Before you do this, however, it is important to check that the return
! value isn't \NULL.  If it is, the Python function terminated by
  raising an exception.  If the C code that called
  \cfunction{PyEval_CallObject()} is called from Python, it should now
***************
*** 653,657 ****
  \item[\samp{z} (string or \code{None}) {[char *]}]
  Like \samp{s}, but the Python object may also be \code{None}, in which
! case the C pointer is set to \NULL{}.

  \item[\samp{z\#} (string or \code{None} or any read buffer compatible object) 
--- 653,657 ----
  \item[\samp{z} (string or \code{None}) {[char *]}]
  Like \samp{s}, but the Python object may also be \code{None}, in which
! case the C pointer is set to \NULL.

  \item[\samp{z\#} (string or \code{None} or any read buffer compatible object) 
***************
*** 681,685 ****
  the buffer used for storing the encoded data).

! The encoding name must map to a registered codec. If set to \NULL{},
  the default encoding is used.

--- 681,685 ----
  the buffer used for storing the encoded data).

! The encoding name must map to a registered codec. If set to \NULL,
  the default encoding is used.

***************
*** 706,710 ****
  (\var{*buffer_length}, the buffer length).

! The encoding name must map to a registered codec. If set to \NULL{},
  the default encoding is used.

--- 706,710 ----
  (\var{*buffer_length}, the buffer length).

! The encoding name must map to a registered codec. If set to \NULL,
  the default encoding is used.

***************
*** 767,771 ****
  The C program thus receives the actual object that was passed.  The
  object's reference count is not increased.  The pointer stored is not
! \NULL{}.

  \item[\samp{O!} (object) {[\var{typeobject}, PyObject *]}]
--- 767,771 ----
  The C program thus receives the actual object that was passed.  The
  object's reference count is not increased.  The pointer stored is not
! \NULL.

  \item[\samp{O!} (object) {[\var{typeobject}, PyObject *]}]
***************
*** 946,950 ****
  \cfunction{PyArg_ParseTuple()} function.  The \var{kwdict} parameter
  is the dictionary of keywords received as the third parameter from the
! Python runtime.  The \var{kwlist} parameter is a \NULL{}-terminated
  list of strings which identify the parameters; the names are matched
  with the type information from \var{format} from left to right.  On
--- 946,950 ----
  \cfunction{PyArg_ParseTuple()} function.  The \var{kwdict} parameter
  is the dictionary of keywords received as the third parameter from the
! Python runtime.  The \var{kwlist} parameter is a \NULL-terminated
  list of strings which identify the parameters; the names are matched
  with the type information from \var{format} from left to right.  On
***************
*** 1056,1064 ****
  \item[\samp{s} (string) {[char *]}]
  Convert a null-terminated C string to a Python object.  If the C
! string pointer is \NULL{}, \code{None} is used.

  \item[\samp{s\#} (string) {[char *, int]}]
  Convert a C string and its length to a Python object.  If the C string
! pointer is \NULL{}, the length is ignored and \code{None} is
  returned.

--- 1056,1064 ----
  \item[\samp{s} (string) {[char *]}]
  Convert a null-terminated C string to a Python object.  If the C
! string pointer is \NULL, \code{None} is used.

  \item[\samp{s\#} (string) {[char *, int]}]
  Convert a C string and its length to a Python object.  If the C string
! pointer is \NULL, the length is ignored and \code{None} is
  returned.

***************
*** 1172,1179 ****
           \label{refcounts}}

! In languages like C or \Cpp{}, the programmer is responsible for
  dynamic allocation and deallocation of memory on the heap.  In C,
  this is done using the functions \cfunction{malloc()} and
! \cfunction{free()}.  In \Cpp{}, the operators \keyword{new} and
  \keyword{delete} are used with essentially the same meaning; they are
  actually implemented using \cfunction{malloc()} and
--- 1172,1179 ----
           \label{refcounts}}

! In languages like C or \Cpp, the programmer is responsible for
  dynamic allocation and deallocation of memory on the heap.  In C,
  this is done using the functions \cfunction{malloc()} and
! \cfunction{free()}.  In \Cpp, the operators \keyword{new} and
  \keyword{delete} are used with essentially the same meaning; they are
  actually implemented using \cfunction{malloc()} and
***************
*** 1424,1428 ****
  exception occurred.  The reason for not testing for \NULL{}
  arguments is that functions often pass the objects they receive on to
! other function --- if each function were to test for \NULL{},
  there would be a lot of redundant tests and the code would run more
  slowly.
--- 1424,1428 ----
  exception occurred.  The reason for not testing for \NULL{}
  arguments is that functions often pass the objects they receive on to
! other function --- if each function were to test for \NULL,
  there would be a lot of redundant tests and the code would run more
  slowly.
***************
*** 1459,1466 ****

! \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
  linked by the C compiler, global or static objects with constructors
--- 1459,1466 ----

! \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
  linked by the C compiler, global or static objects with constructors

Index: unix.tex
===================================================================
RCS file: /cvsroot/python/python/dist/src/Doc/ext/unix.tex,v
retrieving revision 1.1
retrieving revision 1.2
diff -C2 -d -r1.1 -r1.2
*** unix.tex	2001/08/20 19:30:29	1.1
--- unix.tex	2001/11/28 07:26:15	1.2
***************
*** 14,18 ****
  the Python interpreter was built, so people building module's don't
  have to resupply these settings.  This vastly simplifies the process
! of building extensions and custom interpreters on Unix systems.

  The make file make file is distributed as the file
--- 14,18 ----
  the Python interpreter was built, so people building module's don't
  have to resupply these settings.  This vastly simplifies the process
! of building extensions and custom interpreters on \UNIX{} systems.

  The make file make file is distributed as the file

Index: windows.tex
===================================================================
RCS file: /cvsroot/python/python/dist/src/Doc/ext/windows.tex,v
retrieving revision 1.1
retrieving revision 1.2
diff -C2 -d -r1.1 -r1.2
*** windows.tex	2001/08/20 19:30:29	1.1
--- windows.tex	2001/11/28 07:26:15	1.2
***************
*** 4,8 ****

  This chapter briefly explains how to create a Windows extension module
! for Python using Microsoft Visual \Cpp{}, and follows with more
  detailed background information on how it works.  The explanatory
  material is useful for both the Windows programmer learning to build
--- 4,8 ----

  This chapter briefly explains how to create a Windows extension module
! for Python using Microsoft Visual \Cpp, and follows with more
  detailed background information on how it works.  The explanatory
  material is useful for both the Windows programmer learning to build
***************
*** 67,71 ****
  dynamically loaded, be aware of how your system works.

! In \UNIX{}, a shared object (\file{.so}) file contains code to be used by the
  program, and also the names of functions and data that it expects to
  find in the program.  When the file is joined to the program, all
--- 67,71 ----
  dynamically loaded, be aware of how your system works.

! In \UNIX, a shared object (\file{.so}) file contains code to be used by the
  program, and also the names of functions and data that it expects to
  find in the program.  When the file is joined to the program, all
***************
*** 81,85 ****
  point to the functions and data.

! In \UNIX{}, there is only one type of library file (\file{.a}) which
  contains code from several object files (\file{.o}).  During the link
  step to create a shared object file (\file{.so}), the linker may find
--- 81,85 ----
  point to the functions and data.

! In \UNIX, there is only one type of library file (\file{.a}) which
  contains code from several object files (\file{.o}).  During the link
  step to create a shared object file (\file{.so}), the linker may find
***************
*** 100,104 ****

  Suppose you are building two dynamic-load modules, B and C, which should
! share another block of code A.  On \UNIX{}, you would \emph{not} pass
  \file{A.a} to the linker for \file{B.so} and \file{C.so}; that would
  cause it to be included twice, so that B and C would each have their
--- 100,104 ----

  Suppose you are building two dynamic-load modules, B and C, which should
! share another block of code A.  On \UNIX, you would \emph{not} pass
  \file{A.a} to the linker for \file{B.so} and \file{C.so}; that would
  cause it to be included twice, so that B and C would each have their
***************
*** 110,114 ****
  In Windows, using an import library is sort of like using \samp{import
  spam}; it gives you access to spam's names, but does not create a
! separate copy.  On \UNIX{}, linking with a library is more like
  \samp{from spam import *}; it does create a separate copy.

--- 110,114 ----
  In Windows, using an import library is sort of like using \samp{import
  spam}; it gives you access to spam's names, but does not create a
! separate copy.  On \UNIX, linking with a library is more like
  \samp{from spam import *}; it does create a separate copy.

***************
*** 117,121 ****
  \sectionauthor{Chris Phoenix}{cphoenix@best.com}

! Windows Python is built in Microsoft Visual \Cpp{}; using other
  compilers may or may not work (though Borland seems to).  The rest of
  this section is MSV\Cpp{} specific.
--- 117,121 ----
  \sectionauthor{Chris Phoenix}{cphoenix@best.com}

! Windows Python is built in Microsoft Visual \Cpp; using other
  compilers may or may not work (though Borland seems to).  The rest of
  this section is MSV\Cpp{} specific.