Add explanation about 2-d C-arrays and multi-dimensional elements in example of struct syntax.

pep-3118.txt

@@ -68,7 +68,7 @@ has issues:
    There are two widely used libraries that use the concept of
    discontiguous memory: PIL and NumPy.  Their view of discontiguous
    arrays is different, though.  The proposed buffer interface allows
-   sharing of either memory model.  Exporters will use only one        
+   sharing of either memory model.  Exporters will typically use only one        
    approach and consumers may choose to support discontiguous 
    arrays of each type however they choose. 
 
@@ -228,7 +228,7 @@ without that information, then a ``PyErr_BufferError`` should be raised.
    checking for what 'kind' of data is actually stored.  An exporter
    should always be able to provide this information if requested.  If
    format is not explicitly requested then the format must be returned
-   as ``NULL`` (which means "B")
+   as ``NULL`` (which means "B", or unsigned bytes)
 
 ``PyBUF_ND``
 
@@ -322,8 +322,8 @@ The bufferinfo structure is::
        void *internal;
   } Py_buffer;
 
-Before calling this function, the bufferinfo structure can be filled
-with whatever.  Upon return from getbufferproc, the bufferinfo
+Before calling the bf_getbuffer function, the bufferinfo structure can be 
+filled with whatever.  Upon return from bf_getbuffer, the bufferinfo
 structure is filled in with relevant information about the buffer.
 This same bufferinfo structure must be passed to bf_releasebuffer (if
 available) when the consumer is done with the memory. The caller is
@@ -453,10 +453,10 @@ Py_buffer structure itself.
 
     Both of these routines are optional for a type object
 
-    If the releasebuffer function is not provided then it does not ever
-    need to be called. 
+    If the bf_releasebuffer function is not provided (i.e. it is NULL),
+    then it does not ever need to be called. 
     
-Exporters will need to define a releasebuffer function if they can
+Exporters will need to define a bf_releasebuffer function if they can
 re-allocate their memory, strides, shape, suboffsets, or format
 variables which they might share through the struct bufferinfo.
 Several mechanisms could be used to keep track of how many getbuffer
@@ -520,7 +520,7 @@ reference to base is kept and the memory view is not re-grabbed.
 Thus, this memory view object holds on to the memory of base until it
 is deleted.
 
-The getbuffer and releasebuffer for this object increments and
+The bf_getbuffer and bf_releasebuffer for this object increments and
 decrements the lock on base, but passes on the contents of view to the
 caller.
 
@@ -772,6 +772,24 @@ Nested array
            (16,4)d:data:
         """
 
+Note, that in the last example, the C-structure compared against is
+intentionally a 1-d array and not a 2-d array data[16][4].  The reason
+for this is to avoid the confusions between static multi-dimensional
+arrays in C (which are layed out contiguously) and dynamic
+multi-dimensional arrays which use the same syntax to access elements,
+data[0][1], but whose memory is not necessarily contiguous.  The
+struct-syntax *always* uses contiguous memory and the
+multi-dimensional character is information about the memory to be
+communicated by the exporter.  
+
+In other words, the struct-syntax description does not have to match
+the C-syntax exactly as long as it describes the same memory layout.
+The fact that a C-compiler would think of the memory as a 1-d array of
+doubles is irrelevant to the fact that the exporter wanted to
+communicate to the consumer that this field of the memory should be
+thought of as a 2-d array where a new dimension is considered after
+every 4 elements. 
+
 
 Code to be affected
 ===================
@@ -813,7 +831,7 @@ because strided memory is very common when interfacing with compute
 libraries.
 
 Also, with this approach it should be possible to write generic code
-that works with both kinds of memory.
+that works with both kinds of memory without copying. 
 
 Memory management of the format string, the shape array, the strides
 array, and the suboffsets array in the bufferinfo structure is always