Merged revisions 87188-87190,87192-87194 via svnmerge from

svn+ssh://pythondev@svn.python.org/python/branches/py3k

........
  r87188 | antoine.pitrou | 2010-12-12 19:25:25 +0100 (dim., 12 déc. 2010) | 3 lines

  Make this a warning and fix indentation
........
  r87189 | antoine.pitrou | 2010-12-12 20:59:47 +0100 (dim., 12 déc. 2010) | 3 lines

  Better explain the buffer interface (hopefully)
........
  r87190 | antoine.pitrou | 2010-12-12 21:01:43 +0100 (dim., 12 déc. 2010) | 3 lines

  Add link to the buffer protocol description from the memory description.
........
  r87192 | antoine.pitrou | 2010-12-12 21:09:18 +0100 (dim., 12 déc. 2010) | 3 lines

  Remove redundant sentence, and fix markup
........
  r87193 | antoine.pitrou | 2010-12-12 21:13:31 +0100 (dim., 12 déc. 2010) | 3 lines

  Fix heading level
........
  r87194 | antoine.pitrou | 2010-12-12 21:17:29 +0100 (dim., 12 déc. 2010) | 3 lines

  Consistent ordering of availability statements
........

5 files changed, 40 insertions, 33 deletions

diff --git a/Doc/c-api/buffer.rst b/Doc/c-api/buffer.rst
index ad6e3937..e6eff84 100644
--- a/Doc/c-api/buffer.rst
+++ b/Doc/c-api/buffer.rst
@@ -12,16 +12,32 @@ Buffer Protocol
 .. index::
    single: buffer interface
 
-Python objects implemented in C can export a "buffer interface."  These
-functions can be used by an object to expose its data in a raw, byte-oriented
-format. Clients of the object can use the buffer interface to access the
-object data directly, without needing to copy it first.
+Certain objects available in Python wrap access to an underlying memory
+array or *buffer*.  Such objects include the built-in :class:`bytes` and
+:class:`bytearray`, and some extension types like :class:`array.array`.
+Third-party libraries may define their own types for special purposes, such
+as image processing or numeric analysis.
 
-Examples of objects that support the buffer interface are :class:`bytes`,
-:class:`bytearray` and :class:`array.array`. The bytes and bytearray objects
-exposes their bytes contents in the buffer interface's byte-oriented form.
-An :class:`array.array` can also expose its contents, but it should be noted
-that array elements may be multi-byte values.
+While each of these types have their own semantics, they share the common
+characteristic of being backed by a possibly large memory buffer.  It is
+then desireable, in some situations, to access that buffer directly and
+without intermediate copying.
+
+Python provides such a facility at the C level in the form of the *buffer
+protocol*.  This protocol has two sides:
+
+.. index:: single: PyBufferProcs
+
+- on the producer side, a type can export a "buffer interface" which allows
+  objects of that type to expose information about their underlying buffer.
+  This interface is described in the section :ref:`buffer-structs`;
+
+- on the consumer side, several means are available to obtain a pointer to
+  the raw underlying data of an object (for example a method parameter).
+
+Simple objects such as :class:`bytes` and :class:`bytearray` expose their
+underlying buffer in byte-oriented form.  Other forms are possible; for example,
+the elements exposed by a :class:`array.array` can be multi-byte values.
 
 An example consumer of the buffer interface is the :meth:`~io.BufferedIOBase.write`
 method of file objects: any object that can export a series of bytes through
@@ -44,12 +60,6 @@ isn't needed anymore.  Failure to do so could lead to various issues such as
 resource leaks.
 
 
-.. index:: single: PyBufferProcs
-
-How the buffer interface is exposed by a type object is described in the
-section :ref:`buffer-structs`, under the description for :ctype:`PyBufferProcs`.
-
-
 The buffer structure
 ====================
 
diff --git a/Doc/c-api/typeobj.rst b/Doc/c-api/typeobj.rst
index eb8a83e..ab55292 100644
--- a/Doc/c-api/typeobj.rst
+++ b/Doc/c-api/typeobj.rst
@@ -1193,7 +1193,7 @@ Buffer Object Structures
 .. sectionauthor:: Benjamin Peterson
 
 
-The buffer interface exports a model where an object can expose its internal
+The :ref:`buffer interface <bufferobjects>` exports a model where an object can expose its internal
 data.
 
 If an object does not export the buffer interface, then its :attr:`tp_as_buffer`
diff --git a/Doc/library/os.path.rst b/Doc/library/os.path.rst
index fdc45b9..28a7aff 100644
--- a/Doc/library/os.path.rst
+++ b/Doc/library/os.path.rst
@@ -227,7 +227,7 @@ applications should use string objects to access all files.
 
    *start* defaults to :attr:`os.curdir`.
 
-   Availability:  Windows, Unix.
+   Availability: Unix, Windows.
 
 
 .. function:: samefile(path1, path2)
diff --git a/Doc/library/stdtypes.rst b/Doc/library/stdtypes.rst
index 4b7ae39..f2563dd 100644
--- a/Doc/library/stdtypes.rst
+++ b/Doc/library/stdtypes.rst
@@ -2081,9 +2081,9 @@ An example of dictionary view usage::
 memoryview Types
 ================
 
-:class:`memoryview`\s allow Python code to access the internal data of an object
-that supports the buffer protocol without copying.  Memory can be interpreted as
-simple bytes or complex data structures.
+:class:`memoryview` objects allow Python code to access the internal data
+of an object that supports the :ref:`buffer protocol <bufferobjects>` without
+copying.  Memory is generally interpreted as simple bytes.
 
 .. class:: memoryview(obj)
 
@@ -2203,12 +2203,9 @@ Context Manager Types
    single: protocol; context management
 
 Python's :keyword:`with` statement supports the concept of a runtime context
-defined by a context manager.  This is implemented using two separate methods
+defined by a context manager.  This is implemented using a pair of methods
 that allow user-defined classes to define a runtime context that is entered
-before the statement body is executed and exited when the statement ends.
-
-The :dfn:`context management protocol` consists of a pair of methods that need
-to be provided for a context manager object to define a runtime context:
+before the statement body is executed and exited when the statement ends:
 
 
 .. method:: contextmanager.__enter__()
@@ -2256,9 +2253,9 @@ decimal arithmetic context. The specific types are not treated specially beyond
 their implementation of the context management protocol. See the
 :mod:`contextlib` module for some examples.
 
-Python's :term:`generator`\s and the ``contextlib.contextmanager`` :term:`decorator`
+Python's :term:`generator`\s and the :class:`contextlib.contextmanager` decorator
 provide a convenient way to implement these protocols.  If a generator function is
-decorated with the ``contextlib.contextmanager`` decorator, it will return a
+decorated with the :class:`contextlib.contextmanager` decorator, it will return a
 context manager implementing the necessary :meth:`__enter__` and
 :meth:`__exit__` methods, rather than the iterator produced by an undecorated
 generator function.
diff --git a/Doc/library/test.rst b/Doc/library/test.rst
index 0b16109..ecb2e5c 100644
--- a/Doc/library/test.rst
+++ b/Doc/library/test.rst
@@ -5,12 +5,12 @@
    :synopsis: Regression tests package containing the testing suite for Python.
 .. sectionauthor:: Brett Cannon <brett@python.org>
 
-.. note::
-    The :mod:`test` package is meant for internal use by Python only. It is
-    documented for the benefit of the core developers of Python. Any use of
-    this package outside of Python's standard library is discouraged as code
-    mentioned here can change or be removed without notice between releases of
-    Python.
+.. warning::
+   The :mod:`test` package is meant for internal use by Python only. It is
+   documented for the benefit of the core developers of Python. Any use of
+   this package outside of Python's standard library is discouraged as code
+   mentioned here can change or be removed without notice between releases of
+   Python.
 
 
 The :mod:`test` package contains all regression tests for Python as well as the