Merged revisions 86537,86867-86868,86881,86887,86913-86915,86931-86933,86960,86964,86974,86980,86996,87008,87050 via svnmerge from

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

........
  r86537 | georg.brandl | 2010-11-19 23:09:04 +0100 (Fr, 19 Nov 2010) | 1 line

  Do not put a raw REPLACEMENT CHARACTER in the document.
........
  r86867 | georg.brandl | 2010-11-29 15:50:54 +0100 (Mo, 29 Nov 2010) | 1 line

  Fix indentation bug.
........
  r86868 | georg.brandl | 2010-11-29 15:53:15 +0100 (Mo, 29 Nov 2010) | 1 line

  Fix heading style inconsistencies.
........
  r86881 | georg.brandl | 2010-11-30 08:43:28 +0100 (Di, 30 Nov 2010) | 1 line

  #10584: fix bad links.
........
  r86887 | georg.brandl | 2010-11-30 15:57:54 +0100 (Di, 30 Nov 2010) | 1 line

  Fix typo.
........
  r86913 | georg.brandl | 2010-12-01 16:32:43 +0100 (Mi, 01 Dez 2010) | 1 line

  Add missing word, and add a better reference to the actual function.
........
  r86914 | georg.brandl | 2010-12-01 16:36:33 +0100 (Mi, 01 Dez 2010) | 1 line

  #10594: fix parameter names in PyList API docs.
........
  r86915 | georg.brandl | 2010-12-01 16:44:25 +0100 (Mi, 01 Dez 2010) | 1 line

  Fix some markup and style in the unittest docs.
........
  r86931 | georg.brandl | 2010-12-02 10:06:12 +0100 (Do, 02 Dez 2010) | 1 line

  Fix-up documentation of makedirs().
........
  r86932 | david.malcolm | 2010-12-02 17:41:00 +0100 (Do, 02 Dez 2010) | 2 lines

  Fix spelling of Jamie Zawinski's surname in urllib.parse docstring (issue 10606)
........
  r86933 | georg.brandl | 2010-12-02 19:02:01 +0100 (Do, 02 Dez 2010) | 1 line

  #10597: fix Py_SetPythonHome docs by pointing to where the meaning of PYTHONHOME is already documented.
........
  r86960 | georg.brandl | 2010-12-03 08:55:44 +0100 (Fr, 03 Dez 2010) | 1 line

  #10360: catch TypeError in WeakSet.__contains__, just like WeakKeyDictionary does.
........
  r86964 | georg.brandl | 2010-12-03 10:58:38 +0100 (Fr, 03 Dez 2010) | 1 line

  #10549: fix interface of docclass() for text documenter.
........
  r86974 | georg.brandl | 2010-12-03 16:30:09 +0100 (Fr, 03 Dez 2010) | 1 line

  Markup consistency fixes.
........
  r86980 | georg.brandl | 2010-12-03 18:19:27 +0100 (Fr, 03 Dez 2010) | 1 line

  Fix punctuation.
........
  r86996 | georg.brandl | 2010-12-03 20:56:42 +0100 (Fr, 03 Dez 2010) | 1 line

  Fix indentation.
........
  r87008 | georg.brandl | 2010-12-04 10:04:04 +0100 (Sa, 04 Dez 2010) | 1 line

  Fix typo.
........
  r87050 | georg.brandl | 2010-12-04 18:09:30 +0100 (Sa, 04 Dez 2010) | 1 line

  Fix typo.
........

11 files changed, 47 insertions, 46 deletions

diff --git a/Doc/c-api/init.rst b/Doc/c-api/init.rst
index 7f31df2..6786109 100644
--- a/Doc/c-api/init.rst
+++ b/Doc/c-api/init.rst
@@ -318,8 +318,9 @@ Process-wide parameters
 .. cfunction:: void Py_SetPythonHome(wchar_t *home)
 
    Set the default "home" directory, that is, the location of the standard
-   Python libraries.  The libraries are searched in
-   :file:`{home}/lib/python{version}` and :file:`{home}/lib/python{version}`.
+   Python libraries.  See :envvar:`PYTHONHOME` for the meaning of the
+   argument string.
+
    The argument should point to a zero-terminated character string in static
    storage whose contents will not change for the duration of the program's
    execution.  No code in the Python interpreter will change the contents of
diff --git a/Doc/c-api/list.rst b/Doc/c-api/list.rst
index dba0f81..4e3d500 100644
--- a/Doc/c-api/list.rst
+++ b/Doc/c-api/list.rst
@@ -37,7 +37,7 @@ List Objects
 
    .. note::
 
-      If *length* is greater than zero, the returned list object's items are
+      If *len* is greater than zero, the returned list object's items are
       set to ``NULL``.  Thus you cannot use abstract API functions such as
       :cfunc:`PySequence_SetItem`  or expose the object to Python code before
       setting all items to a real object with :cfunc:`PyList_SetItem`.
@@ -58,9 +58,9 @@ List Objects
 
 .. cfunction:: PyObject* PyList_GetItem(PyObject *list, Py_ssize_t index)
 
-   Return the object at position *pos* in the list pointed to by *p*.  The
+   Return the object at position *index* in the list pointed to by *list*.  The
    position must be positive, indexing from the end of the list is not
-   supported.  If *pos* is out of bounds, return *NULL* and set an
+   supported.  If *index* is out of bounds, return *NULL* and set an
    :exc:`IndexError` exception.
 
 
diff --git a/Doc/howto/unicode.rst b/Doc/howto/unicode.rst
index 03bed1e..13efa76 100644
--- a/Doc/howto/unicode.rst
+++ b/Doc/howto/unicode.rst
@@ -265,10 +265,13 @@ Unicode result).  The following examples show the differences::
     UnicodeDecodeError: 'utf8' codec can't decode byte 0x80 in position 0:
                         unexpected code byte
     >>> b'\x80abc'.decode("utf-8", "replace")
-    '\ufffdabc'
+    '?abc'
     >>> b'\x80abc'.decode("utf-8", "ignore")
     'abc'
 
+(In this code example, the Unicode replacement character has been replaced by
+a question mark because it may not be displayed on some systems.)
+
 Encodings are specified as strings containing the encoding's name.  Python 3.2
 comes with roughly 100 different encodings; see the Python Library Reference at
 :ref:`standard-encodings` for a list.  Some encodings have multiple names; for
diff --git a/Doc/library/dbm.rst b/Doc/library/dbm.rst
index 6872d79..6926ca6 100644
--- a/Doc/library/dbm.rst
+++ b/Doc/library/dbm.rst
@@ -20,7 +20,7 @@ the Oracle Berkeley DB.
 
 .. function:: whichdb(filename)
 
-   This functionattempts to guess which of the several simple database modules
+   This function attempts to guess which of the several simple database modules
    available --- :mod:`dbm.gnu`, :mod:`dbm.ndbm` or :mod:`dbm.dumb` --- should
    be used to open a given file.
 
diff --git a/Doc/library/difflib.rst b/Doc/library/difflib.rst
index 3fd44a6..6dea8c1 100644
--- a/Doc/library/difflib.rst
+++ b/Doc/library/difflib.rst
@@ -347,7 +347,6 @@ The :class:`SequenceMatcher` class has this constructor:
 
    :class:`SequenceMatcher` objects have the following methods:
 
-
    .. method:: set_seqs(a, b)
 
       Set the two sequences to be compared.
diff --git a/Doc/library/logging.rst b/Doc/library/logging.rst
index c977eb8..46b643f 100644
--- a/Doc/library/logging.rst
+++ b/Doc/library/logging.rst
@@ -473,9 +473,7 @@ libraries, then the logger name specified can be "orgname.foo" rather than
 just "foo".
 
 .. versionadded:: 3.1
-   The :class:`NullHandler` class was not present in previous versions, but is
-   now included, so that it need not be defined in library code.
-
+   The :class:`NullHandler` class.
 
 
 Logging Levels
@@ -593,8 +591,7 @@ provided:
    more information.
 
 .. versionadded:: 3.1
-
-The :class:`NullHandler` class was not present in previous versions.
+   The :class:`NullHandler` class.
 
 The :class:`NullHandler`, :class:`StreamHandler` and :class:`FileHandler`
 classes are defined in the core logging package. The other handlers are
@@ -1816,6 +1813,7 @@ sends logging output to a disk file.  It inherits the output functionality from
 
       Outputs the record to the file.
 
+
 .. _null-handler:
 
 NullHandler
@@ -1827,12 +1825,10 @@ The :class:`NullHandler` class, located in the core :mod:`logging` package,
 does not do any formatting or output. It is essentially a "no-op" handler
 for use by library developers.
 
-
 .. class:: NullHandler()
 
    Returns a new instance of the :class:`NullHandler` class.
 
-
    .. method:: emit(record)
 
       This method does nothing.
@@ -2609,6 +2605,7 @@ wire).
       Returns the message for this :class:`LogRecord` instance after merging any
       user-supplied arguments with the message.
 
+
 .. _logger-adapter:
 
 LoggerAdapter Objects
@@ -2616,22 +2613,21 @@ LoggerAdapter Objects
 
 :class:`LoggerAdapter` instances are used to conveniently pass contextual
 information into logging calls. For a usage example , see the section on
-`adding contextual information to your logging output`__.
+:ref:`adding contextual information to your logging output <context-info>`.
 
-__ context-info_
 
 .. class:: LoggerAdapter(logger, extra)
 
-  Returns an instance of :class:`LoggerAdapter` initialized with an
-  underlying :class:`Logger` instance and a dict-like object.
+   Returns an instance of :class:`LoggerAdapter` initialized with an
+   underlying :class:`Logger` instance and a dict-like object.
 
-  .. method:: process(msg, kwargs)
+   .. method:: process(msg, kwargs)
 
-    Modifies the message and/or keyword arguments passed to a logging call in
-    order to insert contextual information. This implementation takes the object
-    passed as *extra* to the constructor and adds it to *kwargs* using key
-    'extra'. The return value is a (*msg*, *kwargs*) tuple which has the
-    (possibly modified) versions of the arguments passed in.
+      Modifies the message and/or keyword arguments passed to a logging call in
+      order to insert contextual information. This implementation takes the object
+      passed as *extra* to the constructor and adds it to *kwargs* using key
+      'extra'. The return value is a (*msg*, *kwargs*) tuple which has the
+      (possibly modified) versions of the arguments passed in.
 
 In addition to the above, :class:`LoggerAdapter` supports all the logging
 methods of :class:`Logger`, i.e. :meth:`debug`, :meth:`info`, :meth:`warning`,
diff --git a/Doc/library/os.rst b/Doc/library/os.rst
index b8f1be2..bacb008 100644
--- a/Doc/library/os.rst
+++ b/Doc/library/os.rst
@@ -1015,7 +1015,7 @@ Files and Directories
    Availability: Unix, Windows.
 
 
-.. function:: makedirs(path[, mode])
+.. function:: makedirs(path, mode=0o777)
 
    .. index::
       single: directory; creating
@@ -1029,8 +1029,8 @@ Files and Directories
 
    .. note::
 
-      :func:`makedirs` will become confused if the path elements to create include
-      :data:`os.pardir`.
+      :func:`makedirs` will become confused if the path elements to create
+      include :data:`pardir`.
 
    This function handles UNC paths correctly.
 
diff --git a/Doc/library/pickle.rst b/Doc/library/pickle.rst
index 8a671a7..1850b00 100644
--- a/Doc/library/pickle.rst
+++ b/Doc/library/pickle.rst
@@ -42,7 +42,7 @@ general :mod:`pickle` should always be the preferred way to serialize Python
 objects.  :mod:`marshal` exists primarily to support Python's :file:`.pyc`
 files.
 
-The :mod:`pickle` module differs from :mod:`marshal` several significant ways:
+The :mod:`pickle` module differs from :mod:`marshal` in several significant ways:
 
 * The :mod:`pickle` module keeps track of the objects it has already serialized,
   so that later references to the same object won't be serialized again.
diff --git a/Doc/library/urllib.request.rst b/Doc/library/urllib.request.rst
index ccd946b..b617df4 100644
--- a/Doc/library/urllib.request.rst
+++ b/Doc/library/urllib.request.rst
@@ -1,4 +1,4 @@
-:mod:`urllib.request` --- extensible library for opening URLs
+:mod:`urllib.request` --- Extensible library for opening URLs
 =============================================================
 
 .. module:: urllib.request
@@ -299,18 +299,19 @@ The following classes are provided:
       users for the required information on the controlling terminal.  A subclass may
       override this method to support more appropriate behavior if needed.
 
-    The :class:`FancyURLopener` class offers one additional method that should be
-    overloaded to provide the appropriate behavior:
+   The :class:`FancyURLopener` class offers one additional method that should be
+   overloaded to provide the appropriate behavior:
 
-    .. method:: prompt_user_passwd(host, realm)
+   .. method:: prompt_user_passwd(host, realm)
 
-       Return information needed to authenticate the user at the given host in the
-       specified security realm.  The return value should be a tuple, ``(user,
-       password)``, which can be used for basic authentication.
+      Return information needed to authenticate the user at the given host in the
+      specified security realm.  The return value should be a tuple, ``(user,
+      password)``, which can be used for basic authentication.
+
+      The implementation prompts for this information on the terminal; an application
+      should override this method to use an appropriate interaction model in the local
+      environment.
 
-       The implementation prompts for this information on the terminal; an application
-       should override this method to use an appropriate interaction model in the local
-       environment.
 
 .. class:: OpenerDirector()
 
@@ -1249,8 +1250,8 @@ The following example uses no proxies at all, overriding environment settings::
 
 
 
-:mod:`urllib.response` --- Response classes used by urllib.
-===========================================================
+:mod:`urllib.response` --- Response classes used by urllib
+==========================================================
 
 .. module:: urllib.response
    :synopsis: Response classes used by urllib.
diff --git a/Doc/library/zipfile.rst b/Doc/library/zipfile.rst
index 346af16..827b6b1 100644
--- a/Doc/library/zipfile.rst
+++ b/Doc/library/zipfile.rst
@@ -163,8 +163,8 @@ ZipFile Objects
    .. note::
 
       The file-like object is read-only and provides the following methods:
-      :meth:`read`, :meth:`readline`, :meth:`readlines`, :meth:`__iter__`,
-      :meth:`__next__`.
+      :meth:`!read`, :meth:`!readline`, :meth:`!readlines`, :meth:`!__iter__`,
+      :meth:`!__next__`.
 
    .. note::
 
diff --git a/Doc/reference/expressions.rst b/Doc/reference/expressions.rst
index 27bcfab..944c39f 100644
--- a/Doc/reference/expressions.rst
+++ b/Doc/reference/expressions.rst
@@ -1318,8 +1318,8 @@ groups from right to left).
    true numerically due to roundoff.  For example, and assuming a platform on which
    a Python float is an IEEE 754 double-precision number, in order that ``-1e-100 %
    1e100`` have the same sign as ``1e100``, the computed result is ``-1e-100 +
-   1e100``, which is numerically exactly equal to ``1e100``.  Function :func:`fmod`
-   in the :mod:`math` module returns a result whose sign matches the sign of the
+   1e100``, which is numerically exactly equal to ``1e100``.  The function
+   :func:`math.fmod` returns a result whose sign matches the sign of the
    first argument instead, and so returns ``-1e-100`` in this case. Which approach
    is more appropriate depends on the application.
 
@@ -1340,7 +1340,8 @@ groups from right to left).
    the :keyword:`is` operator, like those involving comparisons between instance
    methods, or constants.  Check their documentation for more info.
 
-.. [#] The ``%`` is also used for string formatting; the same precedence applies.
+.. [#] The ``%`` operator is also used for string formatting; the same
+   precedence applies.
 
 .. [#] The power operator ``**`` binds less tightly than an arithmetic or
    bitwise unary operator on its right, that is, ``2**-1`` is ``0.5``.