Merged revisions 59605-59624 via svnmerge from

svn+ssh://pythondev@svn.python.org/python/trunk

........
  r59606 | georg.brandl | 2007-12-29 11:57:00 +0100 (Sat, 29 Dec 2007) | 2 lines

  Some cleanup in the docs.
........
  r59611 | martin.v.loewis | 2007-12-29 19:49:21 +0100 (Sat, 29 Dec 2007) | 2 lines

  Bug #1699: Define _BSD_SOURCE only on OpenBSD.
........
  r59612 | raymond.hettinger | 2007-12-29 23:09:34 +0100 (Sat, 29 Dec 2007) | 1 line

  Simpler documentation for itertools.tee().  Should be backported.
........
  r59613 | raymond.hettinger | 2007-12-29 23:16:24 +0100 (Sat, 29 Dec 2007) | 1 line

  Improve docs for itertools.groupby().  The use of xrange(0) to create a unique object is less obvious than object().
........
  r59620 | christian.heimes | 2007-12-31 15:47:07 +0100 (Mon, 31 Dec 2007) | 3 lines

  Added wininst-9.0.exe executable for VS 2008
  Integrated bdist_wininst into PCBuild9 directory
........
  r59621 | christian.heimes | 2007-12-31 15:51:18 +0100 (Mon, 31 Dec 2007) | 1 line

  Moved PCbuild directory to PC/VS7.1
........
  r59622 | christian.heimes | 2007-12-31 15:59:26 +0100 (Mon, 31 Dec 2007) | 1 line

  Fix paths for build bot
........
  r59623 | christian.heimes | 2007-12-31 16:02:41 +0100 (Mon, 31 Dec 2007) | 1 line

  Fix paths for build bot, part 2
........
  r59624 | christian.heimes | 2007-12-31 16:18:55 +0100 (Mon, 31 Dec 2007) | 1 line

  Renamed PCBuild9 directory to PCBuild
........

.hgsvnexternals

 [Tools]
  2to3 http://svn.python.org/projects/sandbox/trunk/2to3/
- 

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

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/`.
 
 

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()

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:

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

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)

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

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
 

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
 

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.
+latex_paper_size : "letter" or "a4"
+   The paper size option for the LaTeX document class.
+
\ No newline at end of file
+latex_font_size : "10pt", "11pt" or "12pt"
+   The font size option for the LaTeX document class.
\ No newline at end of file

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:

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

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

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

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

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::
 

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
 ========

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.)
 
 ::
 

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

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

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.

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

Doc/library/audioop.rst

@@ -19,7 +19,7 @@ specified otherwise.
 
 This module provides support for a-LAW, u-LAW and Intel/DVI ADPCM encodings.
 
-.. % This para is mostly here to provide an excuse for the index entries...
+.. This para is mostly here to provide an excuse for the index entries...
 
 A few of the more complicated operations only take 16-bit samples, otherwise the
 sample size (in bytes) is always a parameter of the operation.

Doc/library/bisect.rst

@@ -5,11 +5,7 @@
 .. module:: bisect
    :synopsis: Array bisection algorithms for binary searching.
 .. sectionauthor:: Fred L. Drake, Jr. <fdrake@acm.org>
-
-
-.. % LaTeX produced by Fred L. Drake, Jr. <fdrake@acm.org>, with an
-.. % example based on the PyModules FAQ entry by Aaron Watters
-.. % <arw@pythonpros.com>.
+.. example based on the PyModules FAQ entry by Aaron Watters <arw@pythonpros.com>
 
 This module provides support for maintaining a list in sorted order without
 having to sort the list after each insertion.  For long lists of items with

Doc/library/cgi.rst

@@ -176,7 +176,7 @@ intuitive way.  The interface doesn't make the techniques described in previous
 sections obsolete --- they are still useful to process file uploads efficiently,
 for example.
 
-.. % XXX: Is this true ?
+.. XXX: Is this true ?
 
 The interface consists of two simple methods. Using the methods you can process
 form data in a generic way, without the need to worry whether only one or more

Doc/library/codeop.rst

@@ -7,9 +7,6 @@
 .. sectionauthor:: Moshe Zadka <moshez@zadka.site.co.il>
 .. sectionauthor:: Michael Hudson <mwh@python.net>
 
-
-.. % LaTeXed from excellent doc-string.
-
 The :mod:`codeop` module provides utilities upon which the Python
 read-eval-print loop can be emulated, as is done in the :mod:`code` module.  As
 a result, you probably don't want to use the module directly; if you want to
@@ -29,7 +26,6 @@ of doing them both.
 
 To do just the former:
 
-
 .. function:: compile_command(source[, filename[, symbol]])
 
    Tries to compile *source*, which should be a string of Python code and return a

Doc/library/collections.rst

@@ -100,7 +100,7 @@ particular functionality, for example::
    where only the most recent activity is of interest.
 
    .. versionchanged:: 2.6
-      Added *maxlen*
+      Added *maxlen* parameter.
 
 Deque objects support the following methods:
 

Doc/library/configparser.rst

@@ -87,7 +87,7 @@ write-back, as will be the keys within each section.
    well. New applications should prefer this version if they don't need to be
    compatible with older versions of Python.
 
-   .. % XXX Need to explain what's safer/more predictable about it.
+   .. XXX Need to explain what's safer/more predictable about it.
 
 
 .. exception:: NoSectionError

Doc/library/constants.rst

@@ -15,19 +15,21 @@ A small number of constants live in the built-in namespace.  They are:
 
 .. data:: False
 
-   The false value of the :class:`bool` type.
+   The false value of the :class:`bool` type. Assignments to ``False`` 
+   are illegal and raise a :exc:`SyntaxError`.
 
 
 .. data:: True
 
-   The true value of the :class:`bool` type.
+   The true value of the :class:`bool` type. Assignments to ``True`` 
+   are illegal and raise a :exc:`SyntaxError`.
 
 
 .. data:: None
 
    The sole value of :attr:`types.NoneType`.  ``None`` is frequently used to
    represent the absence of a value, as when default arguments are not passed to a
-   function.
+   function. Assignments to ``None`` are illegal and raise a :exc:`SyntaxError`.
 
 
 .. data:: NotImplemented
@@ -42,11 +44,11 @@ A small number of constants live in the built-in namespace.  They are:
    The same as ``...``. Special value used mostly in conjunction with extended
    slicing syntax for user-defined container data types, as in ::
 
-      val = container[1:5, 7:10, ...]
+   .. XXX Someone who understands extended slicing should fill in here.
 
 
 .. data:: __debug__
 
-   A boolean value that is :data:`True` if Python was not started with the
-   ``-O`` command line option.  Its value is used indirectly by the
-   :keyword:`assert` statement, but it can also be used directly in code.
+   This constant is true if Python was not started with an :option:`-O` option.
+   Assignments to :const:`__debug__` are illegal and raise a :exc:`SyntaxError`.
+   See also the :keyword:`assert` statement.

Doc/library/copy.rst

@@ -21,8 +21,6 @@ Interface summary::
 
 For module specific errors, :exc:`copy.error` is raised.
 
-.. % 
-
 The difference between shallow and deep copying is only relevant for compound
 objects (objects that contain other objects, like lists or class instances):
 

Doc/library/ctypes.rst

@@ -69,7 +69,7 @@ the library by creating an instance of CDLL by calling the constructor::
    <CDLL 'libc.so.6', handle ... at ...>
    >>>
 
-.. % XXX Add section for Mac OS X.
+.. XXX Add section for Mac OS X.
 
 
 .. _ctypes-accessing-functions-from-loaded-dlls:
@@ -1256,10 +1256,6 @@ Enumeration types are not implemented. You can do it easily yourself, using
 
 ``long double`` is not implemented.
 
-.. % Local Variables:
-.. % compile-command: "make.bat"
-.. % End:
-
 
 .. _ctypes-ctypes-reference:
 

Doc/library/curses.rst

@@ -1167,7 +1167,7 @@ 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 should this table be alphabetized?
+.. XXX this table is far too large! should it be alphabetized?
 
 +-------------------+--------------------------------------------+
 | Key constant      | Key                                        |

Doc/library/datetime.rst

-.. % XXX what order should the types be discussed in?
-
-
 :mod:`datetime` --- Basic date and time types
 =============================================
 
@@ -10,6 +7,7 @@
 .. sectionauthor:: Tim Peters <tim@zope.com>
 .. sectionauthor:: A.M. Kuchling <amk@amk.ca>
 
+.. XXX what order should the types be discussed in?
 
 The :mod:`datetime` module supplies classes for manipulating dates and times in
 both simple and complex ways.  While date and time arithmetic is supported, the
@@ -202,7 +200,7 @@ Instance attributes (read-only):
 
 Supported operations:
 
-.. % XXX this table is too wide!
+.. XXX this table is too wide!
 
 +--------------------------------+-----------------------------------------------+
 | Operation                      | Result                                        |

Doc/library/decimal.rst

@@ -88,7 +88,7 @@ reset them before monitoring a calculation.
    * IEEE standard 854-1987, `Unofficial IEEE 854 Text
      <http://www.cs.berkeley.edu/~ejr/projects/754/private/drafts/854-1987/dir.html>`_.
 
-.. % %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+.. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
 
 
 .. _decimal-tutorial:
@@ -263,7 +263,7 @@ a single cast inside a loop.  With context set and decimals created, the bulk of
 the program manipulates the data no differently than with other Python numeric
 types.
 
-.. % %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+.. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
 
 
 .. _decimal-decimal:
@@ -274,7 +274,7 @@ Decimal objects
 
 .. class:: Decimal([value [, context]])
 
-   Constructs a new :class:`Decimal` object based from *value*.
+   Construct a new :class:`Decimal` object based from *value*.
 
    *value* can be an integer, string, tuple, or another :class:`Decimal` object. If
    no *value* is given, returns ``Decimal("0")``.  If *value* is a string, it
@@ -512,7 +512,7 @@ also have a number of specialized methods:
    correctly rounded using the :const:`ROUND_HALF_EVEN` rounding mode.
 
 
-.. method:  Decimal.logb([context])
+.. method:: Decimal.logb([context])
 
    For a nonzero number, return the adjusted exponent of its operand
    as a :class:`Decimal` instance.  If the operand is a zero then
@@ -624,7 +624,7 @@ also have a number of specialized methods:
 
 .. method:: Decimal.quantize(exp[, rounding[, context[, watchexp]]])
 
-   Returns a value equal to the first operand after rounding and
+   Return a value equal to the first operand after rounding and
    having the exponent of the second operand.
 
    >>> Decimal("1.41421356").quantize(Decimal("1.000"))
@@ -645,8 +645,8 @@ also have a number of specialized methods:
    the given ``context`` argument; if neither argument is given the
    rounding mode of the current thread's context is used.
 
-   If watchexp is set (default), then an error is returned whenever 
-   the resulting exponent is greater than Emax or less than Etiny.
+   If *watchexp* is set (default), then an error is returned whenever the
+   resulting exponent is greater than :attr:`Emax` or less than :attr:`Etiny`.
 
 .. method:: Decimal.radix()
 
@@ -657,7 +657,7 @@ also have a number of specialized methods:
 
 .. method:: Decimal.remainder_near(other[, context])
 
-   Computes the modulo as either a positive or negative value depending on which is
+   Compute the modulo as either a positive or negative value depending on which is
    closest to zero.  For instance, ``Decimal(10).remainder_near(6)`` returns
    ``Decimal("-2")`` which is closer to zero than ``Decimal("4")``.
 
@@ -720,7 +720,7 @@ also have a number of specialized methods:
 
 .. method:: Decimal.to_integral_exact([rounding[, context]])
 
-   Round the argument to the nearest integer, signaling
+   Round to the nearest integer, signaling
    :const:`Inexact` or :const:`Rounded` as appropriate if rounding
    occurs.  The rounding mode is determined by the ``rounding``
    parameter if given, else by the given ``context``.  If neither
@@ -730,14 +730,14 @@ also have a number of specialized methods:
 
 .. method:: Decimal.to_integral_value([rounding[, context]])
 
-   Rounds to the nearest integer without signaling :const:`Inexact` or
+   Round to the nearest integer without signaling :const:`Inexact` or
    :const:`Rounded`.  If given, applies *rounding*; otherwise, uses the rounding
    method in either the supplied *context* or the current context.
 
 
 .. method:: Decimal.trim()
 
-   Returns its argument with *insignificant* trailing zeros removed.
+   Return the decimal with *insignificant* trailing zeros removed.
    Here, a trailing zero is considered insignificant either if it
    follows the decimal point, or if the exponent of the argument (that
    is, the last element of the :meth:`as_tuple` representation) is
@@ -755,7 +755,7 @@ operands*.  A *logical operand* is a :class:`Decimal` instance whose
 exponent and sign are both zero, and whose digits are all either
 :const:`0` or :const:`1`.
 
-.. % %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+.. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
 
 
 .. _decimal-context:
@@ -1023,7 +1023,7 @@ those for the :class:`Decimal` class and are only briefly recounted here.
 
    Converts a number to a string using scientific notation.
 
-.. % %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+.. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
 
 
 .. _decimal-signals:
@@ -1144,7 +1144,7 @@ The following table summarizes the hierarchy of signals::
            Rounded
            Subnormal
 
-.. % %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+.. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
 
 
 .. _decimal-notes:
@@ -1241,7 +1241,7 @@ the following calculation returns a value equal to zero::
    >>> 1 / Decimal('Infinity')
    Decimal("0E-1000000026")
 
-.. % %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+.. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
 
 
 .. _decimal-threads:
@@ -1279,7 +1279,7 @@ threads calling :func:`getcontext`. For example::
    t3.start()
     . . .
 
-.. % %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+.. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
 
 
 .. _decimal-recipes:
@@ -1435,7 +1435,7 @@ to work with the :class:`Decimal` class::
        return +s
 
 
-.. % %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+.. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
 
 
 .. _decimal-faq:

Doc/library/difflib.rst

@@ -6,9 +6,9 @@
    :synopsis: Helpers for computing differences between objects.
 .. moduleauthor:: Tim Peters <tim_one@users.sourceforge.net>
 .. sectionauthor:: Tim Peters <tim_one@users.sourceforge.net>
+.. Markup by Fred L. Drake, Jr. <fdrake@acm.org>
 
 
-.. % LaTeXification by Fred L. Drake, Jr. <fdrake@acm.org>.
 
 This module provides classes and functions for comparing sequences. It
 can be used for example, for comparing files, and can produce difference
@@ -378,6 +378,12 @@ use :meth:`set_seq2` to set the commonly used sequence once and call
    then ``i+n != i'`` or ``j+n != j'``; in other words, adjacent triples always
    describe non-adjacent equal blocks.
 
+   .. XXX Explain why a dummy is used!
+
+   .. versionchanged:: 2.5
+      The guarantee that adjacent triples always describe non-adjacent blocks was
+      implemented.
+
    ::
 
       >>> s = SequenceMatcher(None, "abxcd", "abcd")

Doc/library/dis.rst

@@ -452,13 +452,6 @@ the more significant byte last.
    Unpacks TOS into *count* individual values, which are put onto the stack
    right-to-left.
 
-.. % \begin{opcodedesc}{UNPACK_LIST}{count}
-.. % This opcode is obsolete.
-.. % \end{opcodedesc}
-.. % \begin{opcodedesc}{UNPACK_ARG}{count}
-.. % This opcode is obsolete.
-.. % \end{opcodedesc}
-
 
 .. opcode:: DUP_TOPX (count)
 
@@ -486,10 +479,6 @@ the more significant byte last.
 
    Works as ``DELETE_NAME``, but deletes a global name.
 
-.. % \begin{opcodedesc}{UNPACK_VARARG}{argc}
-.. % This opcode is obsolete.
-.. % \end{opcodedesc}
-
 
 .. opcode:: LOAD_CONST (consti)
 
@@ -577,22 +566,11 @@ the more significant byte last.
    the iterator indicates it is exhausted ``TOS`` is popped, and the byte code
    counter is incremented by *delta*.
 
-.. % \begin{opcodedesc}{FOR_LOOP}{delta}
-.. % This opcode is obsolete.
-.. % \end{opcodedesc}
-.. % \begin{opcodedesc}{LOAD_LOCAL}{namei}
-.. % This opcode is obsolete.
-.. % \end{opcodedesc}
-
 
 .. opcode:: LOAD_GLOBAL (namei)
 
    Loads the global named ``co_names[namei]`` onto the stack.
 
-.. % \begin{opcodedesc}{SET_FUNC_ARGS}{argc}
-.. % This opcode is obsolete.
-.. % \end{opcodedesc}
-
 
 .. opcode:: SETUP_LOOP (delta)
 
@@ -690,7 +668,7 @@ the more significant byte last.
 
    Pushes a slice object on the stack.  *argc* must be 2 or 3.  If it is 2,
    ``slice(TOS1, TOS)`` is pushed; if it is 3, ``slice(TOS2, TOS1, TOS)`` is
-   pushed. See the ``slice()`` built-in function for more information.
+   pushed. See the :func:`slice` built-in function for more information.
 
 
 .. opcode:: EXTENDED_ARG (ext)

Doc/library/dl.rst

@@ -7,9 +7,6 @@
    :synopsis: Call C functions in shared objects.
 .. sectionauthor:: Moshe Zadka <moshez@zadka.site.co.il>
 
-
-.. % ?????????? Anyone????????????
-
 The :mod:`dl` module defines an interface to the :cfunc:`dlopen` function, which
 is the most common interface on Unix platforms for handling dynamically linked
 libraries. It allows the program to call arbitrary functions in such a library.

Doc/library/doctest.rst

@@ -691,12 +691,7 @@ even a single character doesn't match, the test fails.  This will probably
 surprise you a few times, as you learn exactly what Python does and doesn't
 guarantee about output.  For example, when printing a dict, Python doesn't
 guarantee that the key-value pairs will be printed in any particular order, so a
-test like
-
-.. % Hey! What happened to Monty Python examples?
-.. % Tim: ask Guido -- it's his example!
-
-::
+test like ::
 
    >>> foo()
    {"Hermione": "hippogryph", "Harry": "broomstick"}

Doc/library/email.rst

-.. % Copyright (C) 2001-2007 Python Software Foundation
-.. % Author: barry@python.org (Barry Warsaw)
-
-
 :mod:`email` --- An email and MIME handling package
 ===================================================
 
@@ -10,6 +6,7 @@
               including MIME documents.
 .. moduleauthor:: Barry A. Warsaw <barry@python.org>
 .. sectionauthor:: Barry A. Warsaw <barry@python.org>
+.. Copyright (C) 2001-2007 Python Software Foundation
 
 
 The :mod:`email` package is a library for managing email messages, including

Doc/library/exceptions.rst

@@ -111,16 +111,15 @@ The following exceptions are the exceptions that are actually raised.
 
 .. exception:: AttributeError
 
-   Raised when an attribute reference or assignment fails.  (When an object does
-   not support attribute references or attribute assignments at all,
-   :exc:`TypeError` is raised.)
-
-   .. % xref to attribute reference?
+   Raised when an attribute reference (see :ref:`attribute-references`) or
+   assignment fails.  (When an object does not support attribute references or
+   attribute assignments at all, :exc:`TypeError` is raised.)
 
 
 .. exception:: EOFError
 
-   Raised when attempting to read beyond the end of a file. (N.B.: the
+   Raised when one of the built-in functions (:func:`input` or :func:`raw_input`)
+   hits an end-of-file condition (EOF) without reading any data. (N.B.: the
    :meth:`file.read` and :meth:`file.readline` methods return an empty string
    when they hit EOF.)
 
@@ -162,14 +161,14 @@ The following exceptions are the exceptions that are actually raised.
    truncated to fall in the allowed range; if an index is not a plain integer,
    :exc:`TypeError` is raised.)
 
-   .. % XXXJH xref to sequences
+   .. XXX xref to sequences
 
 
 .. exception:: KeyError
 
    Raised when a mapping (dictionary) key is not found in the set of existing keys.
 
-   .. % XXXJH xref to mapping objects?
+   .. XXX xref to mapping objects?
 
 
 .. exception:: KeyboardInterrupt

Doc/library/functions.rst

@@ -28,7 +28,7 @@ available.  They are listed here in alphabetical order.
    :func:`__import__` function.
 
    For example, the statement ``import spam`` results in the following call:
-   ``__import__('spam',`` ``globals(),`` ``locals(), [], -1)``; the statement
+   ``__import__('spam', globals(), locals(), [], -1)``; the statement
    ``from spam.ham import eggs`` results in ``__import__('spam.ham', globals(),
    locals(), ['eggs'], -1)``.  Note that even though ``locals()`` and ``['eggs']``
    are passed in as arguments, the :func:`__import__` function does not set the
@@ -359,7 +359,7 @@ available.  They are listed here in alphabetical order.
    access to the standard :mod:`builtins` module and restricted environments are
    propagated.  If the *locals* dictionary is omitted it defaults to the *globals*
    dictionary.  If both dictionaries are omitted, the expression is executed in the
-   environment where :keyword:`eval` is called.  The return value is the result of
+   environment where :func:`eval` is called.  The return value is the result of
    the evaluated expression. Syntax errors are reported as exceptions.  Example::
 
       >>> x = 1
@@ -632,7 +632,7 @@ available.  They are listed here in alphabetical order.
       The contents of this dictionary should not be modified; changes may not affect
       the values of local variables used by the interpreter.
 
-   Free variables are returned by *locals* when it is called in a function block.
+   Free variables are returned by :func:`locals` when it is called in a function block.
    Modifications of free variables may not affect the values used by the
    interpreter.  Free variables are not returned in class blocks.
 

Doc/library/gensuitemodule.rst

@@ -6,9 +6,7 @@
    :platform: Mac
    :synopsis: Create a stub package from an OSA dictionary
 .. sectionauthor:: Jack Jansen <Jack.Jansen@cwi.nl>
-
-
-.. % \moduleauthor{Jack Jansen?}{email}
+.. moduleauthor:: Jack Jansen
 
 The :mod:`gensuitemodule` module creates a Python package implementing stub code
 for the AppleScript suites that are implemented by a specific application,

Doc/library/getopt.rst

@@ -9,7 +9,7 @@
 
 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:

Doc/library/getpass.rst

-
 :mod:`getpass` --- Portable password input
 ==========================================
 
@@ -6,9 +5,7 @@
    :synopsis: Portable reading of passwords and retrieval of the userid.
 .. moduleauthor:: Piers Lauder <piers@cs.su.oz.au>
 .. sectionauthor:: Fred L. Drake, Jr. <fdrake@acm.org>
-
-
-.. % Windows (& Mac?) support by Guido van Rossum.
+.. Windows (& Mac?) support by Guido van Rossum.
 
 The :mod:`getpass` module provides two functions:
 

Doc/library/heapq.rst

-
 :mod:`heapq` --- Heap queue algorithm
 =====================================
 
@@ -8,9 +7,6 @@
 .. sectionauthor:: Guido van Rossum <guido@python.org>
 .. sectionauthor:: François Pinard
 
-
-.. % Theoretical explanation:
-
 This module provides an implementation of the heap queue algorithm, also known
 as the priority queue algorithm.
 

Doc/library/idle.rst

 .. _idle:
 
-Idle
+IDLE
 ====
 
 .. moduleauthor:: Guido van Rossum <guido@Python.org>
 
-
-.. % \declaremodule{standard}{idle}
-.. % \modulesynopsis{A Python Integrated Development Environment}
-
 .. index::
-   single: Idle
+   single: IDLE
    single: Python Editor
    single: Integrated Development Environment
 
-Idle is the Python IDE built with the :mod:`Tkinter` GUI toolkit.
+IDLE is the Python IDE built with the :mod:`Tkinter` GUI toolkit.
 
 IDLE has the following features:
 

Doc/library/imaplib.rst

-
 :mod:`imaplib` --- IMAP4 protocol client
 ========================================
 
@@ -6,6 +5,10 @@
    :synopsis: IMAP4 protocol client (requires sockets).
 .. moduleauthor:: Piers Lauder <piers@communitysolutions.com.au>
 .. sectionauthor:: Piers Lauder <piers@communitysolutions.com.au>
+.. revised by ESR, January 2000
+.. changes for IMAP4_SSL by Tino Lange <Tino.Lange@isg.de>, March 2002
+.. changes for IMAP4_stream by Piers Lauder <piers@communitysolutions.com.au>,
+   November 2002
 
 
 .. index::
@@ -13,14 +16,6 @@
    pair: IMAP4_SSL; protocol
    pair: IMAP4_stream; protocol
 
-.. % Based on HTML documentation by Piers Lauder
-.. % <piers@communitysolutions.com.au>;
-.. % converted by Fred L. Drake, Jr. <fdrake@acm.org>.
-.. % Revised by ESR, January 2000.
-.. % Changes for IMAP4_SSL by Tino Lange <Tino.Lange@isg.de>, March 2002
-.. % Changes for IMAP4_stream by Piers Lauder
-.. % <piers@communitysolutions.com.au>, November 2002
-
 This module defines three classes, :class:`IMAP4`, :class:`IMAP4_SSL` and
 :class:`IMAP4_stream`, which encapsulate a connection to an IMAP4 server and
 implement a large subset of the IMAP4rev1 client protocol as defined in

Doc/library/itertools.rst

@@ -157,7 +157,7 @@ loops that truncate the stream.
                   key = lambda x: x
               self.keyfunc = key
               self.it = iter(iterable)
-              self.tgtkey = self.currkey = self.currvalue = []
+              self.tgtkey = self.currkey = self.currvalue = object()
           def __iter__(self):
               return self
           def __next__(self):
@@ -350,14 +350,13 @@ loops that truncate the stream.
    is equivalent to::
 
       def tee(iterable):
-          def gen(next, data={}, cnt=[0]):
+          def gen(next, data={}):
               for i in count():
-                  if i == cnt[0]:
-                      item = data[i] = next()
-                      cnt[0] += 1
+                  if i in data:
+                      yield data.pop(i)
                   else:
-                      item = data.pop(i)
-                  yield item
+                      data[i] = next()
+                      yield data[i]
           it = iter(iterable)
           return (gen(it.__next__), gen(it.__next__))
 

Doc/library/logging.rst

@@ -2019,8 +2019,6 @@ Configuration
 Configuration functions
 ^^^^^^^^^^^^^^^^^^^^^^^
 
-.. % 
-
 The following functions configure the logging module. They are located in the
 :mod:`logging.config` module.  Their use is optional --- you can configure the
 logging module using these functions or by making calls to the main API (defined
@@ -2204,13 +2202,12 @@ Sections which specify formatter configuration are typified by the following. ::
    class=logging.Formatter
 
 The ``format`` entry is the overall format string, and the ``datefmt`` entry is
-the :func:`strftime`\ -compatible date/time format string. If empty, the package
-substitutes ISO8601 format date/times, which is almost equivalent to specifying
-the date format string "The ISO8601 format also specifies milliseconds, which
-are appended to the result of using the above format string, with a comma
-separator. An example time in ISO8601 format is ``2003-01-23 00:29:50,411``.
-
-.. % Y-%m-%d %H:%M:%S".
+the :func:`strftime`\ -compatible date/time format string.  If empty, the
+package substitutes ISO8601 format date/times, which is almost equivalent to
+specifying the date format string ``"%Y-%m-%d %H:%M:%S"``.  The ISO8601 format
+also specifies milliseconds, which are appended to the result of using the above
+format string, with a comma separator.  An example time in ISO8601 format is
+``2003-01-23 00:29:50,411``.
 
 The ``class`` entry is optional.  It indicates the name of the formatter's class
 (as a dotted module and class name.)  This option is useful for instantiating a

Doc/library/mhlib.rst

-
 :mod:`mhlib` --- Access to MH mailboxes
 =======================================
 
 .. module:: mhlib
    :synopsis: Manipulate MH mailboxes from Python.
-
-
-.. % LaTeX'ized from the comments in the module by Skip Montanaro
-.. % <skip@pobox.com>.
+.. sectionauthor:: Skip Montanaro <skip@pobox.com>
 
 The :mod:`mhlib` module provides a Python interface to MH folders and their
 contents.

Doc/library/nntplib.rst

@@ -309,8 +309,6 @@ 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)?
-
    RFC2980 says "It is suggested that this extension be deprecated".  Use
    :meth:`descriptions` or :meth:`description` instead.
 

Doc/library/optparse.rst

-.. % THIS FILE IS AUTO-GENERATED!  DO NOT EDIT!
-.. % (Your changes will be lost the next time it is generated.)
-
-
 :mod:`optparse` --- More powerful command line option parser
 ============================================================
 
@@ -18,9 +14,6 @@ populate it with options, and parse the command line. ``optparse`` allows users
 to specify options in the conventional GNU/POSIX syntax, and additionally
 generates usage and help messages for you.
 
-.. % An intro blurb used only when generating LaTeX docs for the Python
-.. % manual (based on README.txt).
-
 Here's an example of using ``optparse`` in a simple script::
 
    from optparse import OptionParser
@@ -70,8 +63,6 @@ and ``optparse`` will print out a brief summary of your script's options::
 where the value of *yourscript* is determined at runtime (normally from
 ``sys.argv[0]``).
 
-.. % $Id: intro.txt 413 2004-09-28 00:59:13Z greg $
-
 
 .. _optparse-background:
 
@@ -233,8 +224,6 @@ you implement, the more flexible your program is, and the more complicated its
 implementation becomes.  Too much flexibility has drawbacks as well, of course;
 too many options can overwhelm users and make your code much harder to maintain.
 
-.. % $Id: tao.txt 413 2004-09-28 00:59:13Z greg $
-
 
 .. _optparse-tutorial:
 
@@ -652,8 +641,6 @@ Here's what :mod:`optparse`\ -based scripts usually look like::
    if __name__ == "__main__":
        main()
 
-.. % $Id: tutorial.txt 515 2006-06-10 15:37:45Z gward $
-
 
 .. _optparse-reference-guide:
 
@@ -1329,8 +1316,6 @@ OptionParser supports several other public methods:
      parser.add_option("--novice", action="store_const",
                        dest="mode", const="novice")
 
-.. % $Id: reference.txt 519 2006-06-11 14:39:11Z gward $
-
 
 .. _optparse-option-callbacks:
 
@@ -1626,8 +1611,6 @@ in the arguments following ``"-c"`` will be interpreted as further options
 (probably causing an error), rather than as arguments to ``"-c"``.  Fixing this
 is left as an exercise for the reader.
 
-.. % $Id: callbacks.txt 415 2004-09-30 02:26:17Z greg $
-
 
 .. _optparse-extending-optparse:
 
@@ -1818,6 +1801,3 @@ Features of note:
   about setting a default value for the option destinations in question; they can
   just leave the default as None and :meth:`ensure_value` will take care of
   getting it right when it's needed.
-
-.. % $Id: extending.txt 517 2006-06-10 16:18:11Z gward $
-

Doc/library/os.rst

@@ -291,9 +291,8 @@ process and user.
 
    Set the current process' user id. Availability: Unix.
 
-.. % placed in this section since it relates to errno.... a little weak
-
 
+.. placed in this section since it relates to errno.... a little weak
 .. function:: strerror(code)
 
    Return the error message corresponding to the error code in *code*.

Doc/library/ossaudiodev.rst

@@ -11,33 +11,33 @@ This module allows you to access the OSS (Open Sound System) audio interface.
 OSS is available for a wide range of open-source and commercial Unices, and is
 the standard audio interface for Linux and recent versions of FreeBSD.
 
-.. % Things will get more complicated for future Linux versions, since
-.. % ALSA is in the standard kernel as of 2.5.x.  Presumably if you
-.. % use ALSA, you'll have to make sure its OSS compatibility layer
-.. % is active to use ossaudiodev, but you're gonna need it for the vast
-.. % majority of Linux audio apps anyways.
-.. % 
-.. % Sounds like things are also complicated for other BSDs.  In response
-.. % to my python-dev query, Thomas Wouters said:
-.. % 
-.. % > Likewise, googling shows OpenBSD also uses OSS/Free -- the commercial
-.. % > OSS installation manual tells you to remove references to OSS/Free from the
-.. % > kernel :)
-.. % 
-.. % but Aleksander Piotrowsk actually has an OpenBSD box, and he quotes
-.. % from its <soundcard.h>:
-.. % >  * WARNING!  WARNING!
-.. % >  * This is an OSS (Linux) audio emulator.
-.. % >  * Use the Native NetBSD API for developing new code, and this
-.. % >  * only for compiling Linux programs.
-.. % 
-.. % There's also an ossaudio manpage on OpenBSD that explains things
-.. % further.  Presumably NetBSD and OpenBSD have a different standard
-.. % audio interface.  That's the great thing about standards, there are so
-.. % many to choose from ... ;-)
-.. % 
-.. % This probably all warrants a footnote or two, but I don't understand
-.. % things well enough right now to write it!   --GPW
+.. Things will get more complicated for future Linux versions, since
+   ALSA is in the standard kernel as of 2.5.x.  Presumably if you
+   use ALSA, you'll have to make sure its OSS compatibility layer
+   is active to use ossaudiodev, but you're gonna need it for the vast
+   majority of Linux audio apps anyways.
+   
+   Sounds like things are also complicated for other BSDs.  In response
+   to my python-dev query, Thomas Wouters said:
+   
+   > Likewise, googling shows OpenBSD also uses OSS/Free -- the commercial
+   > OSS installation manual tells you to remove references to OSS/Free from the
+   > kernel :)
+   
+   but Aleksander Piotrowsk actually has an OpenBSD box, and he quotes
+   from its <soundcard.h>:
+   >  * WARNING!  WARNING!
+   >  * This is an OSS (Linux) audio emulator.
+   >  * Use the Native NetBSD API for developing new code, and this
+   >  * only for compiling Linux programs.
+   
+   There's also an ossaudio manpage on OpenBSD that explains things
+   further.  Presumably NetBSD and OpenBSD have a different standard
+   audio interface.  That's the great thing about standards, there are so
+   many to choose from ... ;-)
+   
+   This probably all warrants a footnote or two, but I don't understand
+   things well enough right now to write it!   --GPW
 
 
 .. seealso::
@@ -87,6 +87,10 @@ 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])
 

Doc/library/othergui.rst

@@ -5,7 +5,6 @@ Other Graphical User Interface Packages
 
 There are an number of extension widget sets to :mod:`Tkinter`.
 
-
 .. seealso::
 
    `Python megawidgets <http://pmw.sourceforge.net/>`_
@@ -29,12 +28,10 @@ There are an number of extension widget sets to :mod:`Tkinter`.
       since they can operate directly on Python data structures, without having to
       transfer data through the Tk/Tcl layer.
 
-      .. % 
 
 The major cross-platform (Windows, Mac OS X, Unix-like) GUI toolkits that are
 also available for Python:
 
-
 .. seealso::
 
    `PyGTK <http://www.pygtk.org/>`_

Doc/library/parser.rst

@@ -8,13 +8,12 @@
 .. sectionauthor:: Fred L. Drake, Jr. <fdrake@acm.org>
 
 
-.. % Copyright 1995 Virginia Polytechnic Institute and State University
-.. % and Fred L. Drake, Jr.  This copyright notice must be distributed on
-.. % all copies, but this document otherwise may be distributed as part
-.. % of the Python distribution.  No fee may be charged for this document
-.. % in any representation, either on paper or electronically.  This
-.. % restriction does not affect other elements in a distributed package
-.. % in any way.
+.. Copyright 1995 Virginia Polytechnic Institute and State University and Fred
+   L. Drake, Jr.  This copyright notice must be distributed on all copies, but
+   this document otherwise may be distributed as part of the Python
+   distribution.  No fee may be charged for this document in any representation,
+   either on paper or electronically.  This restriction does not affect other
+   elements in a distributed package in any way.
 
 .. index:: single: parsing; Python source code
 

Doc/library/pickle.rst

-
 :mod:`pickle` --- Python object serialization
 =============================================
 
@@ -12,10 +11,8 @@
 
 .. module:: pickle
    :synopsis: Convert Python objects to streams of bytes and back.
-
-
-.. % Substantial improvements by Jim Kerr <jbkerr@sr.hp.com>.
-.. % Rewritten by Barry Warsaw <barry@zope.com>
+.. sectionauthor:: Jim Kerr <jbkerr@sr.hp.com>.
+.. sectionauthor:: Barry Warsaw <barry@zope.com>
 
 The :mod:`pickle` module implements a fundamental, but powerful algorithm for
 serializing and de-serializing a Python object structure.  "Pickling" is the
@@ -607,10 +604,10 @@ object references without actually instantiating all the objects in a pickle.
 [#]_  Setting :attr:`persistent_load` to a list is usually used in conjunction
 with the :meth:`noload` method on the Unpickler.
 
-.. % BAW: Both pickle and cPickle support something called
-.. % inst_persistent_id() which appears to give unknown types a second
-.. % shot at producing a persistent id.  Since Jim Fulton can't remember
-.. % why it was added or what it's for, I'm leaving it undocumented.
+.. BAW: Both pickle and cPickle support something called inst_persistent_id()
+   which appears to give unknown types a second shot at producing a persistent
+   id.  Since Jim Fulton can't remember why it was added or what it's for, I'm
+   leaving it undocumented.
 
 
 .. _pickle-sub:

Doc/library/platform.rst

@@ -194,16 +194,12 @@ Windows Platform
 Win95/98 specific
 ^^^^^^^^^^^^^^^^^
 
-
 .. function:: popen(cmd, mode='r', bufsize=None)
 
    Portable :func:`popen` interface.  Find a working popen implementation
    preferring :func:`win32pipe.popen`.  On Windows NT, :func:`win32pipe.popen`
    should work; on Windows 9x it hangs due to bugs in the MS C library.
 
-   .. % This KnowledgeBase article appears to be missing...
-   .. % See also \ulink{MS KnowledgeBase article Q150956}{}.
-
 
 Mac OS Platform
 ---------------
@@ -231,7 +227,7 @@ Unix Platforms
    Tries to determine the name of the OS distribution name Returns a tuple
    ``(distname, version, id)`` which defaults to the args given as parameters.
 
-.. % Document linux_distribution()?
+.. XXX Document linux_distribution()?
 
 
 .. function:: libc_ver(executable=sys.executable, lib='', version='', chunksize=2048)

Doc/library/poplib.rst

@@ -4,16 +4,11 @@
 
 .. module:: poplib
    :synopsis: POP3 protocol client (requires sockets).
-
+.. sectionauthor:: Andrew T. Csillag
+.. revised by ESR, January 2000
 
 .. index:: pair: POP3; protocol
 
-.. % By Andrew T. Csillag
-.. % Even though I put it into LaTeX, I cannot really claim that I wrote
-.. % it since I just stole most of it from the poplib.py source code and
-.. % the imaplib ``chapter''.
-.. % Revised by ESR, January 2000
-
 This module defines a class, :class:`POP3`, which encapsulates a connection to a
 POP3 server and implements the protocol as defined in :rfc:`1725`.  The
 :class:`POP3` class supports both the minimal and optional command sets.

Doc/library/pprint.rst

@@ -24,7 +24,7 @@ Dictionaries are sorted by key before the display is computed.
 
 The :mod:`pprint` module defines one class:
 
-.. % First the implementation class:
+.. First the implementation class:
 
 
 .. class:: PrettyPrinter(...)
@@ -65,8 +65,7 @@ The :mod:`pprint` module defines one class:
 
 The :class:`PrettyPrinter` class supports several derivative functions:
 
-.. % Now the derivative functions:
-
+.. Now the derivative functions:
 
 .. function:: pformat(object[, indent[, width[, depth]]])
 
@@ -123,9 +122,6 @@ One more support function is also defined:
    recursive reference will be represented as ``<Recursion on typename with
    id=number>``.  The representation is not otherwise formatted.
 
-.. % This example is outside the {funcdesc} to keep it from running over
-.. % the right margin.
-
 ::
 
    >>> pprint.saferepr(stuff)

Doc/library/profile.rst

@@ -72,47 +72,47 @@ is not so far as well-tested and might not be available on all systems.
 :mod:`cProfile` is really a compatibility layer on top of the internal
 :mod:`_lsprof` module.
 
-.. % \section{How Is This Profiler Different From The Old Profiler?}
-.. % \nodename{Profiler Changes}
-.. % 
-.. % (This section is of historical importance only; the old profiler
-.. % discussed here was last seen in Python 1.1.)
-.. % 
-.. % The big changes from old profiling module are that you get more
-.. % information, and you pay less CPU time.  It's not a trade-off, it's a
-.. % trade-up.
-.. % 
-.. % To be specific:
-.. % 
-.. % \begin{description}
-.. % 
-.. % \item[Bugs removed:]
-.. % Local stack frame is no longer molested, execution time is now charged
-.. % to correct functions.
-.. % 
-.. % \item[Accuracy increased:]
-.. % Profiler execution time is no longer charged to user's code,
-.. % calibration for platform is supported, file reads are not done \emph{by}
-.. % profiler \emph{during} profiling (and charged to user's code!).
-.. % 
-.. % \item[Speed increased:]
-.. % Overhead CPU cost was reduced by more than a factor of two (perhaps a
-.. % factor of five), lightweight profiler module is all that must be
-.. % loaded, and the report generating module (\module{pstats}) is not needed
-.. % during profiling.
-.. % 
-.. % \item[Recursive functions support:]
-.. % Cumulative times in recursive functions are correctly calculated;
-.. % recursive entries are counted.
-.. % 
-.. % \item[Large growth in report generating UI:]
-.. % Distinct profiles runs can be added together forming a comprehensive
-.. % report; functions that import statistics take arbitrary lists of
-.. % files; sorting criteria is now based on keywords (instead of 4 integer
-.. % options); reports shows what functions were profiled as well as what
-.. % profile file was referenced; output format has been improved.
-.. % 
-.. % \end{description}
+.. \section{How Is This Profiler Different From The Old Profiler?}
+   \nodename{Profiler Changes}
+   
+   (This section is of historical importance only; the old profiler
+   discussed here was last seen in Python 1.1.)
+   
+   The big changes from old profiling module are that you get more
+   information, and you pay less CPU time.  It's not a trade-off, it's a
+   trade-up.
+   
+   To be specific:
+   
+   \begin{description}
+   
+   \item[Bugs removed:]
+   Local stack frame is no longer molested, execution time is now charged
+   to correct functions.
+   
+   \item[Accuracy increased:]
+   Profiler execution time is no longer charged to user's code,
+   calibration for platform is supported, file reads are not done \emph{by}
+   profiler \emph{during} profiling (and charged to user's code!).
+   
+   \item[Speed increased:]
+   Overhead CPU cost was reduced by more than a factor of two (perhaps a
+   factor of five), lightweight profiler module is all that must be
+   loaded, and the report generating module (\module{pstats}) is not needed
+   during profiling.
+   
+   \item[Recursive functions support:]
+   Cumulative times in recursive functions are correctly calculated;
+   recursive entries are counted.
+   
+   \item[Large growth in report generating UI:]
+   Distinct profiles runs can be added together forming a comprehensive
+   report; functions that import statistics take arbitrary lists of
+   files; sorting criteria is now based on keywords (instead of 4 integer
+   options); reports shows what functions were profiled as well as what
+   profile file was referenced; output format has been improved.
+   
+   \end{description}
 
 
 .. _profile-instant:
@@ -172,7 +172,7 @@ second method sorted all the entries according to the standard module/line/name
 string that is printed. The third method printed out all the statistics.  You
 might try the following sort calls:
 
-.. % (this is to comply with the semantics of the old profiler).
+.. (this is to comply with the semantics of the old profiler).
 
 ::
 
@@ -363,6 +363,8 @@ Analysis of the profiler data is done using the :class:`Stats` class.
    a single report.  If additional files need to be combined with data in an
    existing :class:`Stats` object, the :meth:`add` method can be used.
 
+   .. (such as the old system profiler).
+
 
 .. _profile-stats:
 
@@ -457,7 +459,7 @@ The :class:`Stats` Class
    (numeric) is used, only one sort key (the numeric key) will be used, and
    additional arguments will be silently ignored.
 
-   .. % For compatibility with the old profiler,
+   .. For compatibility with the old profiler,
 
 
 .. method:: Stats.reverse_order()
@@ -466,8 +468,7 @@ The :class:`Stats` Class
    within the object.  Note that by default ascending vs descending order is
    properly selected based on the sort key of choice.
 
-   .. % This method is provided primarily for
-   .. % compatibility with the old profiler.
+   .. This method is provided primarily for compatibility with the old profiler.
 
 
 .. method:: Stats.print_stats([restriction, ...])

Doc/library/py_compile.rst

@@ -3,11 +3,8 @@
 
 .. module:: py_compile
    :synopsis: Generate byte-code files from Python source files.
-
-.. % Documentation based on module docstrings, by Fred L. Drake, Jr.
-.. % <fdrake@acm.org>
-
-
+.. sectionauthor:: Fred L. Drake, Jr. <fdrake@acm.org>
+.. documentation based on module docstrings
 
 .. index:: pair: file; byte-code
 

Doc/library/pyclbr.rst

@@ -24,7 +24,7 @@ in Python, including many standard and optional extension modules.
    be a sequence, and is used to augment the value of ``sys.path``, which is
    used to locate module source code.
 
-   .. % The 'inpackage' parameter appears to be for internal use only....
+   .. The 'inpackage' parameter appears to be for internal use only....
 
 
 .. function:: readmodule_ex(module[, path])
@@ -35,7 +35,7 @@ in Python, including many standard and optional extension modules.
    the key ``'__path__'`` in the returned dictionary has as its value a list which
    contains the package search path.
 
-   .. % The 'inpackage' parameter appears to be for internal use only....
+   .. The 'inpackage' parameter appears to be for internal use only....
 
 
 .. _pyclbr-class-objects:

Doc/library/pyexpat.rst

@@ -7,14 +7,13 @@
 .. moduleauthor:: Paul Prescod <paul@prescod.net>
 
 
-.. % Markup notes:
-.. % 
-.. % Many of the attributes of the XMLParser objects are callbacks.
-.. % Since signature information must be presented, these are described
-.. % using the methoddesc environment.  Since they are attributes which
-.. % are set by client code, in-text references to these attributes
-.. % should be marked using the \member macro and should not include the
-.. % parentheses used when marking functions and methods.
+.. Markup notes:
+
+   Many of the attributes of the XMLParser objects are callbacks.  Since
+   signature information must be presented, these are described using the method
+   directive.  Since they are attributes which are set by client code, in-text
+   references to these attributes should be marked using the :member: role.
+
 
 .. index:: single: Expat
 

Doc/library/re.rst

@@ -84,8 +84,6 @@ the null byte using the ``\number`` notation, e.g., ``'\x00'``.
 
 The special characters are:
 
-.. % 
-
 ``'.'``
    (Dot.)  In the default mode, this matches any character except a newline.  If
    the :const:`DOTALL` flag has been specified, this matches any character
@@ -297,8 +295,6 @@ The special sequences consist of ``'\'`` and a character from the list below.
 If the ordinary character is not on the list, then the resulting RE will match
 the second character.  For example, ``\$`` matches the character ``'$'``.
 
-.. % 
-
 ``\number``
    Matches the contents of the group of the same number.  Groups are numbered
    starting from 1.  For example, ``(.+) \1`` matches ``'the the'`` or ``'55 55'``,
@@ -384,9 +380,6 @@ there are three octal digits, it is considered an octal escape. Otherwise, it is
 a group reference.  As for string literals, octal escapes are always at most
 three digits in length.
 
-.. % Note the lack of a period in the section title; it causes problems
-.. % with readers of the GNU info version.  See http://www.python.org/sf/581414.
-
 
 .. _matching-searching:
 
@@ -406,15 +399,11 @@ beginning with ``'^'``: ``'^'`` matches only at the start of the string, or in
 :const:`MULTILINE` mode also immediately following a newline.  The "match"
 operation succeeds only if the pattern matches at the start of the string
 regardless of mode, or at the starting position given by the optional *pos*
-argument regardless of whether a newline precedes it.
-
-.. % Examples from Tim Peters:
-
-::
+argument regardless of whether a newline precedes it.  ::
 
    >>> re.match("c", "abcdef") # No match
    >>> re.search("c", "abcdef")
-  <_sre.SRE_Match object at 0x827e9c0> # Match
+   <_sre.SRE_Match object at 0x827e9c0> # Match
 
 
 .. _contents-of-module-re:
@@ -450,10 +439,9 @@ form.
    but the version using :func:`compile` is more efficient when the expression
    will be used several times in a single program.
 
-   .. % (The compiled version of the last pattern passed to
-   .. % \function{re.match()} or \function{re.search()} is cached, so
-   .. % programs that use only a single regular expression at a time needn't
-   .. % worry about compiling regular expressions.)
+   .. (The compiled version of the last pattern passed to :func:`re.match` or
+      :func:`re.search` is cached, so programs that use only a single regular
+      expression at a time needn't worry about compiling regular expressions.)
 
 
 .. data:: I

Doc/library/sched.rst

-
 :mod:`sched` --- Event scheduler
 ================================
 
@@ -6,9 +5,6 @@
    :synopsis: General purpose event scheduler.
 .. sectionauthor:: Moshe Zadka <moshez@zadka.site.co.il>
 
-
-.. % LaTeXed and enhanced from comments in file
-
 .. index:: single: event scheduling
 
 The :mod:`sched` module defines a class which implements a general purpose event

Doc/library/select.rst

@@ -58,8 +58,6 @@ The module defines the following:
    class yourself, as long as it has an appropriate :meth:`fileno` method (that
    really returns a file descriptor, not just a random integer).
 
-   .. % 
-
    .. note::
 
       .. index:: single: WinSock

Doc/library/shutil.rst

@@ -5,9 +5,7 @@
 .. module:: shutil
    :synopsis: High-level file operations, including copying.
 .. sectionauthor:: Fred L. Drake, Jr. <fdrake@acm.org>
-
-
-.. % partly based on the docstrings
+.. partly based on the docstrings
 
 .. index::
    single: file; copying

Doc/library/sndhdr.rst

@@ -5,9 +5,7 @@
 .. module:: sndhdr
    :synopsis: Determine type of a sound file.
 .. sectionauthor:: Fred L. Drake, Jr. <fdrake@acm.org>
-
-
-.. % Based on comments in the module source file.
+.. Based on comments in the module source file.
 
 .. index::
    single: A-LAW

Doc/library/socket.rst

@@ -542,7 +542,7 @@ correspond to Unix system calls applicable to sockets.
    file object and socket object may be closed or garbage-collected independently.
    The socket must be in blocking mode (it can not have a timeout). The optional
    *mode* and *bufsize* arguments are interpreted the same way as by the built-in
-   :func:`file` function; see :ref:`built-in-funcs` for more information.
+   :func:`file` function.
 
 
 .. method:: socket.recv(bufsize[, flags])

Doc/library/socketserver.rst

@@ -115,9 +115,8 @@ next (or whether to handle a new incoming request).  This is particularly
 important for stream services where each client can potentially be connected for
 a long time (if threads or subprocesses cannot be used).
 
-.. % XXX should data and methods be intermingled, or separate?
-.. % how should the distinction between class and instance variables be
-.. % drawn?
+.. XXX should data and methods be intermingled, or separate?
+   how should the distinction between class and instance variables be drawn?
 
 
 Server Objects
@@ -171,8 +170,7 @@ Server Objects
 
 The server classes support the following class variables:
 
-.. % XXX should class variables be covered before instance variables, or
-.. % vice versa?
+.. XXX should class variables be covered before instance variables, or vice versa?
 
 
 .. data:: allow_reuse_address
@@ -199,8 +197,8 @@ There are various server methods that can be overridden by subclasses of base
 server classes like :class:`TCPServer`; these methods aren't useful to external
 users of the server object.
 
-.. % should the default implementations of these be documented, or should
-.. % it be assumed that the user will look at SocketServer.py?
+.. XXX should the default implementations of these be documented, or should
+   it be assumed that the user will look at SocketServer.py?
 
 
 .. function:: finish_request()
@@ -230,9 +228,9 @@ users of the server object.
    or thread to handle the request; the :class:`ForkingMixIn` and
    :class:`ThreadingMixIn` classes do this.
 
-.. % Is there any point in documenting the following two functions?
-.. % What would the purpose of overriding them be: initializing server
-.. % instance variables, adding new network families?
+.. Is there any point in documenting the following two functions?
+   What would the purpose of overriding them be: initializing server
+   instance variables, adding new network families?
 
 
 .. function:: server_activate()

Doc/library/sqlite3.rst

@@ -349,7 +349,7 @@ A :class:`Connection` instance has the following attributes and methods:
    memory overhead. It will probably be better than your own custom
    dictionary-based approach or even a db_row based solution.
 
-   .. % XXX what's a db_row-based solution?
+   .. XXX what's a db_row-based solution?
 
 
 .. attribute:: Connection.text_factory

Doc/library/statvfs.rst

-
 :mod:`statvfs` --- Constants used with :func:`os.statvfs`
 =========================================================
 
@@ -7,8 +6,6 @@
 .. sectionauthor:: Moshe Zadka <moshez@zadka.site.co.il>
 
 
-.. % LaTeX'ed from comments in module
-
 The :mod:`statvfs` module defines constants so interpreting the result if
 :func:`os.statvfs`, which returns a tuple, can be made without remembering
 "magic numbers."  Each of the constants defined in this module is the *index* of

Doc/library/stdtypes.rst

@@ -161,6 +161,24 @@ This table summarizes the comparison operations:
 | ``is not`` | negated object identity |       |
 +------------+-------------------------+-------+
 
+.. index::
+   pair: operator; comparison
+   operator: ==
+   operator: <
+   operator: <=
+   operator: >
+   operator: >=
+   operator: !=
+   operator: is
+   operator: is not
+
+Notes:
+
+(1)
+    ``!=`` can also be written ``<>``, but this is an obsolete usage
+    kept for backwards compatibility only. New code should always use
+    ``!=``.
+
 .. index::
    pair: object; numeric
    pair: objects; comparing
@@ -335,8 +353,8 @@ Notes:
    
    .. versionadded:: 2.6
 
-   
-.. % XXXJH exceptions: overflow (when? what operations?) zerodivision
+
+.. XXXJH exceptions: overflow (when? what operations?) zerodivision
 
 
 .. _bitstring-ops:
@@ -1154,6 +1172,8 @@ 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.
@@ -1845,8 +1865,7 @@ File Objects
 .. 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
+created with the built-in :func:`open` function.  File
 objects are also returned by some other built-in functions and methods,
 such as :func:`os.popen` and :func:`os.fdopen` and the :meth:`makefile`
 method of socket objects. Temporary files can be created using the
@@ -1870,7 +1889,7 @@ Files have the following methods:
 
    As of Python 2.5, you can avoid having to call this method explicitly if you use
    the :keyword:`with` statement.  For example, the following code will
-   automatically close ``f`` when the :keyword:`with` block is exited::
+   automatically close *f* when the :keyword:`with` block is exited::
 
       from __future__ import with_statement
 
@@ -1998,6 +2017,9 @@ Files have the following methods:
 
    Note that not all file objects are seekable.
 
+   .. versionchanged:: 2.6
+      Passing float values as offset has been deprecated.
+
 
 .. method:: file.tell()
 
@@ -2407,9 +2429,6 @@ types, where they are relevant.  Some of these are not reported by the
    strings of meaningless digits without hampering correct use and without having
    to know the exact precision of floating point values on a particular machine.
 
-.. [#] :func:`file` is new in Python 2.2.  The older built-in :func:`open` is an alias
-   for :func:`file`.
-
 .. [#] The advantage of leaving the newline on is that returning an empty string is
    then an unambiguous EOF indication.  It is also possible (in cases where it
    might matter, for example, if you want to make an exact copy of a file while

Doc/library/struct.rst

@@ -175,7 +175,7 @@ For example, Motorola and Sun processors are big-endian; Intel and DEC
 processors are little-endian.
 
 Native size and alignment are determined using the C compiler's
-:keyword:`sizeof` expression.  This is always combined with native byte order.
+``sizeof`` expression.  This is always combined with native byte order.
 
 Standard size and alignment are as follows: no alignment is required for any
 type (so you have to use pad bytes); :ctype:`short` is 2 bytes; :ctype:`int` and

Doc/library/sys.rst

@@ -458,9 +458,8 @@ always available.
    implementation and, where needed, by :mod:`sitecustomize`.  Once used by the
    :mod:`site` module, it is removed from the :mod:`sys` module's namespace.
 
-   .. % Note that \refmodule{site} is not imported if
-   .. % the \programopt{-S} option is passed to the interpreter, in which
-   .. % case this function will remain available.
+   .. Note that :mod:`site` is not imported if the :option:`-S` option is passed
+      to the interpreter, in which case this function will remain available.
 
 
 .. function:: setdlopenflags(n)

Doc/library/tabnanny.rst

@@ -8,9 +8,7 @@
 .. moduleauthor:: Tim Peters <tim_one@users.sourceforge.net>
 .. sectionauthor:: Peter Funk <pf@artcom-gmbh.de>
 
-
-.. % rudimentary documentation based on module comments, by Peter Funk
-.. % <pf@artcom-gmbh.de>
+.. rudimentary documentation based on module comments
 
 For the time being this module is intended to be called as a script. However it
 is possible to import it into an IDE and use the function :func:`check`
@@ -55,14 +53,11 @@ described below.
    This function is used by :func:`check` as a callback parameter to the function
    :func:`tokenize.tokenize`.
 
-.. % XXX FIXME: Document \function{errprint},
-.. % \function{format_witnesses} \class{Whitespace}
-.. % check_equal, indents
-.. % \function{reset_globals}
+.. XXX document errprint, format_witnesses, Whitespace, check_equal, indents,
+   reset_globals
 
 
 .. seealso::
 
    Module :mod:`tokenize`
       Lexical scanner for Python source code.
-

Doc/library/tarfile.rst

@@ -205,10 +205,6 @@ details.
    `GNU tar manual, Basic Tar Format <http://www.gnu.org/software/tar/manual/html_node/tar_134.html#SEC134>`_
       Documentation for tar archive files, including GNU tar extensions.
 
-.. % -----------------
-.. % TarFile Objects
-.. % -----------------
-
 
 .. _tarfile-objects:
 
@@ -421,10 +417,6 @@ object, see :ref:`tarinfo-objects` for details.
    A dictionary containing key-value pairs of pax global headers.
 
 
-.. % -----------------
-.. % TarInfo Objects
-.. % -----------------
-
 
 .. _tarinfo-objects:
 
@@ -574,10 +566,6 @@ A :class:`TarInfo` object also provides some convenient query methods:
 
    Return :const:`True` if it is one of character device, block device or FIFO.
 
-.. % ------------------------
-.. % Examples
-.. % ------------------------
-
 
 .. _tar-examples:
 
@@ -635,10 +623,6 @@ The *only* way to extract an uncompressed tar stream from ``sys.stdin``::
        tar.extract(tarinfo)
    tar.close()
 
-.. % ------------
-.. % Tar format
-.. % ------------
-
 
 .. _tar-formats:
 
@@ -679,11 +663,6 @@ created:
 * The SunOS tar extended format. This format is a variant of the POSIX.1-2001
   pax format, but is not compatible.
 
-.. % ----------------
-.. % Unicode issues
-.. % ----------------
-
-
 .. _tar-unicode:
 
 Unicode issues

Doc/library/test.rst

@@ -33,8 +33,6 @@ written using a "traditional" testing style that compares output printed to
 Writing Unit Tests for the :mod:`test` package
 ----------------------------------------------
 
-.. % 
-
 It is preferred that tests that use the :mod:`unittest` module follow a few
 guidelines. One is to name the test module by starting it with ``test_`` and end
 it with the name of the module being tested. The test methods in the test module

Doc/library/thread.rst

@@ -63,12 +63,13 @@ It defines the following constant and functions:
    Raise the :exc:`SystemExit` exception.  When not caught, this will cause the
    thread to exit silently.
 
-.. % \begin{funcdesc}{exit_prog}{status}
-.. % Exit all threads and report the value of the integer argument
-.. % \var{status} as the exit status of the entire program.
-.. % \strong{Caveat:} code in pending \keyword{finally} clauses, in this thread
-.. % or in other threads, is not executed.
-.. % \end{funcdesc}
+..
+   function:: exit_prog(status)
+
+      Exit all threads and report the value of the integer argument
+      *status* as the exit status of the entire program.
+      **Caveat:** code in pending :keyword:`finally` clauses, in this thread
+      or in other threads, is not executed.
 
 
 .. function:: allocate_lock()

Doc/library/tk.rst

@@ -36,8 +36,8 @@ libraries, see the :ref:`other-gui-packages` section.
    idle.rst
    othergui.rst
 
-.. % Other sections I have in mind are
-.. % Tkinter internals
-.. % Freezing Tkinter applications
+.. Other sections I have in mind are
+   Tkinter internals
+   Freezing Tkinter applications
 
 

Doc/library/tkinter.rst

@@ -59,7 +59,7 @@ Or, more often::
    widget of Tk which usually is the main window of an application. Each instance
    has its own associated Tcl interpreter.
 
-   .. % FIXME: The following keyword arguments are currently recognized:
+   .. FIXME: The following keyword arguments are currently recognized:
 
 
 .. function:: Tcl(screenName=None, baseName=None, className='Tk', useTk=0)
@@ -114,8 +114,6 @@ This section is not designed to be an exhaustive tutorial on either Tk or
 Tkinter.  Rather, it is intended as a stop gap, providing some introductory
 orientation on the system.
 
-.. % Converted to LaTeX by Mike Clarkson.
-
 Credits:
 
 * Tkinter was written by Steen Lumholt and Guido van Rossum.
@@ -218,8 +216,6 @@ The class hierarchy looks complicated, but in actual practice, application
 programmers almost always refer to the classes at the very bottom of the
 hierarchy.
 
-.. % BriefTclTk.html
-
 Notes:
 
 * These classes are provided for the purposes of organizing certain functions
@@ -334,13 +330,6 @@ the Form geometry manager. ::
 How Tk and Tkinter are Related
 ------------------------------
 
-.. % Relationship.html
-
-.. note::
-
-   This was derived from a graphical image; the image will be used more directly in
-   a subsequent version of this document.
-
 From the top down:
 
 Your App Here (Python)
@@ -453,8 +442,6 @@ The Packer
 
 .. index:: single: packing (widgets)
 
-.. % Packer.html
-
 The packer is one of Tk's geometry-management mechanisms.    Geometry managers
 are used to specify the relative positioning of the positioning of widgets
 within their container - their mutual *master*.  In contrast to the more
@@ -463,8 +450,6 @@ packer takes qualitative relationship specification - *above*, *to the left of*,
 *filling*, etc - and works everything out to determine the exact placement
 coordinates for you.
 
-.. % See also \citetitle[classes/ClassPacker.html]{the Packer class interface}.
-
 The size of any *master* widget is determined by the size of the "slave widgets"
 inside.  The packer is used to control where slave widgets appear inside the
 master into which they are packed.  You can pack widgets into frames, and frames
@@ -521,8 +506,6 @@ options are ``variable``, ``textvariable``, ``onvalue``, ``offvalue``, and
 ``value``.  This connection works both ways: if the variable changes for any
 reason, the widget it's connected to will be updated to reflect the new value.
 
-.. % VarCouplings.html
-
 Unfortunately, in the current implementation of :mod:`Tkinter` it is not
 possible to hand over an arbitrary Python variable to a widget through a
 ``variable`` or ``textvariable`` option.  The only kinds of variables for which
@@ -569,8 +552,6 @@ The Window Manager
 
 .. index:: single: window manager (widgets)
 
-.. % WindowMgr.html
-
 In Tk, there is a utility command, ``wm``, for interacting with the window
 manager.  Options to the ``wm`` command allow you to control things like titles,
 placement, icon bitmaps, and the like.  In :mod:`Tkinter`, these commands have
@@ -585,8 +566,6 @@ window that contains an arbitrary widget, you can call the :meth:`_root` method.
 This method begins with an underscore to denote the fact that this function is
 part of the implementation, and not an interface to Tk functionality.
 
-.. % See also \citetitle[classes/ClassWm.html]{the Wm class interface}.
-
 Here are some examples of typical usage::
 
    from Tkinter import *
@@ -614,8 +593,6 @@ Tk Option Data Types
 
 .. index:: single: Tk Option Data Types
 
-.. % OptionTypes.html
-
 anchor
    Legal values are points of the compass: ``"n"``, ``"ne"``, ``"e"``, ``"se"``,
    ``"s"``, ``"sw"``, ``"w"``, ``"nw"``, and also ``"center"``.
@@ -695,8 +672,6 @@ Bindings and Events
    single: bind (widgets)
    single: events (widgets)
 
-.. % Bindings.html
-
 The bind method from the widget command allows you to watch for certain events
 and to have a callback function trigger when that event type occurs.  The form
 of the bind method is::
@@ -752,8 +727,6 @@ A number of widgets require"index" parameters to be passed.  These are used to
 point at a specific place in a Text widget, or to particular characters in an
 Entry widget, or to particular menu items in a Menu widget.
 
-.. % Index.html
-
 Entry widget indexes (index, view index, etc.)
    Entry widgets have options that refer to character positions in the text being
    displayed.  You can use these :mod:`Tkinter` functions to access these special

Doc/library/undoc.rst

@@ -169,3 +169,27 @@ 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}.
+
+:mod:`timing`
+   --- Measure time intervals to high resolution (use :func:`time.clock` instead).
+
+
+SGI-specific Extension modules
+==============================
+
+The following are SGI specific, and may be out of touch with the current version
+of reality.
+
+:mod:`cl`
+   --- Interface to the SGI compression library.
+
+:mod:`sv`
+   --- Interface to the "simple video" board on SGI Indigo (obsolete hardware).
+

Doc/library/wave.rst

-.. % Documentations stolen and LaTeX'ed from comments in file.
-
-
 :mod:`wave` --- Read and write WAV files
 ========================================
 
 .. module:: wave
    :synopsis: Provide an interface to the WAV sound format.
 .. sectionauthor:: Moshe Zadka <moshez@zadka.site.co.il>
-
+.. Documentations stolen from comments in file.
 
 The :mod:`wave` module provides a convenient interface to the WAV sound format.
 It does not support compression/decompression, but it does support mono/stereo.

Doc/library/weakref.rst

@@ -13,8 +13,8 @@
 The :mod:`weakref` module allows the Python programmer to create :dfn:`weak
 references` to objects.
 
-.. % When making changes to the examples in this file, be sure to update
-.. % Lib/test/test_weakref.py::libreftest too!
+.. When making changes to the examples in this file, be sure to update
+   Lib/test/test_weakref.py::libreftest too!
 
 In the following, the term :dfn:`referent` means the object which is referred to
 by a weak reference.
@@ -306,7 +306,7 @@ objects that it has seen before.  The IDs of the objects can then be used in
 other data structures without forcing the objects to remain alive, but the
 objects can still be retrieved by ID if they do.
 
-.. % Example contributed by Tim Peters.
+.. Example contributed by Tim Peters.
 
 ::
 

Doc/library/wsgiref.rst

@@ -27,7 +27,7 @@ to the WSGI specification (:pep:`333`).
 See http://www.wsgi.org for more information about WSGI, and links to tutorials
 and other resources.
 
-.. % XXX If you're just trying to write a web application...
+.. XXX If you're just trying to write a web application...
 
 
 :mod:`wsgiref.util` -- WSGI environment utilities

Doc/library/xml.dom.minidom.rst

@@ -201,11 +201,11 @@ rules apply:
 
 * Operations are used as methods. Since the DOM uses only :keyword:`in`
   parameters, the arguments are passed in normal order (from left to right).
-  There are no optional arguments. :keyword:`void` operations return ``None``.
+  There are no optional arguments. ``void`` operations return ``None``.
 
 * IDL attributes map to instance attributes. For compatibility with the OMG IDL
   language mapping for Python, an attribute ``foo`` can also be accessed through
-  accessor methods :meth:`_get_foo` and :meth:`_set_foo`.  :keyword:`readonly`
+  accessor methods :meth:`_get_foo` and :meth:`_set_foo`.  ``readonly``
   attributes must not be changed; this is not enforced at runtime.
 
 * The types ``short int``, ``unsigned int``, ``unsigned long long``, and
@@ -216,7 +216,7 @@ rules apply:
   Values of type ``DOMString`` may also be ``None`` where allowed to have the IDL
   ``null`` value by the DOM specification from the W3C.
 
-* :keyword:`const` declarations map to variables in their respective scope (e.g.
+* ``const`` declarations map to variables in their respective scope (e.g.
   ``xml.dom.minidom.Node.PROCESSING_INSTRUCTION_NODE``); they must not be changed.
 
 * ``DOMException`` is currently not supported in :mod:`xml.dom.minidom`.

Doc/library/xml.dom.rst

@@ -38,13 +38,13 @@ DOM Level 2 recommendation.
    package <http://pyxml.sourceforge.net/>`_.  Refer to the documentation bundled
    with that package for information on the current state of DOM Level 3 support.
 
-.. % What if your needs are somewhere between SAX and the DOM?  Perhaps
-.. % you cannot afford to load the entire tree in memory but you find the
-.. % SAX model somewhat cumbersome and low-level.  There is also a module
-.. % called xml.dom.pulldom that allows you to build trees of only the
-.. % parts of a document that you need structured access to.  It also has
-.. % features that allow you to find your way around the DOM.
-.. % See http://www.prescod.net/python/pulldom
+.. What if your needs are somewhere between SAX and the DOM?  Perhaps
+   you cannot afford to load the entire tree in memory but you find the
+   SAX model somewhat cumbersome and low-level.  There is also a module
+   called xml.dom.pulldom that allows you to build trees of only the
+   parts of a document that you need structured access to.  It also has
+   features that allow you to find your way around the DOM.
+   See http://www.prescod.net/python/pulldom
 
 DOM applications typically start by parsing some XML into a DOM.  How this is
 accomplished is not covered at all by DOM Level 1, and Level 2 provides only
@@ -148,7 +148,7 @@ provided as part of this module does provide the constants used for the
 within the class rather than at the module level to conform with the DOM
 specifications.
 
-.. % Should the Node documentation go here?
+.. Should the Node documentation go here?
 
 
 .. _dom-objects:
@@ -893,7 +893,7 @@ attribute.
 
    This is raised if data is specified for a node which does not support data.
 
-   .. % XXX  a better explanation is needed!
+   .. XXX  a better explanation is needed!
 
 
 .. exception:: NoModificationAllowedErr
@@ -906,7 +906,7 @@ attribute.
 
    Raised when an invalid or illegal string is specified.
 
-   .. % XXX  how is this different from InvalidCharacterErr ???
+   .. XXX  how is this different from InvalidCharacterErr?
 
 
 .. exception:: WrongDocumentErr
@@ -988,8 +988,8 @@ Additionally, the :class:`DOMString` defined in the recommendation is mapped to
 a Python string or Unicode string.  Applications should be able to handle
 Unicode whenever a string is returned from the DOM.
 
-The IDL :keyword:`null` value is mapped to ``None``, which may be accepted or
-provided by the implementation whenever :keyword:`null` is allowed by the API.
+The IDL ``null`` value is mapped to ``None``, which may be accepted or
+provided by the implementation whenever ``null`` is allowed by the API.
 
 
 .. _dom-accessor-methods:
@@ -998,7 +998,7 @@ Accessor Methods
 ^^^^^^^^^^^^^^^^
 
 The mapping from OMG IDL to Python defines accessor functions for IDL
-:keyword:`attribute` declarations in much the way the Java mapping does.
+``attribute`` declarations in much the way the Java mapping does.
 Mapping the IDL declarations ::
 
    readonly attribute string someValue;
@@ -1017,13 +1017,13 @@ likely to work, and wrapper objects may be needed on the client if the DOM
 objects are accessed via CORBA. While this does require some additional
 consideration for CORBA DOM clients, the implementers with experience using DOM
 over CORBA from Python do not consider this a problem.  Attributes that are
-declared :keyword:`readonly` may not restrict write access in all DOM
+declared ``readonly`` may not restrict write access in all DOM
 implementations.
 
 In the Python DOM API, accessor functions are not required.  If provided, they
 should take the form defined by the Python IDL mapping, but these methods are
 considered unnecessary since the attributes are accessible directly from Python.
-"Set" accessors should never be provided for :keyword:`readonly` attributes.
+"Set" accessors should never be provided for ``readonly`` attributes.
 
 The IDL definitions do not fully embody the requirements of the W3C DOM API,
 such as the notion of certain objects, such as the return value of

Doc/library/xml.etree.rst

@@ -12,7 +12,7 @@ common components  from the ElementTree API library.  In the current release,
 this package contains the :mod:`ElementTree`,  :mod:`ElementPath`, and
 :mod:`ElementInclude` modules from the full  ElementTree distribution.
 
-.. % XXX To be continued!
+.. XXX To be continued!
 
 
 .. seealso::

Doc/library/xml.sax.handler.rst

@@ -205,7 +205,7 @@ events in the input document:
    information to the application to expand prefixes in those contexts itself, if
    necessary.
 
-   .. % XXX This is not really the default, is it? MvL
+   .. XXX This is not really the default, is it? MvL
 
    Note that :meth:`startPrefixMapping` and :meth:`endPrefixMapping` events are not
    guaranteed to be properly nested relative to each-other: all

Doc/library/xml.sax.reader.rst

@@ -348,8 +348,8 @@ are also provided:
 
    Return the value of attribute *name*.
 
-.. % getValueByQName, getNameByQName, getQNameByName, getQNames available
-.. % here already, but documented only for derived class.
+.. getValueByQName, getNameByQName, getQNameByName, getQNames available
+.. here already, but documented only for derived class.
 
 
 .. _attributes-ns-objects:

Doc/library/xmlrpclib.rst

-
 :mod:`xmlrpclib` --- XML-RPC client access
 ==========================================
 
@@ -8,8 +7,8 @@
 .. sectionauthor:: Eric S. Raymond <esr@snark.thyrsus.com>
 
 
-.. % Not everything is documented yet.  It might be good to describe
-.. % Marshaller, Unmarshaller, getparser, dumps, loads, and Transport.
+.. XXX Not everything is documented yet.  It might be good to describe
+   Marshaller, Unmarshaller, getparser, dumps, loads, and Transport.
 
 XML-RPC is a Remote Procedure Call method that uses XML passed via HTTP as a
 transport.  With it, a client can call methods with parameters on a remote
@@ -529,11 +528,9 @@ Example of Client Usage
        print("ERROR", v)
 
 To access an XML-RPC server through a proxy, you need to define  a custom
-transport.  The following example,  written by NoboNobo, shows how:
-
-.. % fill in original author's name if we ever learn it
+transport.  The following example shows how:
 
-.. % Example taken from http://lowlife.jp/nobonobo/wiki/xmlrpcwithproxy.html
+.. Example taken from http://lowlife.jp/nobonobo/wiki/xmlrpcwithproxy.html
 
 ::
 

Doc/library/zipfile.rst

@@ -7,9 +7,6 @@
 .. moduleauthor:: James C. Ahlstrom <jim@interet.com>
 .. sectionauthor:: James C. Ahlstrom <jim@interet.com>
 
-
-.. % LaTeX markup by Fred L. Drake, Jr. <fdrake@acm.org>
-
 The ZIP file format is a common archive and compression standard. This module
 provides tools to create, read, write, append, and list a ZIP file.  Any
 advanced use of this module will require an understanding of the format, as

Doc/library/zlib.rst

@@ -74,8 +74,6 @@ The available exception and functions in this module are:
    the algorithm is designed for use as a checksum algorithm, it is not suitable
    for use as a general hash algorithm.
 
-   .. % 
-
 
 .. function:: decompress(string[, wbits[, bufsize]])
 

Doc/reference/compound_stmts.rst

@@ -72,6 +72,8 @@ on a separate line for clarity.
 
 
 .. _if:
+.. _elif:
+.. _else:
 
 The :keyword:`if` statement
 ===========================
@@ -200,6 +202,8 @@ returns the list ``[0, 1, 2]``.
 
 
 .. _try:
+.. _except:
+.. _finally:
 
 The :keyword:`try` statement
 ============================
@@ -326,6 +330,7 @@ may be found in section :ref:`raise`.
 
 
 .. _with:
+.. _as:
 
 The :keyword:`with` statement
 =============================
@@ -382,6 +387,7 @@ The execution of the :keyword:`with` statement proceeds as follows:
 
 
 .. _function:
+.. _def:
 
 Function definitions
 ====================

Doc/reference/datamodel.rst

@@ -202,8 +202,6 @@ Numbers
       operation except left shift, if it yields a result in the plain integer domain
       without causing overflow, will yield the same result when using mixed operands.
 
-      .. % Integers
-
    Floating point numbers
       .. index::
          object: floating point
@@ -229,8 +227,6 @@ Numbers
       The real and imaginary parts of a complex number ``z`` can be retrieved through
       the read-only attributes ``z.real`` and ``z.imag``.
 
-   .. % Numbers
-
 Sequences
    .. index::
       builtin: len
@@ -302,8 +298,6 @@ Sequences
          parentheses must be usable for grouping of expressions).  An empty
          tuple can be formed by an empty pair of parentheses.
 
-      .. % Immutable sequences
-
    Mutable sequences
       .. index::
          object: mutable sequence
@@ -341,10 +335,6 @@ Sequences
       The extension module :mod:`array` provides an additional example of a
       mutable sequence type.
 
-      .. % Mutable sequences
-
-   .. % Sequences
-
 Set types
    .. index::
       builtin: len
@@ -379,8 +369,6 @@ Set types
       :term:`hashable`, it can be used again as an element of another set, or as
       a dictionary key.
 
-   .. % Set types
-
 Mappings
    .. index::
       builtin: len
@@ -418,8 +406,6 @@ Mappings
       The extension modules :mod:`dbm`, :mod:`gdbm`, and :mod:`bsddb` provide
       additional examples of mapping types.
 
-   .. % Mapping types
-
 Callable types
    .. index::
       object: callable
@@ -652,8 +638,6 @@ Modules
    object used to initialize the module (since it isn't needed once the
    initialization is done).
 
-   .. % 
-
    Attribute assignment updates the module's namespace dictionary, e.g., ``m.x =
    1`` is equivalent to ``m.__dict__["x"] = 1``.
 
@@ -992,12 +976,53 @@ Internal types
       described above, under "User-defined methods". Class method objects are created
       by the built-in :func:`classmethod` constructor.
 
-   .. % Internal types
-
-.. % =========================================================================
 
 .. _newstyle:
 
+New-style and classic classes
+=============================
+
+Classes and instances come in two flavors: old-style or classic, and new-style.
+
+Up to Python 2.1, old-style classes were the only flavour available to the user.
+The concept of (old-style) class is unrelated to the concept of type: if *x* is
+an instance of an old-style class, then ``x.__class__`` designates the class of
+*x*, but ``type(x)`` is always ``<type 'instance'>``.  This reflects the fact
+that all old-style instances, independently of their class, are implemented with
+a single built-in type, called ``instance``.
+
+New-style classes were introduced in Python 2.2 to unify classes and types.  A
+new-style class neither more nor less than a user-defined type.  If *x* is an
+instance of a new-style class, then ``type(x)`` is the same as ``x.__class__``.
+
+The major motivation for introducing new-style classes is to provide a unified
+object model with a full meta-model.  It also has a number of immediate
+benefits, like the ability to subclass most built-in types, or the introduction
+of "descriptors", which enable computed properties.
+
+For compatibility reasons, classes are still old-style by default.  New-style
+classes are created by specifying another new-style class (i.e. a type) as a
+parent class, or the "top-level type" :class:`object` if no other parent is
+needed.  The behaviour of new-style classes differs from that of old-style
+classes in a number of important details in addition to what :func:`type`
+returns.  Some of these changes are fundamental to the new object model, like
+the way special methods are invoked.  Others are "fixes" that could not be
+implemented before for compatibility concerns, like the method resolution order
+in case of multiple inheritance.
+
+This manual is not up-to-date with respect to new-style classes.  For now,
+please see http://www.python.org/doc/newstyle.html for more information.
+
+.. index::
+   single: class
+   single: class
+   single: class
+
+The plan is to eventually drop old-style classes, leaving only the semantics of
+new-style classes.  This change will probably only be feasible in Python 3.0.
+new-style classic old-style
+
+
 .. _specialnames:
 
 Special method names

Doc/reference/expressions.rst

@@ -937,6 +937,10 @@ must be integers.
 
 
 .. _comparisons:
+.. _is:
+.. _isnot:
+.. _in:
+.. _notin:
 
 Comparisons
 ===========
@@ -1058,6 +1062,9 @@ yields the inverse truth value.
 
 
 .. _booleans:
+.. _and:
+.. _or:
+.. _not:
 
 Boolean operations
 ==================

Doc/reference/lexical_analysis.rst

@@ -100,8 +100,7 @@ If an encoding is declared, the encoding name must be recognized by Python. The
 encoding is used for all lexical analysis, including string literals, comments
 and identifiers. The encoding declaration must appear on a line of its own.
 
-A list of standard encodings can be found in the section
-:ref:`standard-encodings`.
+.. XXX there should be a list of supported encodings.
 
 
 .. _explicit-joining: