[Python-checkins] CVS: python/dist/src/Doc/api api.tex,1.56.2.19,1.56.2.20

Fred L. Drake python-dev@python.org
Tue, 21 Mar 2000 11:32:22 -0500 (EST)


Update of /projects/cvsroot/python/dist/src/Doc/api
In directory weyr:/home/fdrake/projects/python/Doc-152p2/api

Modified Files:
      Tag: release152p1-patches
	api.tex 
Log Message:

A number of minor consistency fixes and wording changes.

Explain how *not* to include the Python header file; omniORBpy gets it 
wrong on multi-platform installs on Unix!


Index: api.tex
===================================================================
RCS file: /projects/cvsroot/python/dist/src/Doc/api/api.tex,v
retrieving revision 1.56.2.19
retrieving revision 1.56.2.20
diff -C2 -r1.56.2.19 -r1.56.2.20
*** api.tex	2000/03/16 15:11:15	1.56.2.19
--- api.tex	2000/03/21 16:32:18	1.56.2.20
***************
*** 105,109 ****
--- 105,117 ----
  the installation directory specified to the installer.
  
+ To include the headers, place both directories (if different) on your
+ compiler's search path for includes.  Do \emph{not} place the parent
+ directories on the search path and then use
+ \samp{\#include <python1.5/Python.h>}; this will break on
+ multi-platform builds since the platform independent headers under
+ \envvar{prefix} include the platform specific headers from
+ \envvar{exec_prefix}.
  
+ 
  \section{Objects, Types and Reference Counts \label{objects}}
  
***************
*** 114,121 ****
  Python language in most situations (e.g., assignments, scope rules,
  and argument passing), it is only fitting that they should be
! represented by a single C type.  All Python objects live on the heap:
! you never declare an automatic or static variable of type
  \ctype{PyObject}, only pointer variables of type \ctype{PyObject*} can 
! be declared.
  
  All Python objects (even Python integers) have a \dfn{type} and a
--- 122,131 ----
  Python language in most situations (e.g., assignments, scope rules,
  and argument passing), it is only fitting that they should be
! represented by a single C type.  Almost all Python objects live on the
! heap: you never declare an automatic or static variable of type
  \ctype{PyObject}, only pointer variables of type \ctype{PyObject*} can 
! be declared.  The sole exception are the type objects\obindex{type};
! since these must never be deallocated, they are typically static
! \ctype{PyTypeObject} objects.
  
  All Python objects (even Python integers) have a \dfn{type} and a
***************
*** 1921,1927 ****
  object.
  
! More information on the buffer interface is provided in chapter
! \ref{newTypes}, under the description for
! \ctype{PyBufferProcs}\ttindex{PyBufferProcs}.
  
  A ``buffer object'' is defined in the \file{bufferobject.h} header
--- 1931,1937 ----
  object.
  
! More information on the buffer interface is provided in the section
! ``Buffer Object Structures'' (section \ref{buffer-structs}), under
! the description for \ctype{PyBufferProcs}\ttindex{PyBufferProcs}.
  
  A ``buffer object'' is defined in the \file{bufferobject.h} header
***************
*** 3569,3573 ****
  Note that in the three examples above, the buffer is always
  manipulated via functions/macros belonging to the same set. Indeed, it
! is highly recommended to use the same memory API family for a given
  memory block, so that the risk of mixing different allocators is
  reduced to a minimum. The following code sequence contains two errors,
--- 3579,3583 ----
  Note that in the three examples above, the buffer is always
  manipulated via functions/macros belonging to the same set. Indeed, it
! is required to use the same memory API family for a given
  memory block, so that the risk of mixing different allocators is
  reduced to a minimum. The following code sequence contains two errors,
***************
*** 3672,3678 ****
  
  The buffer interface exports a model where an object can expose its
! internal data as a set of chunks of data, each chunk specified as a
! pointer/length pair.  These chunks are called ``segments'' and are
! presumed to be non-contiguous in memory.
  
  If an object does not export the buffer interface, then its
--- 3682,3688 ----
  
  The buffer interface exports a model where an object can expose its
! internal data as a set of chunks of data, where each chunk is
! specified as a pointer/length pair.  These chunks are called
! \dfn{segments} and are presumed to be non-contiguous in memory.
  
  If an object does not export the buffer interface, then its
***************
*** 3681,3685 ****
  a \ctype{PyBufferProcs} structure.
  
! \emph{Note:} It is very important that your
  \ctype{PyTypeObject} structure uses \code{Py_TPFLAGS_DEFAULT} for the
  value of the \member{tp_flags} member rather than \code{0}.  This
--- 3691,3695 ----
  a \ctype{PyBufferProcs} structure.
  
! \strong{Note:} It is very important that your
  \ctype{PyTypeObject} structure uses \code{Py_TPFLAGS_DEFAULT} for the
  value of the \member{tp_flags} member rather than \code{0}.  This
***************
*** 3711,3716 ****
  The last slot is \member{bf_getcharbuffer}, of type
  \ctype{getcharbufferproc}.  This slot will only be present if the
! \code{Py_TPFLAGS_HAVE_GETCHARBUFFER} flag is present in
! \member{tp_flags} of the object's \ctype{PyTypeObject}.  Before using
  this slot, the caller should test whether it is present by using the
  \cfunction{PyType_HasFeature()}\ttindex{PyType_HasFeature()} function.
--- 3721,3726 ----
  The last slot is \member{bf_getcharbuffer}, of type
  \ctype{getcharbufferproc}.  This slot will only be present if the
! \code{Py_TPFLAGS_HAVE_GETCHARBUFFER} flag is present in the
! \member{tp_flags} field of the object's \ctype{PyTypeObject}.  Before using
  this slot, the caller should test whether it is present by using the
  \cfunction{PyType_HasFeature()}\ttindex{PyType_HasFeature()} function.
***************
*** 3726,3730 ****
  have character-based content.
  
! \emph{Note:} The current policy seems to state that these characters
  may be multi-byte characters. This implies that a buffer size of
  \var{N} does not mean there are \var{N} characters present.
--- 3736,3740 ----
  have character-based content.
  
! \strong{Note:} The current policy seems to state that these characters
  may be multi-byte characters. This implies that a buffer size of
  \var{N} does not mean there are \var{N} characters present.