241 files changed, 18913 insertions, 18876 deletions

diff --git a/.hgsvnexternals b/.hgsvnexternals
index 048f7c8..28567dc 100644
--- a/.hgsvnexternals
+++ b/.hgsvnexternals
@@ -1,3 +1,2 @@
 [Tools]
  2to3 http://svn.python.org/projects/sandbox/trunk/2to3/
- 
diff --git a/Doc/Makefile b/Doc/Makefile
index 22f852b..189a2f7 100644
--- a/Doc/Makefile
+++ b/Doc/Makefile
@@ -16,10 +16,11 @@ ALLSPHINXOPTS = -b $(BUILDER) -d build/doctrees -D latex_paper_size=$(PAPER) \
 
 help:
 	@echo "Please use \`make <target>' where <target> is one of"
-	@echo "  html   to make standalone HTML files"
-	@echo "  web    to make file usable by Sphinx.web"
+	@echo "  html     to make standalone HTML files"
+	@echo "  web      to make file usable by Sphinx.web"
 	@echo "  htmlhelp to make HTML files and a HTML help project"
-	@echo "  latex  to make LaTeX files, you can set PAPER=a4 or PAPER=letter"
+	@echo "  latex    to make LaTeX files, you can set PAPER=a4 or PAPER=letter"
+	@echo "  changes  to make an overview over all changed/added/deprecated items"
 
 checkout:
 	@if [ ! -d tools/sphinx ]; then \
@@ -66,6 +67,10 @@ latex: build
 	@echo "Run \`make all-pdf' or \`make all-ps' in that directory to" \
 	      "run these through (pdf)latex."
 
+changes: BUILDER = changes
+changes: build
+	@echo "The overview file is in build/changes."
+
 clean:
 	-rm -rf build/*
 	-rm -rf tools/sphinx
diff --git a/Doc/README.txt b/Doc/README.txt
index 9db4f4c..c6f685c 100644
--- a/Doc/README.txt
+++ b/Doc/README.txt
@@ -56,6 +56,10 @@ Available make targets are:
  * "latex", which builds LaTeX source files that can be run with "pdflatex"
    to produce PDF documents.
 
+ * "changes", which builds an overview over all versionadded/versionchanged/
+   deprecated items in the current version. This is meant as a help for the
+   writer of the "What's New" document.
+
 A "make update" updates the Subversion checkouts in `tools/`.
 
 
diff --git a/Doc/c-api/exceptions.rst b/Doc/c-api/exceptions.rst
index 9413762..3e06e4f 100644
--- a/Doc/c-api/exceptions.rst
+++ b/Doc/c-api/exceptions.rst
@@ -31,8 +31,8 @@ The error indicator consists of three Python objects corresponding to the result
 of ``sys.exc_info()``.  API functions exist to interact with the error indicator
 in various ways.  There is a separate error indicator for each thread.
 
-.. % XXX Order of these should be more thoughtful.
-.. % Either alphabetical or some kind of structure.
+.. XXX Order of these should be more thoughtful.
+   Either alphabetical or some kind of structure.
 
 
 .. cfunction:: void PyErr_Print()
diff --git a/Doc/c-api/init.rst b/Doc/c-api/init.rst
index a4f25fa..dac37e1 100644
--- a/Doc/c-api/init.rst
+++ b/Doc/c-api/init.rst
@@ -264,7 +264,7 @@ Initialization, Finalization, and Threads
    as the list ``sys.path``, which may be modified to change the future search path
    for loaded modules.
 
-   .. % XXX should give the exact rules
+   .. XXX should give the exact rules
 
 
 .. cfunction:: const char* Py_GetVersion()
@@ -357,8 +357,8 @@ Initialization, Finalization, and Threads
    to initialize ``sys.argv``, a fatal condition is signalled using
    :cfunc:`Py_FatalError`.
 
-   .. % XXX impl. doesn't seem consistent in allowing 0/NULL for the params;
-   .. % check w/ Guido.
+   .. XXX impl. doesn't seem consistent in allowing 0/NULL for the params;
+      check w/ Guido.
 
 
 .. _threads:
diff --git a/Doc/c-api/intro.rst b/Doc/c-api/intro.rst
index 54412cd..2742a53 100644
--- a/Doc/c-api/intro.rst
+++ b/Doc/c-api/intro.rst
@@ -484,7 +484,7 @@ Here is the corresponding C code, in all its glory::
    single: PyErr_Clear()
    single: Py_XDECREF()
 
-This example represents an endorsed use of the :keyword:`goto` statement  in C!
+This example represents an endorsed use of the ``goto`` statement  in C!
 It illustrates the use of :cfunc:`PyErr_ExceptionMatches` and
 :cfunc:`PyErr_Clear` to handle specific exceptions, and the use of
 :cfunc:`Py_XDECREF` to dispose of owned references that may be *NULL* (note the
diff --git a/Doc/c-api/newtypes.rst b/Doc/c-api/newtypes.rst
index b557957..88a4f2f 100644
--- a/Doc/c-api/newtypes.rst
+++ b/Doc/c-api/newtypes.rst
@@ -459,7 +459,7 @@ type objects) *must* have the :attr:`ob_size` field.
    declare the instance struct) and this in turn includes the :attr:`_ob_prev` and
    :attr:`_ob_next` fields if they are present.  This means that the only correct
    way to get an initializer for the :attr:`tp_basicsize` is to use the
-   :keyword:`sizeof` operator on the struct used to declare the instance layout.
+   ``sizeof`` operator on the struct used to declare the instance layout.
    The basic size does not include the GC header size (this is new in Python 2.2;
    in 2.1 and 2.0, the GC header size was included in :attr:`tp_basicsize`).
 
@@ -1145,7 +1145,7 @@ The next fields, up to and including :attr:`tp_weaklist`, only exist if the
 
       PyObject * tp_descr_get(PyObject *self, PyObject *obj, PyObject *type);
 
-   XXX more
+   XXX explain.
 
    This field is inherited by subtypes.
 
@@ -1160,7 +1160,7 @@ The next fields, up to and including :attr:`tp_weaklist`, only exist if the
 
    This field is inherited by subtypes.
 
-   XXX more
+   XXX explain.
 
 
 .. cmember:: long PyTypeObject.tp_dictoffset
@@ -1683,10 +1683,9 @@ member in the :ctype:`PyTypeObject` structure should be *NULL*.  Otherwise, the
    and :exc:`SystemError` should be raised when *segment* specifies a segment that
    doesn't exist.
 
-   .. % Why doesn't it raise ValueError for this one?
-   .. % GJS: because you shouldn't be calling it with an invalid
-   .. % segment. That indicates a blatant programming error in the C
-   .. % code.
+   .. Why doesn't it raise ValueError for this one?
+      GJS: because you shouldn't be calling it with an invalid
+      segment. That indicates a blatant programming error in the C code.
 
 
 .. ctype:: Py_ssize_t (*segcountproc) (PyObject *self, Py_ssize_t *lenp)
diff --git a/Doc/distutils/setupscript.rst b/Doc/distutils/setupscript.rst
index 3ffcc78..8b88b58 100644
--- a/Doc/distutils/setupscript.rst
+++ b/Doc/distutils/setupscript.rst
@@ -137,7 +137,7 @@ the Distutils to go out and find the right files; you have to specify the
 extension name, source file(s), and any compile/link requirements (include
 directories, libraries to link with, etc.).
 
-.. % XXX read over this section
+.. XXX read over this section
 
 All of this is done through another keyword argument to :func:`setup`, the
 :option:`ext_modules` option.  :option:`ext_modules` is just a list of
diff --git a/Doc/documenting/fromlatex.rst b/Doc/documenting/fromlatex.rst
index 42045f7..116524a 100644
--- a/Doc/documenting/fromlatex.rst
+++ b/Doc/documenting/fromlatex.rst
@@ -154,25 +154,35 @@ These changes to information units should be noted:
 
         Description.
 
-* **New information unit**
+* **New information units**
 
-  There is a new generic information unit called "describe" which can be used
-  to document things that are not covered by the other units::
+  There are new generic information units: One is called "describe" and can be
+  used to document things that are not covered by the other units::
 
      .. describe:: a == b
 
         The equals operator.
 
+  The others are::
+
+     .. cmdoption:: -O
+
+        Describes a command-line option.
+
+     .. envvar:: PYTHONINSPECT
+
+        Describes an environment variable.
+
 
 Structure
 ---------
 
-The LaTeX docs were split in several toplevel manuals.  Now, all files
-are part of the same documentation tree, as indicated by the *toctree*
-directives in the sources.  Every *toctree* directive embeds other files
-as subdocuments of the current file (this structure is not necessarily
-mirrored in the filesystem layout).  The toplevel file is
-:file:`contents.rst`.
+The LaTeX docs were split in several toplevel manuals.  Now, all files are part
+of the same documentation tree, as indicated by the *toctree* directives in the
+sources (though individual output formats may choose to split them up into parts
+again).  Every *toctree* directive embeds other files as subdocuments of the
+current file (this structure is not necessarily mirrored in the filesystem
+layout).  The toplevel file is :file:`contents.rst`.
 
 However, most of the old directory structure has been kept, with the
 directories renamed as follows:
@@ -184,7 +194,7 @@ directories renamed as follows:
 * :file:`inst` -> :file:`installing`
 * :file:`lib` -> :file:`library`
 * :file:`mac` -> merged into :file:`library`, with :file:`mac/using.tex`
-  moved to :file:`howto/pythonmac.rst`
+  moved to :file:`using/mac.rst`
 * :file:`ref` -> :file:`reference`
 * :file:`tut` -> :file:`tutorial`, with the single TeX file split up
 
diff --git a/Doc/documenting/markup.rst b/Doc/documenting/markup.rst
index a246d62..f3a8237 100644
--- a/Doc/documenting/markup.rst
+++ b/Doc/documenting/markup.rst
@@ -455,7 +455,7 @@ in a different style:
 
 .. describe:: keyword
 
-   The name of a keyword in a programming language.
+   The name of a keyword in Python.
 
 .. describe:: mailheader
 
diff --git a/Doc/documenting/sphinx.rst b/Doc/documenting/sphinx.rst
index 85e8b5e..43da14e 100644
--- a/Doc/documenting/sphinx.rst
+++ b/Doc/documenting/sphinx.rst
@@ -47,14 +47,30 @@ unused_files : list of strings
    could be docs for temporarily disabled modules or documentation that's not
    yet ready for public consumption.
 
-last_updated_format : string
+add_function_parentheses : bool
+   If true, ``()`` will be appended to the content of ``:func:``, ``:meth:`` and
+   ``:cfunc:`` cross-references.
+
+add_module_names : bool
+   If true, the current module name will be prepended to all description unit
+   titles (such as ``.. function::``).
+
+Builder-specific variables
+^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+html_download_base_url : string
+   The base URL for download links on the download page.
+
+html_last_updated_fmt : string
    If this is not an empty string, it will be given to ``time.strftime()`` and
    written to each generated output file after "last updated on:".
 
-use_smartypants : bool
+html_use_smartypants : bool
    If true, use SmartyPants to convert quotes and dashes to the typographically
    correct entities.
 
-add_function_parentheses : bool
-   If true, ``()`` will be appended to the content of ``:func:``, ``:meth:`` and
-   ``:cfunc:`` cross-references.
\ No newline at end of file
+latex_paper_size : "letter" or "a4"
+   The paper size option for the LaTeX document class.
+
+latex_font_size : "10pt", "11pt" or "12pt"
+   The font size option for the LaTeX document class.
\ No newline at end of file
diff --git a/Doc/extending/embedding.rst b/Doc/extending/embedding.rst
index a50c008..6ba2c67 100644
--- a/Doc/extending/embedding.rst
+++ b/Doc/extending/embedding.rst
@@ -155,11 +155,7 @@ then the result should be::
 
 Although the program is quite large for its functionality, most of the code is
 for data conversion between Python and C, and for error reporting.  The
-interesting part with respect to embedding Python starts with
-
-.. % $
-
-::
+interesting part with respect to embedding Python starts with ::
 
    Py_Initialize();
    pName = PyString_FromString(argv[1]);
@@ -239,15 +235,8 @@ With these extensions, the Python script can do things like ::
 In a real application, the methods will expose an API of the application to
 Python.
 
-.. % \section{For the future}
-.. % 
-.. % You don't happen to have a nice library to get textual
-.. % equivalents of numeric values do you :-) ?
-.. % Callbacks here ? (I may be using information from that section
-.. % ?!)
-.. % threads
-.. % code examples do not really behave well if errors happen
-.. % (what to watch out for)
+.. TODO: threads, code examples do not really behave well if errors happen
+   (what to watch out for)
 
 
 .. _embeddingincplusplus:
diff --git a/Doc/extending/extending.rst b/Doc/extending/extending.rst
index 9b5e0fe..5459a7d 100644
--- a/Doc/extending/extending.rst
+++ b/Doc/extending/extending.rst
@@ -306,7 +306,7 @@ function.
 The method table must be passed to the interpreter in the module's
 initialization function.  The initialization function must be named
 :cfunc:`initname`, where *name* is the name of the module, and should be the
-only non-\ :keyword:`static` item defined in the module file::
+only non-\ ``static`` item defined in the module file::
 
    PyMODINIT_FUNC
    initspam(void)
@@ -660,11 +660,7 @@ it returns false and raises an appropriate exception.
 .. index:: single: Philbrick, Geoff
 
 Here is an example module which uses keywords, based on an example by Geoff
-Philbrick (philbrick@hks.com):
-
-.. % 
-
-::
+Philbrick (philbrick@hks.com)::
 
    #include "Python.h"
 
@@ -762,8 +758,8 @@ Reference Counts
 
 In languages like C or C++, the programmer is responsible for dynamic allocation
 and deallocation of memory on the heap.  In C, this is done using the functions
-:cfunc:`malloc` and :cfunc:`free`.  In C++, the operators :keyword:`new` and
-:keyword:`delete` are used with essentially the same meaning and we'll restrict
+:cfunc:`malloc` and :cfunc:`free`.  In C++, the operators ``new`` and
+``delete`` are used with essentially the same meaning and we'll restrict
 the following discussion to the C case.
 
 Every block of memory allocated with :cfunc:`malloc` should eventually be
@@ -1036,11 +1032,10 @@ that it is always a tuple. [#]_
 
 It is a severe error to ever let a *NULL* pointer "escape" to the Python user.
 
-.. % Frank Stajano:
-.. % A pedagogically buggy example, along the lines of the previous listing,
-.. % would be helpful here -- showing in more concrete terms what sort of
-.. % actions could cause the problem. I can't very well imagine it from the
-.. % description.
+.. Frank Stajano:
+   A pedagogically buggy example, along the lines of the previous listing, would
+   be helpful here -- showing in more concrete terms what sort of actions could
+   cause the problem. I can't very well imagine it from the description.
 
 
 .. _cplusplus:
@@ -1076,7 +1071,7 @@ lists, this new collection type should have a set of C functions for direct
 manipulation from other extension modules.
 
 At first sight this seems easy: just write the functions (without declaring them
-:keyword:`static`, of course), provide an appropriate header file, and document
+``static``, of course), provide an appropriate header file, and document
 the C API. And in fact this would work if all extension modules were always
 linked statically with the Python interpreter. When modules are used as shared
 libraries, however, the symbols defined in one module may not be visible to
@@ -1089,7 +1084,7 @@ the module whose functions one wishes to call might not have been loaded yet!
 
 Portability therefore requires not to make any assumptions about symbol
 visibility. This means that all symbols in extension modules should be declared
-:keyword:`static`, except for the module's initialization function, in order to
+``static``, except for the module's initialization function, in order to
 avoid name clashes with other extension modules (as discussed in section
 :ref:`methodtable`). And it means that symbols that *should* be accessible from
 other extension modules must be exported in a different way.
@@ -1124,7 +1119,7 @@ reality (such as adding "spam" to every command). This function
 :cfunc:`PySpam_System` is also exported to other extension modules.
 
 The function :cfunc:`PySpam_System` is a plain C function, declared
-:keyword:`static` like everything else::
+``static`` like everything else::
 
    static int
    PySpam_System(const char *command)
@@ -1180,7 +1175,7 @@ function must take care of initializing the C API pointer array::
            PyModule_AddObject(m, "_C_API", c_api_object);
    }
 
-Note that ``PySpam_API`` is declared :keyword:`static`; otherwise the pointer
+Note that ``PySpam_API`` is declared ``static``; otherwise the pointer
 array would disappear when :func:`initspam` terminates!
 
 The bulk of the work is in the header file :file:`spammodule.h`, which looks
diff --git a/Doc/extending/newtypes.rst b/Doc/extending/newtypes.rst
index e2cf6df..cbe3b68 100644
--- a/Doc/extending/newtypes.rst
+++ b/Doc/extending/newtypes.rst
@@ -1196,16 +1196,14 @@ class object, and get the doc string using its :attr:`__doc__` attribute.
 As with the :attr:`tp_methods` table, a sentinel entry with a :attr:`name` value
 of *NULL* is required.
 
-.. % XXX Descriptors need to be explained in more detail somewhere, but
-.. % not here.
-.. % 
-.. % Descriptor objects have two handler functions which correspond to
-.. % the \member{tp_getattro} and \member{tp_setattro} handlers.  The
-.. % \method{__get__()} handler is a function which is passed the
-.. % descriptor, instance, and type objects, and returns the value of the
-.. % attribute, or it returns \NULL{} and sets an exception.  The
-.. % \method{__set__()} handler is passed the descriptor, instance, type,
-.. % and new value;
+.. XXX Descriptors need to be explained in more detail somewhere, but not here.
+   
+   Descriptor objects have two handler functions which correspond to the
+   \member{tp_getattro} and \member{tp_setattro} handlers.  The
+   \method{__get__()} handler is a function which is passed the descriptor,
+   instance, and type objects, and returns the value of the attribute, or it
+   returns \NULL{} and sets an exception.  The \method{__set__()} handler is
+   passed the descriptor, instance, type, and new value;
 
 
 Type-specific Attribute Management
diff --git a/Doc/extending/windows.rst b/Doc/extending/windows.rst
index 7a66afe..a34ba2b 100644
--- a/Doc/extending/windows.rst
+++ b/Doc/extending/windows.rst
@@ -7,8 +7,6 @@
 Building C and C++ Extensions on Windows
 ****************************************
 
-.. % 
-
 This chapter briefly explains how to create a Windows extension module for
 Python using Microsoft Visual C++, and follows with more detailed background
 information on how it works.  The explanatory material is useful for both the
diff --git a/Doc/howto/advocacy.rst b/Doc/howto/advocacy.rst
index 1f1754a..7d7706e 100644
--- a/Doc/howto/advocacy.rst
+++ b/Doc/howto/advocacy.rst
@@ -302,11 +302,11 @@ http://www.pythonology.com/success
    The Python Success Stories are a collection of stories from successful users of
    Python, with the emphasis on business and corporate users.
 
-.. % \term{\url{http://www.fsbassociates.com/books/pythonchpt1.htm}}
-.. % The first chapter of \emph{Internet Programming with Python} also
-.. % examines some of the reasons for using Python.  The book is well worth
-.. % buying, but the publishers have made the first chapter available on
-.. % the Web.
+.. http://www.fsbassociates.com/books/pythonchpt1.htm
+   The first chapter of \emph{Internet Programming with Python} also
+   examines some of the reasons for using Python.  The book is well worth
+   buying, but the publishers have made the first chapter available on
+   the Web.
 
 http://home.pacbell.net/ouster/scripting.html
    John Ousterhout's white paper on scripting is a good argument for the utility of
@@ -333,9 +333,9 @@ http://pythonjournal.cognizor.com/pyj1/Everitt-Feit_interview98-V1.html
    to show that choosing Python didn't introduce any difficulties into a company's
    development process, and provided some substantial benefits.
 
-.. % \term{\url{http://www.python.org/psa/Commercial.html}}
-.. % Robin Friedrich wrote this document on how to support Python's use in
-.. % commercial projects.
+.. http://www.python.org/psa/Commercial.html
+   Robin Friedrich wrote this document on how to support Python's use in
+   commercial projects.
 
 http://www.python.org/workshops/1997-10/proceedings/stein.ps
    For the 6th Python conference, Greg Stein presented a paper that traced Python's
diff --git a/Doc/howto/doanddont.rst b/Doc/howto/doanddont.rst
index ace5bed..0e6b3e8 100644
--- a/Doc/howto/doanddont.rst
+++ b/Doc/howto/doanddont.rst
@@ -291,7 +291,7 @@ are often more then is comfortable to put in one line, many people do::
       calculate_number(10, 20) != forbulate(500, 360):
          pass
 
-You should realize that this is dangerous: a stray space after the ``XXX`` would
+You should realize that this is dangerous: a stray space after the ``\`` would
 make this line wrong, and stray spaces are notoriously hard to see in editors.
 In this case, at least it would be a syntax error, but if the code was::
 
diff --git a/Doc/howto/regex.rst b/Doc/howto/regex.rst
index 783bec1..6adecd7 100644
--- a/Doc/howto/regex.rst
+++ b/Doc/howto/regex.rst
@@ -5,11 +5,11 @@
 :Author: A.M. Kuchling
 :Release: 0.05
 
-.. % TODO:
-.. % Document lookbehind assertions
-.. % Better way of displaying a RE, a string, and what it matches
-.. % Mention optional argument to match.groups()
-.. % Unicode (at least a reference)
+.. TODO:
+   Document lookbehind assertions
+   Better way of displaying a RE, a string, and what it matches
+   Mention optional argument to match.groups()
+   Unicode (at least a reference)
 
 
 .. topic:: Abstract
@@ -91,8 +91,6 @@ is the same as ``[a-c]``, which uses a range to express the same set of
 characters.  If you wanted to match only lowercase letters, your RE would be
 ``[a-z]``.
 
-.. % $
-
 Metacharacters are not active inside classes.  For example, ``[akm$]`` will
 match any of the characters ``'a'``, ``'k'``, ``'m'``, or ``'$'``; ``'$'`` is
 usually a metacharacter, but inside a character class it's stripped of its
@@ -679,8 +677,8 @@ given location, they can obviously be matched an infinite number of times.
       >>> print(re.search('^From', 'Reciting From Memory'))
       None
 
-   .. % To match a literal \character{\^}, use \regexp{\e\^} or enclose it
-   .. % inside a character class, as in \regexp{[{\e}\^]}.
+   .. To match a literal \character{\^}, use \regexp{\e\^} or enclose it
+   .. inside a character class, as in \regexp{[{\e}\^]}.
 
 ``$``
    Matches at the end of a line, which is defined as either the end of the string,
@@ -696,8 +694,6 @@ given location, they can obviously be matched an infinite number of times.
    To match a literal ``'$'``, use ``\$`` or enclose it inside a character class,
    as in  ``[$]``.
 
-   .. % $
-
 ``\A``
    Matches only at the start of the string.  When not in :const:`MULTILINE` mode,
    ``\A`` and ``^`` are effectively the same.  In :const:`MULTILINE` mode, they're
@@ -980,12 +976,8 @@ filenames where the extension is not ``bat``? Some incorrect attempts:
 that the first character of the extension is not a ``b``.  This is wrong,
 because the pattern also doesn't match ``foo.bar``.
 
-.. % $
-
 ``.*[.]([^b]..|.[^a].|..[^t])$``
 
-.. % Messes up the HTML without the curly braces around \^
-
 The expression gets messier when you try to patch up the first solution by
 requiring one of the following cases to match: the first character of the
 extension isn't ``b``; the second character isn't ``a``; or the third character
@@ -1013,16 +1005,12 @@ match, the whole pattern will fail.  The trailing ``$`` is required to ensure
 that something like ``sample.batch``, where the extension only starts with
 ``bat``, will be allowed.
 
-.. % $
-
 Excluding another filename extension is now easy; simply add it as an
 alternative inside the assertion.  The following pattern excludes filenames that
 end in either ``bat`` or ``exe``:
 
 ``.*[.](?!bat$|exe$).*$``
 
-.. % $
-
 
 Modifying Strings
 =================
@@ -1343,16 +1331,10 @@ enables REs to be formatted more neatly::
     \s*$                # Trailing whitespace to end-of-line
    """, re.VERBOSE)
 
-This is far more readable than:
-
-.. % $
-
-::
+This is far more readable than::
 
    pat = re.compile(r"\s*(?P<header>[^:]+)\s*:(?P<value>.*?)\s*$")
 
-.. % $
-
 
 Feedback
 ========
diff --git a/Doc/install/index.rst b/Doc/install/index.rst
index 1bfc703..c830c8d 100644
--- a/Doc/install/index.rst
+++ b/Doc/install/index.rst
@@ -10,18 +10,17 @@
 :Release: |version|
 :Date: |today|
 
-.. % TODO:
-.. % Fill in XXX comments
-
-.. % The audience for this document includes people who don't know anything
-.. % about Python and aren't about to learn the language just in order to
-.. % install and maintain it for their users, i.e. system administrators.
-.. % Thus, I have to be sure to explain the basics at some point:
-.. % sys.path and PYTHONPATH at least.  Should probably give pointers to
-.. % other docs on "import site", PYTHONSTARTUP, PYTHONHOME, etc.
-.. % 
-.. % Finally, it might be useful to include all the material from my "Care
-.. % and Feeding of a Python Installation" talk in here somewhere.  Yow!
+.. TODO: Fill in XXX comments
+
+.. The audience for this document includes people who don't know anything
+   about Python and aren't about to learn the language just in order to
+   install and maintain it for their users, i.e. system administrators.
+   Thus, I have to be sure to explain the basics at some point:
+   sys.path and PYTHONPATH at least.  Should probably give pointers to
+   other docs on "import site", PYTHONSTARTUP, PYTHONHOME, etc.
+   
+   Finally, it might be useful to include all the material from my "Care
+   and Feeding of a Python Installation" talk in here somewhere.  Yow!
 
 .. topic:: Abstract
 
@@ -565,11 +564,11 @@ environment variables, such as Mac OS 9, the configuration variables supplied by
 the Distutils are the only ones you can use.) See section :ref:`inst-config-files`
 for details.
 
-.. % XXX need some Windows examples---when would custom
-.. % installation schemes be needed on those platforms?
+.. XXX need some Windows examples---when would custom installation schemes be
+   needed on those platforms?
 
-.. % XXX I'm not sure where this section should go.
 
+.. XXX I'm not sure where this section should go.
 
 .. _inst-search-path:
 
@@ -881,8 +880,8 @@ Microsoft Visual C++, which uses COFF as the object file format.) For this
 reason you have to convert Python's library :file:`python25.lib` into the
 Borland format.  You can do this as follows:
 
-.. % Should we mention that users have to create cfg-files for the compiler?
-.. % see also http://community.borland.com/article/0,1410,21205,00.html
+.. Should we mention that users have to create cfg-files for the compiler?
+.. see also http://community.borland.com/article/0,1410,21205,00.html
 
 ::
 
@@ -940,8 +939,8 @@ a good program for this task at
 http://starship.python.net/crew/kernr/mingw32/Notes.html, see at  PExports 0.42h
 there.)
 
-.. % I don't understand what the next line means. --amk
-.. % (inclusive the references on data structures.)
+.. I don't understand what the next line means. --amk
+.. (inclusive the references on data structures.)
 
 ::
 
diff --git a/Doc/library/aepack.rst b/Doc/library/aepack.rst
index 0ee93e5..daaa9b2 100644
--- a/Doc/library/aepack.rst
+++ b/Doc/library/aepack.rst
@@ -6,9 +6,7 @@
    :platform: Mac
    :synopsis: Conversion between Python variables and AppleEvent data containers.
 .. sectionauthor:: Vincent Marchetti <vincem@en.com>
-
-
-.. % \moduleauthor{Jack Jansen?}{email}
+.. moduleauthor:: Jack Jansen
 
 The :mod:`aepack` module defines functions for converting (packing) Python
 variables to AppleEvent descriptors and back (unpacking). Within Python the
diff --git a/Doc/library/aetools.rst b/Doc/library/aetools.rst
index b5fd4ad..da427eb 100644
--- a/Doc/library/aetools.rst
+++ b/Doc/library/aetools.rst
@@ -6,9 +6,7 @@
    :platform: Mac
    :synopsis: Basic support for sending Apple Events
 .. sectionauthor:: Jack Jansen <Jack.Jansen@cwi.nl>
-
-
-.. % \moduleauthor{Jack Jansen?}{email}
+.. moduleauthor:: Jack Jansen
 
 The :mod:`aetools` module contains the basic functionality on which Python
 AppleScript client support is built. It also imports and re-exports the core
diff --git a/Doc/library/aetypes.rst b/Doc/library/aetypes.rst
index 0dd0a88..c8c5d80 100644
--- a/Doc/library/aetypes.rst
+++ b/Doc/library/aetypes.rst
@@ -6,9 +6,7 @@
    :platform: Mac
    :synopsis: Python representation of the Apple Event Object Model.
 .. sectionauthor:: Vincent Marchetti <vincem@en.com>
-
-
-.. % \moduleauthor{Jack Jansen?}{email}
+.. moduleauthor:: Jack Jansen
 
 The :mod:`aetypes` defines classes used to represent Apple Event data
 descriptors and Apple Event object specifiers.
diff --git a/Doc/library/asyncore.rst b/Doc/library/asyncore.rst
index 2ed3c92..6830bae 100644
--- a/Doc/library/asyncore.rst
+++ b/Doc/library/asyncore.rst
@@ -8,13 +8,12 @@
 .. moduleauthor:: Sam Rushing <rushing@nightmare.com>
 .. sectionauthor:: Christopher Petrilli <petrilli@amber.org>
 .. sectionauthor:: Steve Holden <sholden@holdenweb.com>
+.. heavily adapted from original documentation by Sam Rushing
 
 
 This module provides the basic infrastructure for writing asynchronous  socket
 service clients and servers.
 
-.. % Heavily adapted from original documentation by Sam Rushing.
-
 There are only two ways to have a program on a single processor do  "more than
 one thing at a time." Multi-threaded programming is the  simplest and most
 popular way to do it, but there is another very different technique, that lets
diff --git a/Doc/library/audioop.rst b/Doc/library/audioop.rst
index 7779610..8ee2795 100644
--- a/Doc/library/audioop.rst
+++ b/Doc/library/audioop.rst