Merged revisions 75797 via svnmerge from

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

................
  r75797 | georg.brandl | 2009-10-27 16:28:25 +0100 (Di, 27 Okt 2009) | 129 lines

  Merged revisions 75365,75394,75402-75403,75418,75459,75484,75592-75596,75600,75602-75607,75610-75613,75616-75617,75623,75627,75640,75647,75696,75795 via svnmerge from
  svn+ssh://pythondev@svn.python.org/python/trunk

  ........
    r75365 | georg.brandl | 2009-10-11 22:16:16 +0200 (So, 11 Okt 2009) | 1 line

    Fix broken links found by "make linkcheck".  scipy.org seems to be done right now, so I could not verify links going there.
  ........
    r75394 | georg.brandl | 2009-10-13 20:10:59 +0200 (Di, 13 Okt 2009) | 1 line

    Fix markup.
  ........
    r75402 | georg.brandl | 2009-10-14 17:51:48 +0200 (Mi, 14 Okt 2009) | 1 line

    #7125: fix typo.
  ........
    r75403 | georg.brandl | 2009-10-14 17:57:46 +0200 (Mi, 14 Okt 2009) | 1 line

    #7126: os.environ changes *do* take effect in subprocesses started with os.system().
  ........
    r75418 | georg.brandl | 2009-10-14 20:48:32 +0200 (Mi, 14 Okt 2009) | 1 line

    #7116: str.join() takes an iterable.
  ........
    r75459 | georg.brandl | 2009-10-17 10:57:43 +0200 (Sa, 17 Okt 2009) | 1 line

    Fix refleaks in _ctypes PyCSimpleType_New, which fixes the refleak seen in test___all__.
  ........
    r75484 | georg.brandl | 2009-10-18 09:58:12 +0200 (So, 18 Okt 2009) | 1 line

    Fix missing word.
  ........
    r75592 | georg.brandl | 2009-10-22 09:05:48 +0200 (Do, 22 Okt 2009) | 1 line

    Fix punctuation.
  ........
    r75593 | georg.brandl | 2009-10-22 09:06:49 +0200 (Do, 22 Okt 2009) | 1 line

    Revert unintended change.
  ........
    r75594 | georg.brandl | 2009-10-22 09:56:02 +0200 (Do, 22 Okt 2009) | 1 line

    Fix markup.
  ........
    r75595 | georg.brandl | 2009-10-22 09:56:56 +0200 (Do, 22 Okt 2009) | 1 line

    Fix duplicate target.
  ........
    r75596 | georg.brandl | 2009-10-22 10:05:04 +0200 (Do, 22 Okt 2009) | 1 line

    Add a new directive marking up implementation details and start using it.
  ........
    r75600 | georg.brandl | 2009-10-22 13:01:46 +0200 (Do, 22 Okt 2009) | 1 line

    Make it more robust.
  ........
    r75602 | georg.brandl | 2009-10-22 13:28:06 +0200 (Do, 22 Okt 2009) | 1 line

    Document new directive.
  ........
    r75603 | georg.brandl | 2009-10-22 13:28:23 +0200 (Do, 22 Okt 2009) | 1 line

    Allow short form with text as argument.
  ........
    r75604 | georg.brandl | 2009-10-22 13:36:50 +0200 (Do, 22 Okt 2009) | 1 line

    Fix stylesheet for multi-paragraph impl-details.
  ........
    r75605 | georg.brandl | 2009-10-22 13:48:10 +0200 (Do, 22 Okt 2009) | 1 line

    Use "impl-detail" directive where applicable.
  ........
    r75606 | georg.brandl | 2009-10-22 17:00:06 +0200 (Do, 22 Okt 2009) | 1 line

    #6324: membership test tries iteration via __iter__.
  ........
    r75607 | georg.brandl | 2009-10-22 17:04:09 +0200 (Do, 22 Okt 2009) | 1 line

    #7088: document new functions in signal as Unix-only.
  ........
    r75610 | georg.brandl | 2009-10-22 17:27:24 +0200 (Do, 22 Okt 2009) | 1 line

    Reorder __slots__ fine print and add a clarification.
  ........
    r75611 | georg.brandl | 2009-10-22 17:42:32 +0200 (Do, 22 Okt 2009) | 1 line

    #7035: improve docs of the various <method>_errors() functions, and give them docstrings.
  ........
    r75612 | georg.brandl | 2009-10-22 17:52:15 +0200 (Do, 22 Okt 2009) | 1 line

    #7156: document curses as Unix-only.
  ........
    r75613 | georg.brandl | 2009-10-22 17:54:35 +0200 (Do, 22 Okt 2009) | 1 line

    #6977: getopt does not support optional option arguments.
  ........
    r75616 | georg.brandl | 2009-10-22 18:17:05 +0200 (Do, 22 Okt 2009) | 1 line

    Add proper references.
  ........
    r75617 | georg.brandl | 2009-10-22 18:20:55 +0200 (Do, 22 Okt 2009) | 1 line

    Make printout margin important.
  ........
    r75623 | georg.brandl | 2009-10-23 10:14:44 +0200 (Fr, 23 Okt 2009) | 1 line

    #7188: fix optionxform() docs.
  ........
    r75627 | fred.drake | 2009-10-23 15:04:51 +0200 (Fr, 23 Okt 2009) | 2 lines

    add further note about what's passed to optionxform
  ........
    r75640 | neil.schemenauer | 2009-10-23 21:58:17 +0200 (Fr, 23 Okt 2009) | 2 lines

    Improve some docstrings in the 'warnings' module.
  ........
    r75647 | georg.brandl | 2009-10-24 12:04:19 +0200 (Sa, 24 Okt 2009) | 1 line

    Fix markup.
  ........
    r75696 | georg.brandl | 2009-10-25 21:25:43 +0100 (So, 25 Okt 2009) | 1 line

    Fix a demo.
  ........
    r75795 | georg.brandl | 2009-10-27 16:10:22 +0100 (Di, 27 Okt 2009) | 1 line

    Fix a strange mis-edit.
  ........
................

44 files changed, 334 insertions, 215 deletions

diff --git a/Doc/distutils/apiref.rst b/Doc/distutils/apiref.rst
index af19111..cdb32d3 100644
--- a/Doc/distutils/apiref.rst
+++ b/Doc/distutils/apiref.rst
@@ -1976,9 +1976,9 @@ it so that it's implementing the class :class:`peel_banana`, a subclass of
 Subclasses of :class:`Command` must define the following methods.
 
 
-.. method:: Command.initialize_options()(S)
+.. method:: Command.initialize_options()
 
-   et default values for all the options that this command supports.  Note that
+   Set default values for all the options that this command supports.  Note that
    these defaults may be overridden by other commands, by the setup script, by
    config files, or by the command-line.  Thus, this is not the place to code
    dependencies between options; generally, :meth:`initialize_options`
diff --git a/Doc/documenting/markup.rst b/Doc/documenting/markup.rst
index 421971a..eed51d2 100644
--- a/Doc/documenting/markup.rst
+++ b/Doc/documenting/markup.rst
@@ -626,6 +626,24 @@ units as well as normal text:
 
 --------------
 
+.. describe:: impl-detail
+
+   This directive is used to mark CPython-specific information.  Use either with
+   a block content or a single sentence as an argument, i.e. either ::
+
+      .. impl-detail::
+
+         This describes some implementation detail.
+
+         More explanation.
+
+   or ::
+
+      .. impl-detail:: This shortly mentions an implementation detail.
+
+   "\ **CPython implementation detail:**\ " is automatically prepended to the
+   content.
+
 .. describe:: seealso
 
    Many sections include a list of references to module documentation or
diff --git a/Doc/faq/design.rst b/Doc/faq/design.rst
index aacb476..94afaff 100644
--- a/Doc/faq/design.rst
+++ b/Doc/faq/design.rst
@@ -396,12 +396,13 @@ calls into the Python run-time system, even for seemingly simple operations like
 ``x+1``.
 
 Several projects described in the Python newsgroup or at past `Python
-conferences <http://python.org/community/workshops/>`_ have shown that this approach is feasible,
-although the speedups reached so far are only modest (e.g. 2x).  Jython uses the
-same strategy for compiling to Java bytecode.  (Jim Hugunin has demonstrated
-that in combination with whole-program analysis, speedups of 1000x are feasible
-for small demo programs.  See the proceedings from the `1997 Python conference
-<http://python.org/community/workshops/1997-10/proceedings/>`_ for more information.)
+conferences <http://python.org/community/workshops/>`_ have shown that this
+approach is feasible, although the speedups reached so far are only modest
+(e.g. 2x).  Jython uses the same strategy for compiling to Java bytecode.  (Jim
+Hugunin has demonstrated that in combination with whole-program analysis,
+speedups of 1000x are feasible for small demo programs.  See the proceedings
+from the `1997 Python conference
+<http://python.org/workshops/1997-10/proceedings/>`_ for more information.)
 
 Internally, Python source code is always translated into a bytecode
 representation, and this bytecode is then executed by the Python virtual
diff --git a/Doc/faq/extending.rst b/Doc/faq/extending.rst
index 3389877..f01b0a0 100644
--- a/Doc/faq/extending.rst
+++ b/Doc/faq/extending.rst
@@ -48,7 +48,7 @@ Python's C API.
 If you need to interface to some C or C++ library for which no Python extension
 currently exists, you can try wrapping the library's data types and functions
 with a tool such as `SWIG <http://www.swig.org>`_.  `SIP
-<http://www.riverbankcomputing.co.uk/sip/>`_, `CXX
+<http://www.riverbankcomputing.co.uk/software/sip/>`__, `CXX
 <http://cxx.sourceforge.net/>`_ `Boost
 <http://www.boost.org/libs/python/doc/index.html>`_, or `Weave
 <http://www.scipy.org/site_content/weave>`_ are also alternatives for wrapping
diff --git a/Doc/faq/general.rst b/Doc/faq/general.rst
index 758c26e..67935f4 100644
--- a/Doc/faq/general.rst
+++ b/Doc/faq/general.rst
@@ -164,9 +164,10 @@ Sphinx-formatted documentation, Python library modules, example programs, and
 several useful pieces of freely distributable software.  The source will compile
 and run out of the box on most UNIX platforms.
 
-Consult the `Developer FAQ
-<http://www.python.org/dev/devfaq.html#subversion-svn>`__ for more information
-on getting the source code and compiling it.
+.. XXX update link once the dev faq is relocated
+
+Consult the `Developer FAQ <http://www.python.org/dev/faq/>`__ for more
+information on getting the source code and compiling it.
 
 
 How do I get documentation on Python?
@@ -176,7 +177,7 @@ How do I get documentation on Python?
 
 The standard documentation for the current stable version of Python is available
 at http://docs.python.org/.  PDF, plain text, and downloadable HTML versions are
-also available at http://docs.python.org/download/.
+also available at http://docs.python.org/download.html.
 
 The documentation is written in reStructuredText and processed by `the Sphinx
 documentation tool <http://sphinx.pocoo.org/>`__.  The reStructuredText source
@@ -220,8 +221,10 @@ releases are announced on the comp.lang.python and comp.lang.python.announce
 newsgroups and on the Python home page at http://www.python.org/; an RSS feed of
 news is available.
 
+.. XXX update link once the dev faq is relocated
+
 You can also access the development version of Python through Subversion.  See
-http://www.python.org/dev/devfaq.html#subversion-svn for details.
+http://www.python.org/dev/faq/ for details.
 
 
 How do I submit bug reports and patches for Python?
diff --git a/Doc/faq/gui.rst b/Doc/faq/gui.rst
index d3cf779..4761b7d 100644
--- a/Doc/faq/gui.rst
+++ b/Doc/faq/gui.rst
@@ -45,11 +45,12 @@ Qt
 '''
 
 There are bindings available for the Qt toolkit (`PyQt
-<http://www.riverbankcomputing.co.uk/pyqt/>`_) and for KDE (PyKDE).  If you're
-writing open source software, you don't need to pay for PyQt, but if you want to
-write proprietary applications, you must buy a PyQt license from `Riverbank
-Computing <http://www.riverbankcomputing.co.uk>`_ and a Qt license from
-`Trolltech <http://www.trolltech.com>`_.
+<http://www.riverbankcomputing.co.uk/software/pyqt/>`_) and for KDE (PyKDE).  If
+you're writing open source software, you don't need to pay for PyQt, but if you
+want to write proprietary applications, you must buy a PyQt license from
+`Riverbank Computing <http://www.riverbankcomputing.co.uk>`_ and (up to Qt 4.4;
+Qt 4.5 upwards is licensed under the LGPL license) a Qt license from `Trolltech
+<http://www.trolltech.com>`_.
 
 Gtk+
 ''''
diff --git a/Doc/faq/library.rst b/Doc/faq/library.rst
index db69449..88fcf0e 100644
--- a/Doc/faq/library.rst
+++ b/Doc/faq/library.rst
@@ -16,14 +16,10 @@ Check :ref:`the Library Reference <library-index>` to see if there's a relevant
 standard library module.  (Eventually you'll learn what's in the standard
 library and will able to skip this step.)
 
-Search the `Python Package Index <http://pypi.python.org/pypi>`_.
-
-Next, check the `Vaults of Parnassus <http://www.vex.net/parnassus/>`_, an older
-index of packages.
-
-Finally, try `Google <http://www.google.com>`_ or other Web search engine.
-Searching for "Python" plus a keyword or two for your topic of interest will
-usually find something helpful.
+For third-party packages, search the `Python Package Index
+<http://pypi.python.org/pypi>`_ or try `Google <http://www.google.com>`_ or
+another Web search engine.  Searching for "Python" plus a keyword or two for
+your topic of interest will usually find something helpful.
 
 
 Where is the math.py (socket.py, regex.py, etc.) source file?
@@ -181,11 +177,10 @@ in Python.
 How do I create documentation from doc strings?
 -----------------------------------------------
 
-.. XXX mention Sphinx/epydoc
-
 The :mod:`pydoc` module can create HTML from the doc strings in your Python
-source code.  An alternative is `pythondoc
-<http://starship.python.net/crew/danilo/pythondoc/>`_.
+source code.  An alternative for creating API documentation purely from
+docstrings is `epydoc <http://epydoc.sf.net/>`_.  `Sphinx
+<http://sphinx.pocoo.org>`_ can also include docstring content.
 
 
 How do I get a single keypress at a time?
@@ -237,7 +232,7 @@ The :mod:`threading` module builds convenient abstractions on top of the
 low-level primitives provided by the :mod:`_thread` module.
 
 Aahz has a set of slides from his threading tutorial that are helpful; see
-http://starship.python.net/crew/aahz/OSCON2001/.
+http://www.pythoncraft.com/OSCON2001/.
 
 
 None of my threads seem to run: why?
@@ -397,6 +392,7 @@ Can't we get rid of the Global Interpreter Lock?
 ------------------------------------------------
 
 .. XXX mention multiprocessing
+.. XXX link to dbeazley's talk about GIL?
 
 The Global Interpreter Lock (GIL) is often seen as a hindrance to Python's
 deployment on high-end multiprocessor server machines, because a multi-threaded
@@ -583,7 +579,7 @@ substituted for standard input and output.  You will have to use pseudo ttys
 ("ptys") instead of pipes. Or you can use a Python interface to Don Libes'
 "expect" library.  A Python extension that interfaces to expect is called "expy"
 and available from http://expectpy.sourceforge.net.  A pure Python solution that
-works like expect is ` pexpect <http://pexpect.sourceforge.net>`_.
+works like expect is `pexpect <http://pypi.python.org/pypi/pexpect/>`_.
 
 
 How do I access the serial (RS232) port?
diff --git a/Doc/faq/programming.rst b/Doc/faq/programming.rst
index 7d32939..faa3b80 100644
--- a/Doc/faq/programming.rst
+++ b/Doc/faq/programming.rst
@@ -67,8 +67,8 @@ plug-ins to add a custom feature.  In addition to the bug checking that
 PyChecker performs, Pylint offers some additional features such as checking line
 length, whether variable names are well-formed according to your coding
 standard, whether declared interfaces are fully implemented, and more.
-http://www.logilab.org/projects/pylint/documentation provides a full list of
-Pylint's features.
+http://www.logilab.org/card/pylint_manual provides a full list of Pylint's
+features.
 
 
 How can I create a stand-alone binary from a Python script?
@@ -1141,7 +1141,7 @@ use a list comprehension::
    A = [[None] * w for i in range(h)]
 
 Or, you can use an extension that provides a matrix datatype; `Numeric Python
-<http://www.pfdubois.com/numpy/>`_ is the best known.
+<http://numpy.scipy.org/>`_ is the best known.
 
 
 How do I apply a method to a sequence of objects?
diff --git a/Doc/faq/windows.rst b/Doc/faq/windows.rst
index 1f40137..eb1d3ac 100644
--- a/Doc/faq/windows.rst
+++ b/Doc/faq/windows.rst
@@ -389,10 +389,10 @@ need)::
     .py :REG_SZ: c:\<path to python>\python.exe -u %s %s
 
 This line will allow you to call your script with a simple reference like:
-http://yourserver/scripts/yourscript.py provided "scripts" is an "executable"
-directory for your server (which it usually is by default).  The "-u" flag
-specifies unbuffered and binary mode for stdin - needed when working with binary
-data.
+``http://yourserver/scripts/yourscript.py`` provided "scripts" is an
+"executable" directory for your server (which it usually is by default).  The
+:option:`-u` flag specifies unbuffered and binary mode for stdin - needed when
+working with binary data.
 
 In addition, it is recommended that using ".py" may not be a good idea for the
 file extensions when used in this context (you might want to reserve ``*.py``
@@ -517,7 +517,7 @@ Why doesn't os.popen()/win32pipe.popen() work on Win9x?
 There is a bug in Win9x that prevents os.popen/win32pipe.popen* from
 working. The good news is there is a way to work around this problem.  The
 Microsoft Knowledge Base article that you need to lookup is: Q150956. You will
-find links to the knowledge base at: http://www.microsoft.com/kb.
+find links to the knowledge base at: http://support.microsoft.com/.
 
 
 PyRun_SimpleFile() crashes on Windows but not on Unix; why?
@@ -604,4 +604,4 @@ Tim Peters:
    we can't fix it).
 
 David A Burton has written a little program to fix this.  Go to
-http://www.burtonsys.com/download.html and click on "ctl3dfix.zip".
+http://www.burtonsys.com/downloads.html and click on "ctl3dfix.zip".
diff --git a/Doc/howto/unicode.rst b/Doc/howto/unicode.rst
index 49576cd..0f829f3 100644
--- a/Doc/howto/unicode.rst
+++ b/Doc/howto/unicode.rst
@@ -403,7 +403,7 @@ These are grouped into categories such as "Letter", "Number", "Punctuation", or
 from the above output, ``'Ll'`` means 'Letter, lowercase', ``'No'`` means
 "Number, other", ``'Mn'`` is "Mark, nonspacing", and ``'So'`` is "Symbol,
 other".  See
-<http://www.unicode.org/Public/UNIDATA/UCD.html#General_Category_Values> for a
+<http://unicode.org/Public/5.1.0/ucd/UCD.html#General_Category_Values> for a
 list of category codes.
 
 References
diff --git a/Doc/howto/webservers.rst b/Doc/howto/webservers.rst
index 2440b30..d005103 100644
--- a/Doc/howto/webservers.rst
+++ b/Doc/howto/webservers.rst
@@ -270,8 +270,7 @@ Depending on the web server you need to have a special module.
 * lighttpd ships its own `FastCGI module
   <http://trac.lighttpd.net/trac/wiki/Docs%3AModFastCGI>`_ as well as an `SCGI
   module <http://trac.lighttpd.net/trac/wiki/Docs%3AModSCGI>`_.
-* nginx also supports `FastCGI
-  <http://wiki.codemongers.com/NginxSimplePythonFCGI>`_.
+* nginx also supports `FastCGI <http://wiki.nginx.org/NginxSimplePythonFCGI>`_.
 
 Once you have installed and configured the module, you can test it with the
 following WSGI-application::
@@ -525,7 +524,7 @@ the text of a wiki page.  As always, there are different ways to store
 informations on a web server.
 
 Often relational database engines like `MySQL <http://www.mysql.com/>`_ or
-`PostgreSQL <http://http://www.postgresql.org/>`_ are used due to their good
+`PostgreSQL <http://www.postgresql.org/>`_ are used due to their good
 performance handling very large databases consisting of up to millions of
 entries.  These are *queried* using a language called `SQL
 <http://en.wikipedia.org/wiki/SQL>`_.  Python programmers in general do not like
@@ -629,7 +628,7 @@ which make it possible to write web sites nearly without any Python code.
 It has a big, international community which has created many sites using Django.
 There are also quite a lot of add-on projects which extend Django's normal
 functionality.  This is partly due to Django's well written `online
-documentation <http://doc.djangoproject.com/>`_ and the `Django book
+documentation <http://docs.djangoproject.com/>`_ and the `Django book
 <http://www.djangobook.com/>`_.
 
 
diff --git a/Doc/install/index.rst b/Doc/install/index.rst
index 3646061..0751291 100644
--- a/Doc/install/index.rst
+++ b/Doc/install/index.rst
@@ -937,7 +937,8 @@ following steps.
 These compilers require some special libraries. This task is more complex than
 for Borland's C++, because there is no program to convert the library.  First
 you have to create a list of symbols which the Python DLL exports. (You can find
-a good program for this task at http://www.emmestech.com/software/cygwin/pexports-0.43/download_pexports.html)
+a good program for this task at
+http://www.emmestech.com/software/pexports-0.43/download_pexports.html).
 
 .. I don't understand what the next line means. --amk
 .. (inclusive the references on data structures.)
diff --git a/Doc/library/codecs.rst b/Doc/library/codecs.rst
index c3e7407..21e74ca 100644
--- a/Doc/library/codecs.rst
+++ b/Doc/library/codecs.rst
@@ -53,7 +53,7 @@ It defines the following functions:
    *incrementalencoder* and *incrementaldecoder*: These have to be factory
    functions providing the following interface:
 
-   ``factory(errors='strict')``
+      ``factory(errors='strict')``
 
    The factory functions must return objects providing the interfaces defined by
    the base classes :class:`IncrementalEncoder` and :class:`IncrementalDecoder`,
@@ -62,21 +62,25 @@ It defines the following functions:
    *streamreader* and *streamwriter*: These have to be factory functions providing
    the following interface:
 
-   ``factory(stream, errors='strict')``
+      ``factory(stream, errors='strict')``
 
    The factory functions must return objects providing the interfaces defined by
    the base classes :class:`StreamWriter` and :class:`StreamReader`, respectively.
    Stream codecs can maintain state.
 
-   Possible values for errors are ``'strict'`` (raise an exception in case of an
-   encoding error), ``'replace'`` (replace malformed data with a suitable
-   replacement marker, such as ``'?'``), ``'ignore'`` (ignore malformed data and
-   continue without further notice), ``'xmlcharrefreplace'`` (replace with the
-   appropriate XML character reference (for encoding only)),
-   ``'backslashreplace'`` (replace with backslashed escape sequences (for
-   encoding only)), ``'surrogateescape'`` (replace with surrogate U+DCxx, see
-   :pep:`383`) as well as any other error handling name defined via
-   :func:`register_error`.
+   Possible values for errors are
+
+   * ``'strict'``: raise an exception in case of an encoding error
+   * ``'replace'``: replace malformed data with a suitable replacement marker,
+     such as ``'?'`` or ``'\ufffd'``
+   * ``'ignore'``: ignore malformed data and continue without further notice
+   * ``'xmlcharrefreplace'``: replace with the appropriate XML character
+     reference (for encoding only)
+   * ``'backslashreplace'``: replace with backslashed escape sequences (for
+     encoding only
+   * ``'surrogateescape'``: replace with surrogate U+DCxx, see :pep:`383`
+
+   as well as any other error handling name defined via :func:`register_error`.
 
    In case a search function cannot find a given encoding, it should return
    ``None``.
@@ -173,27 +177,33 @@ functions which use :func:`lookup` for the codec lookup:
 
 .. function:: strict_errors(exception)
 
-   Implements the ``strict`` error handling.
+   Implements the ``strict`` error handling: each encoding or decoding error
+   raises a :exc:`UnicodeError`.
 
 
 .. function:: replace_errors(exception)
 
-   Implements the ``replace`` error handling.
+   Implements the ``replace`` error handling: malformed data is replaced with a
+   suitable replacement character such as ``'?'`` in bytestrings and
+   ``'\ufffd'`` in Unicode strings.
 
 
 .. function:: ignore_errors(exception)
 
-   Implements the ``ignore`` error handling.
+   Implements the ``ignore`` error handling: malformed data is ignored and
+   encoding or decoding is continued without further notice.
 
 
 .. function:: xmlcharrefreplace_errors(exception)
 
-   Implements the ``xmlcharrefreplace`` error handling.
+   Implements the ``xmlcharrefreplace`` error handling (for encoding only): the
+   unencodable character is replaced by an appropriate XML character reference.
 
 
 .. function:: backslashreplace_errors(exception)
 
-   Implements the ``backslashreplace`` error handling.
+   Implements the ``backslashreplace`` error handling (for encoding only): the
+   unencodable character is replaced by a backslashed escape sequence.
 
 To simplify working with encoded files or stream, the module also defines these
 utility functions:
diff --git a/Doc/library/configparser.rst b/Doc/library/configparser.rst
index a5d3a77..1d097f9 100644
--- a/Doc/library/configparser.rst
+++ b/Doc/library/configparser.rst
@@ -301,12 +301,23 @@ RawConfigParser Objects
 
 .. method:: RawConfigParser.optionxform(option)
 
-   Transforms the option name *option* as found in an input file or as passed in by
-   client code to the form that should be used in the internal structures.  The
-   default implementation returns a lower-case version of *option*; subclasses may
-   override this or client code can set an attribute of this name on instances to
-   affect this behavior.  Setting this to :func:`str`, for example, would make
-   option names case sensitive.
+   Transforms the option name *option* as found in an input file or as passed in
+   by client code to the form that should be used in the internal structures.
+   The default implementation returns a lower-case version of *option*;
+   subclasses may override this or client code can set an attribute of this name
+   on instances to affect this behavior.
+
+   You don't necessarily need to subclass a ConfigParser to use this method, you
+   can also re-set it on an instance, to a function that takes a string
+   argument.  Setting it to ``str``, for example, would make option names case
+   sensitive::
+
+      cfgparser = ConfigParser()
+      ...
+      cfgparser.optionxform = str
+
+   Note that when reading configuration files, whitespace around the
+   option names are stripped before :meth:`optionxform` is called.
 
 
 .. _configparser-objects:
diff --git a/Doc/library/curses.rst b/Doc/library/curses.rst
index 4ea7afe..f9ba0d6 100644
--- a/Doc/library/curses.rst
+++ b/Doc/library/curses.rst
@@ -4,10 +4,10 @@
 .. module:: curses
    :synopsis: An interface to the curses library, providing portable
               terminal handling.
+   :platform: Unix
 .. sectionauthor:: Moshe Zadka <moshez@zadka.site.co.il>
 .. sectionauthor:: Eric Raymond <esr@thyrsus.com>
 
-
 The :mod:`curses` module provides an interface to the curses library, the
 de-facto standard for portable advanced terminal handling.
 
diff --git a/Doc/library/datetime.rst b/Doc/library/datetime.rst
index c1d3113..2b98005 100644
--- a/Doc/library/datetime.rst
+++ b/Doc/library/datetime.rst
@@ -233,7 +233,7 @@ Supported operations:
 |                                | (-*t1.days*, -*t1.seconds*,                   |
 |                                | -*t1.microseconds*), and to *t1*\* -1. (1)(4) |
 +--------------------------------+-----------------------------------------------+
-| ``abs(t)``                     | equivalent to +*t* when ``t.days >= 0``, and  |
+| ``abs(t)``                     | equivalent to +\ *t* when ``t.days >= 0``, and|
 |                                | to -*t* when ``t.days < 0``. (2)              |
 +--------------------------------+-----------------------------------------------+
 
diff --git a/Doc/library/functions.rst b/Doc/library/functions.rst
index 465339a..adde017 100644
--- a/Doc/library/functions.rst
+++ b/Doc/library/functions.rst
@@ -499,8 +499,10 @@ are always available.  They are listed here in alphabetical order.
 
    Return the "identity" of an object.  This is an integer which
    is guaranteed to be unique and constant for this object during its lifetime.
-   Two objects with non-overlapping lifetimes may have the same :func:`id` value.
-   (Implementation note: this is the address of the object.)
+   Two objects with non-overlapping lifetimes may have the same :func:`id`
+   value.
+
+   .. impl-detail:: This is the address of the object.
 
 
 .. function:: input([prompt])
diff --git a/Doc/library/getopt.rst b/Doc/library/getopt.rst
index 7f6b670..a360384 100644
--- a/Doc/library/getopt.rst
+++ b/Doc/library/getopt.rst
@@ -36,12 +36,13 @@ exception:
    *longopts*, if specified, must be a list of strings with the names of the
    long options which should be supported.  The leading ``'--'`` characters
    should not be included in the option name.  Long options which require an
-   argument should be followed by an equal sign (``'='``).  To accept only long
-   options, *shortopts* should be an empty string.  Long options on the command line
-   can be recognized so long as they provide a prefix of the option name that
-   matches exactly one of the accepted options.  For example, if *longopts* is
-   ``['foo', 'frob']``, the option :option:`--fo` will match as :option:`--foo`,
-   but :option:`--f` will not match uniquely, so :exc:`GetoptError` will be raised.
+   argument should be followed by an equal sign (``'='``).  Optional arguments
+   are not supported.  To accept only long options, *shortopts* should be an
+   empty string.  Long options on the command line can be recognized so long as
+   they provide a prefix of the option name that matches exactly one of the
+   accepted options.  For example, if *longopts* is ``['foo', 'frob']``, the
+   option :option:`--fo` will match as :option:`--foo`, but :option:`--f` will
+   not match uniquely, so :exc:`GetoptError` will be raised.
 
    The return value consists of two elements: the first is a list of ``(option,
    value)`` pairs; the second is the list of program arguments left after the
diff --git a/Doc/library/inspect.rst b/Doc/library/inspect.rst
index ad88e3d..37a4f1a 100644
--- a/Doc/library/inspect.rst
+++ b/Doc/library/inspect.rst
@@ -290,18 +290,22 @@ attributes:
 
    Return true if the object is a getset descriptor.
 
-   getsets are attributes defined in extension modules via ``PyGetSetDef``
-   structures.  For Python implementations without such types, this method will
-   always return ``False``.
+   .. impl-detail::
+
+      getsets are attributes defined in extension modules via
+      :ctype:`PyGetSetDef` structures.  For Python implementations without such
+      types, this method will always return ``False``.
 
 
 .. function:: ismemberdescriptor(object)
 
    Return true if the object is a member descriptor.
 
-   Member descriptors are attributes defined in extension modules via
-   ``PyMemberDef`` structures.  For Python implementations without such types,
-   this method will always return ``False``.
+   .. impl-detail::
+
+      Member descriptors are attributes defined in extension modules via
+      :ctype:`PyMemberDef` structures.  For Python implementations without such
+      types, this method will always return ``False``.
 
 
 .. _inspect-source:
@@ -508,10 +512,12 @@ line.
 
    Return the frame object for the caller's stack frame.
 
-   This function relies on Python stack frame support in the interpreter, which
-   isn't guaranteed to exist in all implementations of Python. If running in
-   an implementation without Python stack frame support this function returns
-   ``None``.
+   .. impl-detail::
+
+      This function relies on Python stack frame support in the interpreter,
+      which isn't guaranteed to exist in all implementations of Python.  If
+      running in an implementation without Python stack frame support this
+      function returns ``None``.
 
 
 .. function:: stack(context=1)
diff --git a/Doc/library/mailbox.rst b/Doc/library/mailbox.rst
index 0d4d056..7409af5 100644
--- a/Doc/library/mailbox.rst
+++ b/Doc/library/mailbox.rst
@@ -595,7 +595,7 @@ Maildir, mbox, MH, Babyl, and MMDF.
    `nmh - Message Handling System <http://www.nongnu.org/nmh/>`_
       Home page of :program:`nmh`, an updated version of the original :program:`mh`.
 
-   `MH & nmh: Email for Users & Programmers <http://www.ics.uci.edu/~mh/book/>`_
+   `MH & nmh: Email for Users & Programmers <http://rand-mh.sourceforge.net/book/>`_
       A GPL-licensed book on :program:`mh` and :program:`nmh`, with some information
       on the mailbox format.
 
diff --git a/Doc/library/math.rst b/Doc/library/math.rst
index 566603d..9fa1899 100644
--- a/Doc/library/math.rst
+++ b/Doc/library/math.rst
@@ -291,7 +291,7 @@ Constants
    The mathematical constant *e*.
 
 
-.. note::
+.. impl-detail::
 
    The :mod:`math` module consists mostly of thin wrappers around the platform C
    math library functions.  Behavior in exceptional cases is loosely specified
diff --git a/Doc/library/msilib.rst b/Doc/library/msilib.rst
index 6fb7f05..1e6946d 100644
--- a/Doc/library/msilib.rst
+++ b/Doc/library/msilib.rst
@@ -394,10 +394,10 @@ Directory Objects
 
 .. seealso::
 
-   `Directory Table <http://msdn.microsoft.com/library/en-us/msi/setup/directory_table.asp>`_
-   `File Table <http://msdn.microsoft.com/library/en-us/msi/setup/file_table.asp>`_
-   `Component Table <http://msdn.microsoft.com/library/en-us/msi/setup/component_table.asp>`_
-   `FeatureComponents Table <http://msdn.microsoft.com/library/en-us/msi/setup/featurecomponents_table.asp>`_
+   `Directory Table <http://msdn.microsoft.com/library/default.asp?url=/library/en-us/msi/setup/directory_table.asp>`_
+   `File Table <http://msdn.microsoft.com/library/default.asp?url=/library/en-us/msi/setup/file_table.asp>`_
+   `Component Table <http://msdn.microsoft.com/library/default.asp?url=/library/en-us/msi/setup/component_table.asp>`_
+   `FeatureComponents Table <http://msdn.microsoft.com/library/default.asp?url=/library/en-us/msi/setup/featurecomponents_table.asp>`_
 
 .. _features:
 
@@ -422,7 +422,7 @@ Features
 
 .. seealso::
 
-   `Feature Table <http://msdn.microsoft.com/library/en-us/msi/setup/feature_table.asp>`_
+   `Feature Table <http://msdn.microsoft.com/library/default.asp?url=/library/en-us/msi/setup/feature_table.asp>`_
 
 .. _msi-gui:
 
@@ -516,13 +516,13 @@ to create MSI files with a user-interface for installing Python packages.
 
 .. seealso::
 
-   `Dialog Table <http://msdn.microsoft.com/library/en-us/msi/setup/dialog_table.asp>`_
-   `Control Table <http://msdn.microsoft.com/library/en-us/msi/setup/control_table.asp>`_
-   `Control Types <http://msdn.microsoft.com/library/en-us/msi/setup/controls.asp>`_
-   `ControlCondition Table <http://msdn.microsoft.com/library/en-us/msi/setup/controlcondition_table.asp>`_
-   `ControlEvent Table <http://msdn.microsoft.com/library/en-us/msi/setup/controlevent_table.asp>`_
-   `EventMapping Table <http://msdn.microsoft.com/library/en-us/msi/setup/eventmapping_table.asp>`_
-   `RadioButton Table <http://msdn.microsoft.com/library/en-us/msi/setup/radiobutton_table.asp>`_
+   `Dialog Table <http://msdn.microsoft.com/library/default.asp?url=/library/en-us/msi/setup/dialog_table.asp>`_
+   `Control Table <http://msdn.microsoft.com/library/default.asp?url=/library/en-us/msi/setup/control_table.asp>`_
+   `Control Types <http://msdn.microsoft.com/library/default.asp?url=/library/en-us/msi/setup/controls.asp>`_
+   `ControlCondition Table <http://msdn.microsoft.com/library/default.asp?url=/library/en-us/msi/setup/controlcondition_table.asp>`_
+   `ControlEvent Table <http://msdn.microsoft.com/library/default.asp?url=/library/en-us/msi/setup/controlevent_table.asp>`_
+   `EventMapping Table <http://msdn.microsoft.com/library/default.asp?url=/library/en-us/msi/setup/eventmapping_table.asp>`_
+   `RadioButton Table <http://msdn.microsoft.com/library/default.asp?url=/library/en-us/msi/setup/radiobutton_table.asp>`_
 
 .. _msi-tables:
 
@@ -551,5 +551,3 @@ definitions. Currently, these definitions are based on MSI version 2.0.
 
    This module contains definitions for the UIText and ActionText tables, for the
    standard installer actions.
-
-
diff --git a/Doc/library/os.rst b/Doc/library/os.rst
index df72857..5e8bdc1 100644
--- a/Doc/library/os.rst
+++ b/Doc/library/os.rst
@@ -1578,9 +1578,9 @@ written in Python, such as a mail server's external command delivery program.
 .. function:: system(command)
 
    Execute the command (a string) in a subshell.  This is implemented by calling
-   the Standard C function :cfunc:`system`, and has the same limitations.  Changes
-   to :data:`os.environ`, :data:`sys.stdin`, etc. are not reflected in the
-   environment of the executed command.
+   the Standard C function :cfunc:`system`, and has the same limitations.
+   Changes to :data:`sys.stdin`, etc. are not reflected in the environment of the
+   executed command.
 
    On Unix, the return value is the exit status of the process encoded in the
    format specified for :func:`wait`.  Note that POSIX does not specify the meaning
diff --git a/Doc/library/othergui.rst b/Doc/library/othergui.rst
index 471076c..1f4aed7 100644
--- a/Doc/library/othergui.rst
+++ b/Doc/library/othergui.rst
@@ -43,7 +43,7 @@ also available for Python:
       `PythonCAD <http://www.pythoncad.org/>`_. An online `tutorial
       <http://www.pygtk.org/pygtk2tutorial/index.html>`_ is available.
 
-   `PyQt <http://www.riverbankcomputing.co.uk/pyqt/index.php>`_
+   `PyQt <http://www.riverbankcomputing.co.uk/software/pyqt/>`_
       PyQt is a :program:`sip`\ -wrapped binding to the Qt toolkit.  Qt is an
       extensive C++ GUI application development framework that is
       available for Unix, Windows and Mac OS X. :program:`sip` is a tool
diff --git a/Doc/library/platform.rst b/Doc/library/platform.rst
index 7be6d7b..f4ef680 100644
--- a/Doc/library/platform.rst
+++ b/Doc/library/platform.rst
@@ -94,7 +94,7 @@ Cross Platform
 .. function:: python_implementation()
 
    Returns a string identifying the Python implementation. Possible return values
-   are: 'CPython', 'IronPython', 'Jython'
+   are: 'CPython', 'IronPython', 'Jython'.
 
 
 .. function:: python_revision()
diff --git a/Doc/library/signal.rst b/Doc/library/signal.rst
index 7319ac9..7beda4b 100644
--- a/Doc/library/signal.rst
+++ b/Doc/library/signal.rst
@@ -157,13 +157,14 @@ The :mod:`signal` module defines the following functions:
 
    The old values are returned as a tuple: (delay, interval).
 
-   Attempting to pass an invalid interval timer will cause a
-   :exc:`ItimerError`.
+   Attempting to pass an invalid interval timer will cause an
+   :exc:`ItimerError`.  Availability: Unix.
 
 
 .. function:: getitimer(which)
 
    Returns current value of a given interval timer specified by *which*.
+   Availability: Unix.
 
 
 .. function:: set_wakeup_fd(fd)
@@ -182,14 +183,14 @@ The :mod:`signal` module defines the following functions:
 
 .. function:: siginterrupt(signalnum, flag)
 
-   Change system call restart behaviour: if *flag* is :const:`False`, system calls
-   will be restarted when interrupted by signal *signalnum*, otherwise system calls will
-   be interrupted. Returns nothing. Availability: Unix (see the man page
-   :manpage:`siginterrupt(3)` for further information).
+   Change system call restart behaviour: if *flag* is :const:`False`, system
+   calls will be restarted when interrupted by signal *signalnum*, otherwise
+   system calls will be interrupted.  Returns nothing.  Availability: Unix (see
+   the man page :manpage:`siginterrupt(3)` for further information).
 
-   Note that installing a signal handler with :func:`signal` will reset the restart
-   behaviour to interruptible by implicitly calling :cfunc:`siginterrupt` with a true *flag*
-   value for the given signal.
+   Note that installing a signal handler with :func:`signal` will reset the
+   restart behaviour to interruptible by implicitly calling
+   :cfunc:`siginterrupt` with a true *flag* value for the given signal.
 
 
 .. function:: signal(signalnum, handler)
diff --git a/Doc/library/stdtypes.rst b/Doc/library/stdtypes.rst
index 8f56bb0..b854fc4 100644
--- a/Doc/library/stdtypes.rst
+++ b/Doc/library/stdtypes.rst
@@ -772,13 +772,15 @@ Notes:
    If *k* is ``None``, it is treated like ``1``.
 
 (6)
-   If *s* and *t* are both strings, some Python implementations such as CPython can
-   usually perform an in-place optimization for assignments of the form ``s=s+t``
-   or ``s+=t``.  When applicable, this optimization makes quadratic run-time much
-   less likely.  This optimization is both version and implementation dependent.
-   For performance sensitive code, it is preferable to use the :meth:`str.join`
-   method which assures consistent linear concatenation performance across versions
-   and implementations.
+   .. impl-detail::
+
+      If *s* and *t* are both strings, some Python implementations such as
+      CPython can usually perform an in-place optimization for assignments of
+      the form ``s = s + t`` or ``s += t``.  When applicable, this optimization
+      makes quadratic run-time much less likely.  This optimization is both
+      version and implementation dependent.  For performance sensitive code, it
+      is preferable to use the :meth:`str.join` method which assures consistent
+      linear concatenation performance across versions and implementations.
 
 
 .. _string-methods:
@@ -950,12 +952,12 @@ functions based on regular expressions.
    least one cased character, false otherwise.
 
 
-.. method:: str.join(seq)
+.. method:: str.join(iterable)
 
-   Return a string which is the concatenation of the strings in the sequence
-   *seq*.  A :exc:`TypeError` will be raised if there are any non-string values
-   in *seq*, including :class:`bytes` objects.  The separator between elements
-   is the string providing this method.
+   Return a string which is the concatenation of the strings in the
+   :term:`iterable` *iterable*.  A :exc:`TypeError` will be raised if there are
+   any non-string values in *seq*, including :class:`bytes` objects.  The
+   separator between elements is the string providing this method.
 
 
 .. method:: str.ljust(width[, fillchar])
@@ -1509,14 +1511,17 @@ Notes:
    that compare equal --- this is helpful for sorting in multiple passes (for
    example, sort by department, then by salary grade).
 
-   While a list is being sorted, the effect of attempting to mutate, or even
-   inspect, the list is undefined.  The C implementation
-   makes the list appear empty for the duration, and raises :exc:`ValueError` if it
-   can detect that the list has been mutated during a sort.
+   .. impl-detail::
+
+      While a list is being sorted, the effect of attempting to mutate, or even
+      inspect, the list is undefined.  The C implementation of Python makes the
+      list appear empty for the duration, and raises :exc:`ValueError` if it can
+      detect that the list has been mutated during a sort.
 
 (8)
    :meth:`sort` is not supported by :class:`bytearray` objects.
 
+
 .. _bytes-methods:
 
 Bytes and Byte Array Methods
diff --git a/Doc/library/sys.rst b/Doc/library/sys.rst
index b786034..9262a09 100644
--- a/Doc/library/sys.rst
+++ b/Doc/library/sys.rst
@@ -352,8 +352,10 @@ always available.
    that is deeper than the call stack, :exc:`ValueError` is raised.  The default
    for *depth* is zero, returning the frame at the top of the call stack.
 
-   This function should be used for internal and specialized purposes only. It
-   is not guaranteed to exist in all implementations of Python.
+   .. impl-detail::
+
+      This function should be used for internal and specialized purposes only.
+      It is not guaranteed to exist in all implementations of Python.
 
 
 .. function:: getprofile()
@@ -373,12 +375,12 @@ always available.
 
    Get the trace function as set by :func:`settrace`.
 
-   .. note::
+   .. impl-detail::
 
       The :func:`gettrace` function is intended only for implementing debuggers,
-      profilers, coverage tools and the like. Its behavior is part of the
-      implementation platform, rather than part of the language definition,
-      and thus may not be available in all Python implementations.
+      profilers, coverage tools and the like.  Its behavior is part of the
+      implementation platform, rather than part of the language definition, and
+      thus may not be available in all Python implementations.
 
 
 .. function:: getwindowsversion()
@@ -749,12 +751,12 @@ always available.
 
    For more information on code and frame objects, refer to :ref:`types`.
 
-   .. note::
+   .. impl-detail::
 
       The :func:`settrace` function is intended only for implementing debuggers,
-      profilers, coverage tools and the like. Its behavior is part of the
-      implementation platform, rather than part of the language definition, and thus
-      may not be available in all Python implementations.
+      profilers, coverage tools and the like.  Its behavior is part of the
+      implementation platform, rather than part of the language definition, and
+      thus may not be available in all Python implementations.
 
 
 .. function:: settscdump(on_flag)
diff --git a/Doc/library/types.rst b/Doc/library/types.rst
index 8ae9f88..7caecaf 100644
--- a/Doc/library/types.rst
+++ b/Doc/library/types.rst
@@ -77,5 +77,8 @@ The module defines the following names:
    as ``datetime.timedelta.days``.  This type is used as descriptor for simple C
    data members which use standard conversion functions; it has the same purpose
    as the :class:`property` type, but for classes defined in extension modules.
-   In other implementations of Python, this type may be identical to
-   ``GetSetDescriptorType``.
+
+   .. impl-detail::
+
+      In other implementations of Python, this type may be identical to
+      ``GetSetDescriptorType``.
diff --git a/Doc/library/weakref.rst b/Doc/library/weakref.rst
index a667479..d462f6e 100644
--- a/Doc/library/weakref.rst
+++ b/Doc/library/weakref.rst
@@ -69,9 +69,10 @@ support weak references but can add support through subclassing::
 
    obj = Dict(red=1, green=2, blue=3)   # this object is weak referenceable
 
-Other built-in types such as :class:`tuple` and :class:`int` do not support
-weak references even when subclassed (those types implemented as a
-:ctype:`PyVarObject`).
+.. impl-detail::
+
+   Other built-in types such as :class:`tuple` and :class:`long` do not support
+   weak references even when subclassed.
 
 Extension types can easily be made to support weak references; see
 :ref:`weakref-support`.
diff --git a/Doc/reference/datamodel.rst b/Doc/reference/datamodel.rst
index 971c06e..36fc575 100644
--- a/Doc/reference/datamodel.rst
+++ b/Doc/reference/datamodel.rst
@@ -59,13 +59,16 @@ Objects are never explicitly destroyed; however, when they become unreachable
 they may be garbage-collected.  An implementation is allowed to postpone garbage
 collection or omit it altogether --- it is a matter of implementation quality
 how garbage collection is implemented, as long as no objects are collected that
-are still reachable.  (Implementation note: CPython currently uses a
-reference-counting scheme with (optional) delayed detection of cyclically linked
-garbage, which collects most objects as soon as they become unreachable, but is
-not guaranteed to collect garbage containing circular references.  See the
-documentation of the :mod:`gc` module for information on controlling the
-collection of cyclic garbage.  Other implementations act differently and CPython
-may change.)
+are still reachable.
+
+.. impl-detail::
+
+   CPython currently uses a reference-counting scheme with (optional) delayed
+   detection of cyclically linked garbage, which collects most objects as soon
+   as they become unreachable, but is not guaranteed to collect garbage
+   containing circular references.  See the documentation of the :mod:`gc`
+   module for information on controlling the collection of cyclic garbage.
+   Other implementations act differently and CPython may change.
 
 Note that the use of the implementation's tracing or debugging facilities may
 keep objects alive that would normally be collectable. Also note that catching
@@ -1469,15 +1472,15 @@ Notes on using *__slots__*
   *__slots__*; otherwise, the class attribute would overwrite the descriptor
   assignment.
 
+* The action of a *__slots__* declaration is limited to the class where it is
+  defined.  As a result, subclasses will have a *__dict__* unless they also define
+  *__slots__* (which must only contain names of any *additional* slots).
+
 * If a class defines a slot also defined in a base class, the instance variable
   defined by the base class slot is inaccessible (except by retrieving its
   descriptor directly from the base class). This renders the meaning of the
   program undefined.  In the future, a check may be added to prevent this.
 
-* The action of a *__slots__* declaration is limited to the class where it is
-  defined.  As a result, subclasses will have a *__dict__* unless they also define
-  *__slots__*.
-
 * Nonempty *__slots__* does not work for classes derived from "variable-length"
   built-in types such as :class:`int`, :class:`str` and :class:`tuple`.
 
@@ -1714,12 +1717,16 @@ implemented as an iteration through a sequence.  However, container objects can
 supply the following special method with a more efficient implementation, which
 also does not require the object be a sequence.
 
-
 .. method:: object.__contains__(self, item)
 
-   Called to implement membership test operators.  Should return true if *item* is
-   in *self*, false otherwise.  For mapping objects, this should consider the keys
-   of the mapping rather than the values or the key-item pairs.
+   Called to implement membership test operators.  Should return true if *item*
+   is in *self*, false otherwise.  For mapping objects, this should consider the
+   keys of the mapping rather than the values or the key-item pairs.
+
+   For objects that don't define :meth:`__contains__`, the membership test first
+   tries iteration via :meth:`__iter__`, then the old sequence iteration
+   protocol via :meth:`__getitem__`, see :ref:`this section in the language
+   reference <membership-test-details>`.
 
 
 .. _numeric-types:
diff --git a/Doc/reference/executionmodel.rst b/Doc/reference/executionmodel.rst
index 68ee654..90791d2 100644
--- a/Doc/reference/executionmodel.rst
+++ b/Doc/reference/executionmodel.rst
@@ -129,7 +129,7 @@ the built-in module :mod:`builtins`; when in any other module,
 itself.  ``__builtins__`` can be set to a user-created dictionary to create a
 weak form of restricted execution.
 
-.. note::
+.. impl-detail::
 
    Users should not touch ``__builtins__``; it is strictly an implementation
    detail.  Users wanting to override values in the built-in namespace should
diff --git a/Doc/reference/expressions.rst b/Doc/reference/expressions.rst
index cdb802a..d074ebb 100644
--- a/Doc/reference/expressions.rst
+++ b/Doc/reference/expressions.rst
@@ -639,13 +639,13 @@ slots for which no default value is specified, a :exc:`TypeError` exception is
 raised.  Otherwise, the list of filled slots is used as the argument list for
 the call.
 
-.. note::
+.. impl-detail::
 
-   An implementation may provide built-in functions whose positional parameters do
-   not have names, even if they are 'named' for the purpose of documentation, and
-   which therefore cannot be supplied by keyword.  In CPython, this is the case for
-   functions implemented in C that use :cfunc:`PyArg_ParseTuple` to parse their
-   arguments.
+   An implementation may provide built-in functions whose positional parameters
+   do not have names, even if they are 'named' for the purpose of documentation,
+   and which therefore cannot be supplied by keyword.  In CPython, this is the
+   case for functions implemented in C that use :cfunc:`PyArg_ParseTuple` to
+   parse their arguments.
 
 If there are more positional arguments than there are formal parameter slots, a
 :exc:`TypeError` exception is raised, unless a formal parameter using the syntax
@@ -1053,6 +1053,8 @@ cross-type comparison is not supported, the comparison method returns
 supported cross-type comparisons and unsupported comparisons.  For example,
 ``Decimal(2) == 2`` and `2 == float(2)`` but ``Decimal(2) != float(2)``.
 
+.. _membership-test-details:
+
 The operators :keyword:`in` and :keyword:`not in` test for membership.  ``x in
 s`` evaluates to true if *x* is a member of *s*, and false otherwise.  ``x not
 in s`` returns the negation of ``x in s``.  All built-in sequences and set types
@@ -1069,7 +1071,12 @@ return ``True``.
 For user-defined classes which define the :meth:`__contains__` method, ``x in
 y`` is true if and only if ``y.__contains__(x)`` is true.
 
-For user-defined classes which do not define :meth:`__contains__` and do define
+For user-defined classes which do not define :meth:`__contains__` but do define
+:meth:`__iter__`, ``x in y`` is true if some value ``z`` with ``x == z`` is
+produced while iterating over ``y``.  If an exception is raised during the
+iteration, it is as if :keyword:`in` raised that exception.
+
+Lastly, the old-style iteration protocol is tried: if a class defines
 :meth:`__getitem__`, ``x in y`` is true if and only if there is a non-negative
 integer index *i* such that ``x == y[i]``, and all lower integer indices do not
 raise :exc:`IndexError` exception.  (If any other exception is raised, it is as
diff --git a/Doc/reference/simple_stmts.rst b/Doc/reference/simple_stmts.rst
index 8c95623..b3fc891 100644
--- a/Doc/reference/simple_stmts.rst
+++ b/Doc/reference/simple_stmts.rst
@@ -236,9 +236,11 @@ Assignment of an object to a single target is recursively defined as follows.
   from the length of the assigned sequence, thus changing the length of the
   target sequence, if the object allows it.
 
-(In the current implementation, the syntax for targets is taken to be the same
-as for expressions, and invalid syntax is rejected during the code generation
-phase, causing less detailed error messages.)
+.. impl-detail::
+
+   In the current implementation, the syntax for targets is taken to be the same
+   as for expressions, and invalid syntax is rejected during the code generation
+   phase, causing less detailed error messages.
 
 WARNING: Although the definition of assignment implies that overlaps between the
 left-hand side and the right-hand side are 'safe' (for example ``a, b = b, a``
@@ -935,9 +937,11 @@ Names listed in a :keyword:`global` statement must not be defined as formal
 parameters or in a :keyword:`for` loop control target, :keyword:`class`
 definition, function definition, or :keyword:`import` statement.
 
-(The current implementation does not enforce the latter two restrictions, but
-programs should not abuse this freedom, as future implementations may enforce
-them or silently change the meaning of the program.)
+.. impl-detail::
+
+   The current implementation does not enforce the latter two restrictions, but
+   programs should not abuse this freedom, as future implementations may enforce
+   them or silently change the meaning of the program.
 
 .. index::
    builtin: exec
diff --git a/Doc/tools/sphinxext/pyspecific.py b/Doc/tools/sphinxext/pyspecific.py
index adfeb6a..d2cca84 100644
--- a/Doc/tools/sphinxext/pyspecific.py
+++ b/Doc/tools/sphinxext/pyspecific.py
@@ -35,6 +35,8 @@ from sphinx.locale import versionlabels
 HTMLTranslator.visit_versionmodified = new_visit_versionmodified
 
 
+# Support for marking up and linking to bugs.python.org issues
+
 def issue_role(typ, rawtext, text, lineno, inliner, options={}, content=[]):
     issue = utils.unescape(text)
     text = 'issue ' + issue
@@ -42,6 +44,34 @@ def issue_role(typ, rawtext, text, lineno, inliner, options={}, content=[]):
     return [refnode], []
 
 
+# Support for marking up implementation details
+
+from sphinx.util.compat import Directive
+
+class ImplementationDetail(Directive):
+
+    has_content = True
+    required_arguments = 0
+    optional_arguments = 1
+    final_argument_whitespace = True
+
+    def run(self):
+        pnode = nodes.compound(classes=['impl-detail'])
+        content = self.content
+        add_text = nodes.strong('CPython implementation detail:',
+                                'CPython implementation detail:')
+        if self.arguments:
+            n, m = self.state.inline_text(self.arguments[0], self.lineno)
+            pnode.append(nodes.paragraph('', '', *(n + m)))
+        self.state.nested_parse(content, self.content_offset, pnode)
+        if pnode.children and isinstance(pnode[0], nodes.paragraph):
+            pnode[0].insert(0, add_text)
+            pnode[0].insert(1, nodes.Text(' '))
+        else:
+            pnode.insert(0, nodes.paragraph('', '', add_text))
+        return [pnode]
+
+
 # Support for building "topic help" for pydoc
 
 pydoc_topic_labels = [
@@ -108,10 +138,12 @@ class PydocTopicsBuilder(Builder):
         finally:
             f.close()
 
+
 # Support for checking for suspicious markup
 
 import suspicious
 
+
 # Support for documenting Opcodes
 
 import re
@@ -134,6 +166,7 @@ def parse_opcode_signature(env, sig, signode):
 
 def setup(app):
     app.add_role('issue', issue_role)
+    app.add_directive('impl-detail', ImplementationDetail)
     app.add_builder(PydocTopicsBuilder)
     app.add_builder(suspicious.CheckSuspiciousMarkupBuilder)
     app.add_description_unit('opcode', 'opcode', '%s (opcode)',
diff --git a/Doc/tools/sphinxext/static/basic.css b/Doc/tools/sphinxext/static/basic.css
index 03b0ba3..aeb1381 100644
--- a/Doc/tools/sphinxext/static/basic.css
+++ b/Doc/tools/sphinxext/static/basic.css
@@ -345,6 +345,21 @@ p.deprecated {
     background-color: #ffa
 }
 
+.impl-detail {
+    margin-top: 10px;
+    margin-bottom: 10px;
+    padding: 7px;
+    border: 1px solid #ccc;
+}
+
+.impl-detail .compound-first {
+    margin-top: 0;
+}
+
+.impl-detail .compound-last {
+    margin-bottom: 0;
+}
+
 /* -- code displays --------------------------------------------------------- */
 
 pre {
@@ -405,7 +420,7 @@ span.eqno {
     div.document,
     div.documentwrapper,
     div.bodywrapper {
-        margin: 0;
+        margin: 0 !important;
         width: 100%;
     }
 
diff --git a/Doc/tutorial/index.rst b/Doc/tutorial/index.rst
index 8a1a8fb..7d0bfc2 100644
--- a/Doc/tutorial/index.rst
+++ b/Doc/tutorial/index.rst
@@ -28,18 +28,17 @@ features of the Python language and system. It helps to have a Python
 interpreter handy for hands-on experience, but all examples are self-contained,
 so the tutorial can be read off-line as well.
 
-For a description of standard objects and modules, see the Python Library
-Reference document. The Python Reference Manual gives a more formal definition
-of the language. To write extensions in C or C++, read Extending and Embedding
-the Python Interpreter and Python/C API Reference. There are also several books
-covering Python in depth.
+For a description of standard objects and modules, see :ref:`library-index`.
+:ref:`reference-index` gives a more formal definition of the language.  To write
+extensions in C or C++, read :ref:`extending-index` and
+:ref:`c-api-index`. There are also several books covering Python in depth.
 
 This tutorial does not attempt to be comprehensive and cover every single
 feature, or even every commonly used feature. Instead, it introduces many of
 Python's most noteworthy features, and will give you a good idea of the
 language's flavor and style. After reading it, you will be able to read and
 write Python modules and programs, and you will be ready to learn more about the
-various Python library modules described in the Python Library Reference.
+various Python library modules described in :ref:`library-index`.
 
 The :ref:`glossary` is also worth going through.
 
diff --git a/Doc/using/cmdline.rst b/Doc/using/cmdline.rst
index ad8f8c6..ccdfe33 100644
--- a/Doc/using/cmdline.rst
+++ b/Doc/using/cmdline.rst
@@ -8,7 +8,7 @@ Command line and environment
 The CPython interpreter scans the command line and the environment for various
 settings.
 
-.. note::
+.. impl-detail::
 
    Other implementations' command line schemes may differ.  See
    :ref:`implementations` for further resources.
diff --git a/Doc/using/windows.rst b/Doc/using/windows.rst
index 99fc674..7961a60 100644
--- a/Doc/using/windows.rst
+++ b/Doc/using/windows.rst
@@ -67,7 +67,7 @@ key features:
 `ActivePython <http://www.activestate.com/Products/activepython/>`_
     Installer with multi-platform compatibility, documentation, PyWin32
 
-`Python Enthought Edition <http://code.enthought.com/enthon/>`_
+`Enthought Python Distribution <http://www.enthought.com/products/epd.php>`_
     Popular modules (such as PyWin32) with their respective documentation, tool
     suite for building extensible python applications
 
@@ -221,8 +221,7 @@ utilities for:
 * Win32 API calls
 * Registry
 * Event log
-* `Microsoft Foundation Classes <http://msdn.microsoft.com/library/
-  en-us/vclib/html/_mfc_Class_Library_Reference_Introduction.asp>`_ (MFC)
+* `Microsoft Foundation Classes <http://msdn.microsoft.com/en-us/library/fe1cf721%28VS.80%29.aspx>`_ (MFC)
   user interfaces
 
 `PythonWin <http://web.archive.org/web/20060524042422/
@@ -299,7 +298,7 @@ For extension modules, consult :ref:`building-on-windows`.
       MinGW gcc under Windows" or "Installing Python extension with distutils
       and without Microsoft Visual C++" by Sébastien Sauvage, 2003
 
-   `MingW -- Python extensions <http://www.mingw.org/MinGWiki/index.php/Python%20extensions>`_
+   `MingW -- Python extensions <http://oldwiki.mingw.org/index.php/Python%20extensions>`_
       by Trent Apted et al, 2007
 
 
diff --git a/Doc/whatsnew/2.0.rst b/Doc/whatsnew/2.0.rst
index f5326d7..5fd53d1 100644
--- a/Doc/whatsnew/2.0.rst
+++ b/Doc/whatsnew/2.0.rst
@@ -572,8 +572,7 @@ Work has been done on porting Python to 64-bit Windows on the Itanium processor,
 mostly by Trent Mick of ActiveState.  (Confusingly, ``sys.platform`` is still
 ``'win32'`` on Win64 because it seems that for ease of porting, MS Visual C++
 treats code as 32 bit on Itanium.) PythonWin also supports Windows CE; see the
-Python CE page at http://starship.python.net/crew/mhammond/ce/ for more
-information.
+Python CE page at http://pythonce.sourceforge.net/ for more information.
 
 Another new platform is Darwin/MacOS X; initial support for it is in Python 2.0.
 Dynamic loading works, if you specify "configure --with-dyld --with-suffix=.x".
@@ -1041,8 +1040,8 @@ sent over a socket.  When compiling Python, you can edit :file:`Modules/Setup`
 to include SSL support, which adds an additional function to the :mod:`socket`
 module: :func:`socket.ssl(socket, keyfile, certfile)`, which takes a socket
 object and returns an SSL socket.  The :mod:`httplib` and :mod:`urllib` modules
-were also changed to support "https://" URLs, though no one has implemented FTP
-or SMTP over SSL.
+were also changed to support ``https://`` URLs, though no one has implemented
+FTP or SMTP over SSL.
 
 The :mod:`httplib` module has been rewritten by Greg Stein to support HTTP/1.1.
 Backward compatibility with the 1.5 version of :mod:`httplib` is provided,
diff --git a/Doc/whatsnew/2.2.rst b/Doc/whatsnew/2.2.rst
index acdba83..31e8dd0 100644
--- a/Doc/whatsnew/2.2.rst
+++ b/Doc/whatsnew/2.2.rst
@@ -30,7 +30,7 @@ understand the complete implementation and design rationale for a change, refer
 to the PEP for a particular new feature.
 
 
-.. seealso::
+.. seealso (now defunct)
 
    http://www.unixreview.com/documents/s=1356/urm0109h/0109h.htm
       "What's So Special About Python 2.2?" is also about the new 2.2 features, and
@@ -49,14 +49,14 @@ amazing new capabilities. Before beginning this, the longest and most
 complicated section of this article, I'll provide an overview of the changes and
 offer some comments.
 
-A long time ago I wrote a Web page (http://www.amk.ca/python/writing/warts.html)
-listing flaws in Python's design.  One of the most significant flaws was that
-it's impossible to subclass Python types implemented in C.  In particular, it's
-not possible to subclass built-in types, so you can't just subclass, say, lists
-in order to add a single useful method to them. The :mod:`UserList` module
-provides a class that supports all of the methods of lists and that can be
-subclassed further, but there's lots of C code that expects a regular Python
-list and won't accept a :class:`UserList` instance.
+A long time ago I wrote a Web page listing flaws in Python's design.  One of the
+most significant flaws was that it's impossible to subclass Python types
+implemented in C.  In particular, it's not possible to subclass built-in types,
+so you can't just subclass, say, lists in order to add a single useful method to
+them. The :mod:`UserList` module provides a class that supports all of the
+methods of lists and that can be subclassed further, but there's lots of C code
+that expects a regular Python list and won't accept a :class:`UserList`
+instance.
 
 Python 2.2 fixes this, and in the process adds some exciting new capabilities.
 A brief summary:
diff --git a/Doc/whatsnew/2.3.rst b/Doc/whatsnew/2.3.rst
index fd0f77f..3894f87 100644
--- a/Doc/whatsnew/2.3.rst
+++ b/Doc/whatsnew/2.3.rst
@@ -1855,10 +1855,10 @@ and bundle it with the source of your extension.
 
 .. seealso::
 
-   http://cvs.sourceforge.net/cgi-bin/viewcvs.cgi/python/python/dist/src/Objects/obmalloc.c
-      For the full details of the pymalloc implementation, see the comments at the top
-      of the file :file:`Objects/obmalloc.c` in the Python source code.  The above
-      link points to the file within the SourceForge CVS browser.
+   http://svn.python.org/view/python/trunk/Objects/obmalloc.c
+      For the full details of the pymalloc implementation, see the comments at
+      the top of the file :file:`Objects/obmalloc.c` in the Python source code.
+      The above link points to the file within the python.org SVN browser.
 
 .. ======================================================================
 
diff --git a/Doc/whatsnew/2.4.rst b/Doc/whatsnew/2.4.rst
index 9e438ac..27e412e 100644
--- a/Doc/whatsnew/2.4.rst
+++ b/Doc/whatsnew/2.4.rst
@@ -680,9 +680,6 @@ includes a quick-start tutorial and a reference.
       Written by Facundo Batista and implemented by Facundo Batista, Eric Price,
       Raymond Hettinger, Aahz, and Tim Peters.
 
-   http://research.microsoft.com/~hollasch/cgindex/coding/ieeefloat.html
-      A more detailed overview of the IEEE-754 representation.
-
    http://www.lahey.com/float.htm
       The article uses Fortran code to illustrate many of the problems that floating-
       point inaccuracy can cause.
@@ -756,7 +753,7 @@ API that perform ASCII-only conversions, ignoring the locale setting:
   :ctype:`double` to an ASCII string.
 
 The code for these functions came from the GLib library
-(http://developer.gnome.org/arch/gtk/glib.html), whose developers kindly
+(http://library.gnome.org/devel/glib/stable/), whose developers kindly
 relicensed the relevant functions and donated them to the Python Software
 Foundation.  The :mod:`locale` module  can now change the numeric locale,
 letting extensions such as GTK+  produce the correct results.
diff --git a/Doc/whatsnew/2.6.rst b/Doc/whatsnew/2.6.rst
index cc8a29a..27d8e5c 100644
--- a/Doc/whatsnew/2.6.rst
+++ b/Doc/whatsnew/2.6.rst
@@ -1828,7 +1828,7 @@ changes, or look through the Subversion logs for all the details.
 
   The :mod:`bsddb.dbshelve` module now uses the highest pickling protocol
   available, instead of restricting itself to protocol 1.
-  (Contributed by W. Barnes; :issue:`1551443`.)
+  (Contributed by W. Barnes.)
 
 * The :mod:`cgi` module will now read variables from the query string
   of an HTTP POST request.  This makes it possible to use form actions
@@ -2977,7 +2977,7 @@ Changes to Python's build process and to the C API include:
 * The BerkeleyDB module now has a C API object, available as
   ``bsddb.db.api``.   This object can be used by other C extensions
   that wish to use the :mod:`bsddb` module for their own purposes.
-  (Contributed by Duncan Grisby; :issue:`1551895`.)
+  (Contributed by Duncan Grisby.)
 
 * The new buffer interface, previously described in
   `the PEP 3118 section <#pep-3118-revised-buffer-protocol>`__,