[Python-checkins] r56481 - peps/trunk/pep-3123.txt

[georg.brandl]

Author: georg.brandl
Date: Sat Jul 21 11:18:45 2007
New Revision: 56481

Modified:
   peps/trunk/pep-3123.txt
Log:
Minor fixes and markup.


Modified: peps/trunk/pep-3123.txt
==============================================================================
--- peps/trunk/pep-3123.txt	(original)
+++ peps/trunk/pep-3123.txt	Sat Jul 21 11:18:45 2007
@@ -14,7 +14,7 @@
 ========
 
 Python currently relies on undefined C behavior, with its
-usage of PyObject_HEAD. This PEP proposes to change that
+usage of ``PyObject_HEAD``. This PEP proposes to change that
 into standard C.
 
 Rationale
@@ -43,18 +43,18 @@
   }
 
 The problem here is that the storage is both accessed as
-if it where struct PyObject, and as struct FooObject.
+if it where struct ``PyObject``, and as struct ``FooObject``.
 
 Historically, compilers did not have any problems with this
 code. However, modern compilers use that clause as an 
-optimization opportunity, finding that f->ob_refcnt and
-o->ob_refcnt cannot possibly refer to the same memory, and
+optimization opportunity, finding that ``f->ob_refcnt`` and
+``o->ob_refcnt`` cannot possibly refer to the same memory, and
 that therefore the function should return 0, without having
 to fetch the value of ob_refcnt at all in the return
-statement. For GCC, Python now uses -fno-strict-aliasing
+statement. For GCC, Python now uses ``-fno-strict-aliasing``
 to work around that problem; with other compilers, it
 may just see undefined behavior. Even with GCC, using
--fno-strict-aliasing may pessimize the generated code
+``-fno-strict-aliasing`` may pessimize the generated code
 unnecessarily.
 
 Specification
@@ -63,12 +63,12 @@
 Standard C has one specific exception to its aliasing rules precisely
 designed to support the case of Python: a value of a struct type may
 also be accessed through a pointer to the first field. E.g. if a
-struct starts with an int, the struct\* may also be cast to an int\*,
-allowing to write int values into the first field.
+struct starts with an ``int``, the ``struct *`` may also be cast to
+an ``int *``, allowing to write int values into the first field.
 
-For Python, PyObject_HEAD and PyObject_VAR_HEAD will be changed
+For Python, ``PyObject_HEAD`` and ``PyObject_VAR_HEAD`` will be changed
 to not list all fields anymore, but list a single field of type
-PyObject/PyVarObject::
+``PyObject``/``PyVarObject``::
 
   typedef struct _object {
     _PyObject_HEAD_EXTRA
@@ -92,14 +92,14 @@
     PyObject *start, *stop, *step;
   } PySliceObject;
 
-  typedef struct{
+  typedef struct {
     PyVarObject ob_base;
     PyObject **ob_item;
     Py_ssize_t allocated;
   } PyListObject;
 
-The above definitions of PyObject_HEAD is normative, so extension
-authors MAY either use the macro, or put the ob_base field explicitly
+The above definitions of ``PyObject_HEAD`` are normative, so extension
+authors MAY either use the macro, or put the ``ob_base`` field explicitly
 into their structs.
 
 As a convention, the base field SHOULD be called ob_base. However, all
@@ -112,7 +112,7 @@
   #define Py_Refcnt(o)  (((PyObject*)(o))->ob_refcnt)
   #define Py_Size(o)    (((PyVarObject*)(o))->ob_size)
 
-are added. E.g. the code blocks::
+are added. E.g. the code blocks ::
 
   #define PyList_CheckExact(op) ((op)->ob_type == &PyList_Type)
 
@@ -124,12 +124,12 @@
 
   return Py_Type(func)->tp_name;
 
-For initialization of type objects, the current sequence::
+For initialization of type objects, the current sequence ::
 
   PyObject_HEAD_INIT(NULL)
   0, /* ob_size */
 
-becomes incorrect, and must be replaced with
+becomes incorrect, and must be replaced with ::
 
   PyVarObject_HEAD_INIT(NULL, 0)
 
@@ -137,9 +137,9 @@
 =============================
 
 To support modules that compile with both Python 2.6 and Python 3.0,
-the Py_* macros is added to Python 2.6. The macros Py_INCREF
-and Py_DECREF will be changed to cast their argument to PyObject\*,
-so that module authors can also explicitly declare the ob_base
+the ``Py_*`` macros are added to Python 2.6. The macros ``Py_INCREF``
+and ``Py_DECREF`` will be changed to cast their argument to ``PyObject *``,
+so that module authors can also explicitly declare the ``ob_base``
 field in modules designed for Python 2.6. 
 
 Copyright