Address a few XXX comments, other fixes.

20 files changed, 43 insertions, 124 deletions

diff --git a/Doc/TODO.txt b/Doc/TODO.txt
index c8d3501bd6..4eb852e0f9 100644
--- a/Doc/TODO.txt
+++ b/Doc/TODO.txt
@@ -4,3 +4,4 @@ To do
 * split very large files and add toctrees
 * finish "Documenting Python"
 * care about XXX comments
+* X-refs to statements
diff --git a/Doc/c-api/newtypes.rst b/Doc/c-api/newtypes.rst
index f8694bf719..09091e1e2d 100644
--- a/Doc/c-api/newtypes.rst
+++ b/Doc/c-api/newtypes.rst
@@ -1155,7 +1155,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 blah, blah.
+   XXX more
 
    This field is inherited by subtypes.
 
@@ -1170,7 +1170,7 @@ The next fields, up to and including :attr:`tp_weaklist`, only exist if the
 
    This field is inherited by subtypes.
 
-   XXX blah, blah.
+   XXX more
 
 
 .. cmember:: long PyTypeObject.tp_dictoffset
@@ -1595,9 +1595,6 @@ objects which may also be containers.  Types which do not store references to
 other objects, or which only store references to atomic types (such as numbers
 or strings), do not need to provide any explicit support for garbage collection.
 
-.. An example showing the use of these interfaces can be found in "Supporting the
-.. Cycle Collector (XXX not found: ../ext/example-cycle-support.html)".
-
 To create a container type, the :attr:`tp_flags` field of the type object must
 include the :const:`Py_TPFLAGS_HAVE_GC` and provide an implementation of the
 :attr:`tp_traverse` handler.  If instances of the type are mutable, a
diff --git a/Doc/extending/newtypes.rst b/Doc/extending/newtypes.rst
index 72aaf1b8b8..1d9ab1c8b6 100644
--- a/Doc/extending/newtypes.rst
+++ b/Doc/extending/newtypes.rst
@@ -232,8 +232,6 @@ at a shell should produce a file :file:`noddy.so` in a subdirectory; move to
 that directory and fire up Python --- you should be able to ``import noddy`` and
 play around with Noddy objects.
 
-.. % $ <-- bow to font-lock  ;-(
-
 That wasn't so hard, was it?
 
 Of course, the current Noddy type is pretty uninteresting. It has no data and
diff --git a/Doc/install/index.rst b/Doc/install/index.rst
index c607eb93c5..980956ad7b 100644
--- a/Doc/install/index.rst
+++ b/Doc/install/index.rst
@@ -517,11 +517,7 @@ might define the following installation scheme::
                            --install-scripts=python/scripts
                            --install-data=python/data
 
-or, equivalently,
-
-.. % $ % -- bow to font-lock
-
-::
+or, equivalently, ::
 
    python setup.py install --home=~/python \
                            --install-purelib=lib \
@@ -533,8 +529,6 @@ or, equivalently,
 the Distutils as it parses your command line options, just as it does when
 parsing your configuration file(s).
 
-.. % $ % -- bow to font-lock
-
 Obviously, specifying the entire installation scheme every time you install a
 new module distribution would be very tedious.  Thus, you can put these options
 into your Distutils config file (see section :ref:`inst-config-files`)::
diff --git a/Doc/library/curses.rst b/Doc/library/curses.rst
index 91af757108..06bac2f8fc 100644
--- a/Doc/library/curses.rst
+++ b/Doc/library/curses.rst
@@ -1170,7 +1170,6 @@ Several constants are available to specify character cell attributes:
 Keys are referred to by integer constants with names starting with  ``KEY_``.
 The exact keycaps available are system dependent.
 
-.. % XXX this table is far too large!
 .. % XXX should this table be alphabetized?
 
 +-------------------+--------------------------------------------+
diff --git a/Doc/library/exceptions.rst b/Doc/library/exceptions.rst
index d6a64fc1b9..808e26a9fa 100644
--- a/Doc/library/exceptions.rst
+++ b/Doc/library/exceptions.rst
@@ -126,12 +126,9 @@ The following exceptions are the exceptions that are actually raised.
 
 .. exception:: EOFError
 
-   Raised when attempting to read beyond the end of a file. (N.B.: the :meth:`read`
-   and :meth:`readline` methods of file objects return an empty string when they
-   hit EOF.)
-
-   .. % XXXJH xrefs here
-   .. % XXXJH xrefs here
+   Raised when attempting to read beyond the end of a file. (N.B.: the
+   :meth:`file.read` and :meth:`file.readline` methods return an empty string
+   when they hit EOF.)
 
 
 .. exception:: FloatingPointError
@@ -154,12 +151,10 @@ The following exceptions are the exceptions that are actually raised.
 
 .. exception:: IOError
 
-   Raised when an I/O operation (such as a :keyword:`print` statement, the built-in
-   :func:`open` function or a method of a file object) fails for an I/O-related
+   Raised when an I/O operation (such as the built-in :func:`print` or
+   :func:`open` functions or a method of a file object) fails for an I/O-related
    reason, e.g., "file not found" or "disk full".
 
-   .. % XXXJH xrefs here
-
    This class is derived from :exc:`EnvironmentError`.  See the discussion above
    for more information on exception instance attributes.
 
@@ -169,8 +164,6 @@ The following exceptions are the exceptions that are actually raised.
    Raised when an :keyword:`import` statement fails to find the module definition
    or when a ``from ... import`` fails to find a name that is to be imported.
 
-   .. % XXXJH xref to import statement?
-
 
 .. exception:: IndexError
 
@@ -191,12 +184,10 @@ The following exceptions are the exceptions that are actually raised.
 .. exception:: KeyboardInterrupt
 
    Raised when the user hits the interrupt key (normally :kbd:`Control-C` or
-   :kbd:`Delete`).  During execution, a check for interrupts is made regularly. The
-   exception inherits from :exc:`BaseException` so as to not be accidentally caught
-   by code that catches :exc:`Exception` and thus prevent the interpreter from
-   exiting.
-
-   .. % XXX(hylton) xrefs here
+   :kbd:`Delete`).  During execution, a check for interrupts is made
+   regularly. The exception inherits from :exc:`BaseException` so as to not be
+   accidentally caught by code that catches :exc:`Exception` and thus prevent
+   the interpreter from exiting.
 
    .. versionchanged:: 2.5
       Changed to inherit from :exc:`BaseException`.
@@ -246,11 +237,7 @@ The following exceptions are the exceptions that are actually raised.
    represented.  This cannot occur for long integers (which would rather raise
    :exc:`MemoryError` than give up).  Because of the lack of standardization of
    floating point exception handling in C, most floating point operations also
-   aren't checked.  For plain integers, all operations that can overflow are
-   checked except left shift, where typical applications prefer to drop bits than
-   raise an exception.
-
-   .. % XXXJH reference to long's and/or int's?
+   aren't checked.
 
 
 .. exception:: ReferenceError
@@ -290,8 +277,6 @@ The following exceptions are the exceptions that are actually raised.
    or :func:`eval`, or when reading the initial script or standard input
    (also interactively).
 
-   .. % XXXJH xref to these functions?
-
    Instances of this class have attributes :attr:`filename`, :attr:`lineno`,
    :attr:`offset` and :attr:`text` for easier access to the details.  :func:`str`
    of the exception instance returns only the message.
@@ -319,8 +304,6 @@ The following exceptions are the exceptions that are actually raised.
    it has another type (such as a string), the object's value is printed and the
    exit status is one.
 
-   .. % XXX(hylton) xref to module sys?
-
    Instances have an attribute :attr:`code` which is set to the proposed exit
    status or error message (defaulting to ``None``). Also, this exception derives
    directly from :exc:`BaseException` and not :exc:`Exception`, since it is not
diff --git a/Doc/library/getopt.rst b/Doc/library/getopt.rst
index 0d9641dd04..53a3d2bf68 100644
--- a/Doc/library/getopt.rst
+++ b/Doc/library/getopt.rst
@@ -9,13 +9,11 @@
 
 This module helps scripts to parse the command line arguments in ``sys.argv``.
 It supports the same conventions as the Unix :cfunc:`getopt` function (including
-the special meanings of arguments of the form '``-``' and '``-``\ ``-``'). Long
+the special meanings of arguments of the form '``-``' and '``--``'). Long
 options similar to those supported by GNU software may be used as well via an
 optional third argument. This module provides a single function and an
 exception:
 
-.. % That's to fool latex2html into leaving the two hyphens alone!
-
 
 .. function:: getopt(args, options[, long_options])
 
@@ -32,7 +30,7 @@ exception:
       work.
 
    *long_options*, if specified, must be a list of strings with the names of the
-   long options which should be supported.  The leading ``'-``\ ``-'`` characters
+   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, *options* should be an empty string.  Long options on the command line
@@ -46,7 +44,7 @@ exception:
    option list was stripped (this is a trailing slice of *args*).  Each
    option-and-value pair returned has the option as its first element, prefixed
    with a hyphen for short options (e.g., ``'-x'``) or two hyphens for long
-   options (e.g., ``'-``\ ``-long-option'``), and the option argument as its
+   options (e.g., ``'--long-option'``), and the option argument as its
    second element, or an empty string if the option has no argument.  The
    options occur in the list in the same order in which they were found, thus
    allowing multiple occurrences.  Long and short options may be mixed.
diff --git a/Doc/library/logging.rst b/Doc/library/logging.rst
index e7406828b3..0035836392 100644
--- a/Doc/library/logging.rst
+++ b/Doc/library/logging.rst
@@ -611,7 +611,7 @@ This time, all messages with a severity of DEBUG or above were handled, and the
 format of the messages was also changed, and output went to the specified file
 rather than the console.
 
-.. XXX logging should probably be updated!
+.. XXX logging should probably be updated for new string formatting!
 
 Formatting uses the old Python string formatting - see section
 :ref:`old-string-formatting`. The format string takes the following common
diff --git a/Doc/library/new.rst b/Doc/library/new.rst
index 852fb58126..438329f44a 100644
--- a/Doc/library/new.rst
+++ b/Doc/library/new.rst
@@ -37,7 +37,7 @@ The :mod:`new` module defines the following functions:
 
    This function is an interface to the :cfunc:`PyCode_New` C function.
 
-   .. % XXX This is still undocumented!!!!!!!!!!!
+   .. XXX This is still undocumented!!!
 
 
 .. function:: module(name[, doc])
diff --git a/Doc/library/nntplib.rst b/Doc/library/nntplib.rst
index 5bc947e11d..faa5115fb4 100644
--- a/Doc/library/nntplib.rst
+++ b/Doc/library/nntplib.rst
@@ -316,7 +316,7 @@ indicates an error, the method raises one of the above exceptions.
    is supplied, then the returned *list* is an empty list. This is an optional NNTP
    extension, and may not be supported by all servers.
 
-   .. % XXX huh?  Should that be name, description?
+   .. % XXX huh?  Should that be (name, description)?
 
    RFC2980 says "It is suggested that this extension be deprecated".  Use
    :meth:`descriptions` or :meth:`description` instead.
diff --git a/Doc/library/ossaudiodev.rst b/Doc/library/ossaudiodev.rst
index 066b26bca2..de82f00b5b 100644
--- a/Doc/library/ossaudiodev.rst
+++ b/Doc/library/ossaudiodev.rst
@@ -89,10 +89,6 @@ the standard audio interface for Linux and recent versions of FreeBSD.
    second is required.  This is a historical artifact for compatibility with the
    older :mod:`linuxaudiodev` module which :mod:`ossaudiodev` supersedes.
 
-   .. % XXX it might also be motivated
-   .. % by my unfounded-but-still-possibly-true belief that the default
-   .. % audio device varies unpredictably across operating systems.  -GW
-
 
 .. function:: openmixer([device])
 
diff --git a/Doc/library/posix.rst b/Doc/library/posix.rst
index 07ecb48f43..2074e4503d 100644
--- a/Doc/library/posix.rst
+++ b/Doc/library/posix.rst
@@ -60,17 +60,11 @@ of Irix, but with Solaris 2.6 and 2.7 you need to do something like::
    CFLAGS="`getconf LFS_CFLAGS`" OPT="-g -O2 $CFLAGS" \
            ./configure
 
-On large-file-capable Linux systems, this might work:
-
-.. % $ <-- bow to font-lock
-
-::
+On large-file-capable Linux systems, this might work::
 
    CFLAGS='-D_LARGEFILE64_SOURCE -D_FILE_OFFSET_BITS=64' OPT="-g -O2 $CFLAGS" \
            ./configure
 
-.. % $ <-- bow to font-lock
-
 
 .. _posix-contents:
 
diff --git a/Doc/library/re.rst b/Doc/library/re.rst
index d5abcdd2a2..b0b8513eed 100644
--- a/Doc/library/re.rst
+++ b/Doc/library/re.rst
@@ -504,7 +504,12 @@ form.
    character class or preceded by an unescaped backslash, all characters from the
    leftmost such ``'#'`` through the end of the line are ignored.
 
-   .. % XXX should add an example here
+   This means that the two following regular expression objects are equal::
+
+      re.compile(r""" [a-z]+   # some letters
+                      \.\.     # two dots
+                      [a-z]*   # perhaps more letters""")
+      re.compile(r"[a-z]+\.\.[a-z]*")
 
 
 .. function:: search(pattern, string[, flags])
diff --git a/Doc/library/stdtypes.rst b/Doc/library/stdtypes.rst
index 9fd6e444b4..96c0b269ba 100644
--- a/Doc/library/stdtypes.rst
+++ b/Doc/library/stdtypes.rst
@@ -137,6 +137,17 @@ be chained arbitrarily; for example, ``x < y <= z`` is equivalent to ``x < y and
 y <= z``, except that *y* is evaluated only once (but in both cases *z* is not
 evaluated at all when ``x < y`` is found to be false).
 
+.. index::
+   pair: operator; comparison
+   operator: ==
+   operator: <
+   operator: >
+   operator: <=
+   operator: >=
+   operator: !=
+   operator: is
+   operator: is not
+
 This table summarizes the comparison operations:
 
 +------------+-------------------------+-------+
@@ -160,14 +171,6 @@ This table summarizes the comparison operations:
 +------------+-------------------------+-------+
 
 .. index::
-   pair: operator; comparison
-   operator: ==
-   operator: is
-   operator: is not
-
-.. % XXX *All* others have funny characters < ! >
-
-.. index::
    pair: object; numeric
    pair: objects; comparing
 
@@ -1021,7 +1024,7 @@ Old String Formatting Operations
    single: % formatting
    single: % interpolation
 
-.. XXX better?
+.. XXX is the note enough?
 
 .. note::
 
@@ -1182,8 +1185,6 @@ Notes:
 Since Python strings have an explicit length, ``%s`` conversions do not assume
 that ``'\0'`` is the end of the string.
 
-.. % XXX Examples?
-
 For safety reasons, floating point precisions are clipped to 50; ``%f``
 conversions for numbers whose absolute value is over 1e25 are replaced by ``%g``
 conversions. [#]_  All other errors raise exceptions.
@@ -1380,7 +1381,8 @@ In addition to the operations on mutable sequence types (see
 :ref:`typesseq-mutable`), bytes objects, being "mutable ASCII strings" have
 further useful methods also found on strings.
 
-.. XXX documented "count" differently above
+.. XXX "count" is documented as a mutable sequence method differently above
+.. XXX perhaps just split bytes and list methods
 
 .. method:: bytes.count(sub[, start[, end]])
 
@@ -1960,6 +1962,8 @@ File Objects
    module: os
    module: socket
 
+.. XXX this is quite out of date, must be updated with "io" module
+
 File objects are implemented using C's ``stdio`` package and can be
 created with the built-in :func:`file` and (more usually) :func:`open`
 constructors described in the :ref:`built-in-funcs` section. [#]_ File
diff --git a/Doc/library/tabnanny.rst b/Doc/library/tabnanny.rst
index 80326557b4..7632b02ab5 100644
--- a/Doc/library/tabnanny.rst
+++ b/Doc/library/tabnanny.rst
@@ -66,5 +66,3 @@ described below.
    Module :mod:`tokenize`
       Lexical scanner for Python source code.
 
-   .. % XXX may be add a reference to IDLE?
-
diff --git a/Doc/library/tix.rst b/Doc/library/tix.rst
index 4701c1583c..c7034ed7a4 100644
--- a/Doc/library/tix.rst
+++ b/Doc/library/tix.rst
@@ -79,8 +79,6 @@ line::
 
    package ifneeded Tix 8.1 [list load "[file join $dir tix8183.dll]" Tix]
 
-.. % $ <-- bow to font-lock
-
 
 Tix Widgets
 -----------
@@ -489,16 +487,6 @@ In addition, :mod:`Tix` augments :mod:`Tkinter` by providing:
    <http://tix.sourceforge.net/dist/current/man/html/TixCmd/tixForm.htm>`_ geometry
    manager based on attachment rules for all Tk widgets.
 
-.. % begin{latexonly}
-.. % \subsection{Tix Class Structure}
-.. % 
-.. % \begin{figure}[hbtp]
-.. % \centerline{\epsfig{file=hierarchy.png,width=.9\textwidth}}
-.. % \vspace{.5cm}
-.. % \caption{The Class Hierarchy of Tix Widgets}
-.. % \end{figure}
-.. % end{latexonly}
-
 
 Tix Commands
 ------------
diff --git a/Doc/library/tkinter.rst b/Doc/library/tkinter.rst
index d52c1e0b57..fe014902f5 100644
--- a/Doc/library/tkinter.rst
+++ b/Doc/library/tkinter.rst
@@ -182,17 +182,6 @@ documentation that exists. Here are some hints:
 A Simple Hello World Program
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-.. % HelloWorld.html
-.. % begin{latexonly}
-.. % \begin{figure}[hbtp]
-.. % \centerline{\epsfig{file=HelloWorld.gif,width=.9\textwidth}}
-.. % \vspace{.5cm}
-.. % \caption{HelloWorld gadget image}
-.. % \end{figure}
-.. % See also the hello-world \ulink{notes}{classes/HelloWorld-notes.html} and
-.. % \ulink{summary}{classes/HelloWorld-summary.html}.
-.. % end{latexonly}
-
 ::
 
    from Tkinter import *
diff --git a/Doc/library/undoc.rst b/Doc/library/undoc.rst
index ad46fc8027..3cc94bb228 100644
--- a/Doc/library/undoc.rst
+++ b/Doc/library/undoc.rst
@@ -172,15 +172,3 @@ must be enabled by uncommenting the appropriate lines in :file:`Modules/Setup`
 in the build tree and either rebuilding Python if the modules are statically
 linked, or building and installing the shared object if using dynamically-loaded
 extensions.
-
-.. % %% lib-old is empty as of Python 2.5
-.. % Those which are written in Python will be installed into the directory
-.. % \file{lib-old/} installed as part of the standard library.  To use
-.. % these, the directory must be added to \code{sys.path}, possibly using
-.. % \envvar{PYTHONPATH}.
-
-.. % XXX need Windows instructions!
-
-
-   --- This section should be empty for Python 3.0.
-
diff --git a/Doc/reference/datamodel.rst b/Doc/reference/datamodel.rst
index 6f6f42c678..ce7704ad0c 100644
--- a/Doc/reference/datamodel.rst
+++ b/Doc/reference/datamodel.rst
@@ -1193,12 +1193,6 @@ Basic customization
    used when an "informal" string representation of instances of that class is
    required.
 
-   .. index::
-      pair: string; conversion
-      pair: reverse; quotes
-      pair: backward; quotes
-      single: back-quotes
-
    This is typically used for debugging, so it is important that the representation
    is information-rich and unambiguous.
 
diff --git a/Doc/tutorial/introduction.rst b/Doc/tutorial/introduction.rst
index 456307de45..0c37f23c9c 100644
--- a/Doc/tutorial/introduction.rst
+++ b/Doc/tutorial/introduction.rst
@@ -11,13 +11,6 @@ with a prompt are output from the interpreter. Note that a secondary prompt on a
 line by itself in an example means you must type a blank line; this is used to
 end a multi-line command.
 
-.. % 
-.. % \footnote{
-.. % I'd prefer to use different fonts to distinguish input
-.. % from output, but the amount of LaTeX hacking that would require
-.. % is currently beyond my ability.
-.. % }
-
 Many of the examples in this manual, even those entered at the interactive
 prompt, include comments.  Comments in Python start with the hash character,
 ``'#'``, and extend to the end of the physical line.  A comment may appear at