Merged revisions 72661,72675-72677,72679,72712,72801,72820 via svnmerge from

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

........
  r72661 | georg.brandl | 2009-05-15 10:03:03 +0200 (Fr, 15 Mai 2009) | 1 line

  Fix example output for doctest-like demos.
........
  r72675 | georg.brandl | 2009-05-16 13:13:21 +0200 (Sa, 16 Mai 2009) | 1 line

  #6034: clarify __reversed__ doc.
........
  r72676 | georg.brandl | 2009-05-16 13:14:46 +0200 (Sa, 16 Mai 2009) | 1 line

  #6025: fix signature of parse().
........
  r72677 | georg.brandl | 2009-05-16 13:18:55 +0200 (Sa, 16 Mai 2009) | 1 line

  #6009: undocument default argument of Option as deprecated.
........
  r72679 | georg.brandl | 2009-05-16 13:24:41 +0200 (Sa, 16 Mai 2009) | 1 line

  Fix about and bugs pages to match real workflow.
........
  r72712 | georg.brandl | 2009-05-17 10:55:00 +0200 (So, 17 Mai 2009) | 1 line

  #5935: mention that BROWSER is looked for in PATH.
........
  r72801 | georg.brandl | 2009-05-20 20:31:14 +0200 (Mi, 20 Mai 2009) | 1 line

  #6055: refer to "sqlite3" consistently.
........
  r72820 | georg.brandl | 2009-05-22 09:23:32 +0200 (Fr, 22 Mai 2009) | 1 line

  Use raise X(y).
........

9 files changed, 44 insertions, 31 deletions

diff --git a/Doc/about.rst b/Doc/about.rst
index a5adf07..9483ca5 100644
--- a/Doc/about.rst
+++ b/Doc/about.rst
@@ -7,8 +7,8 @@ These documents are generated from `reStructuredText
 <http://docutils.sf.net/rst.html>`_ sources by *Sphinx*, a document processor
 specifically written for the Python documentation.
 
-In the online version of these documents, you can submit comments and suggest
-changes directly on the documentation pages.
+.. In the online version of these documents, you can submit comments and suggest
+   changes directly on the documentation pages.
 
 Development of the documentation and its toolchain takes place on the
 docs@python.org mailing list.  We're always looking for volunteers wanting
@@ -24,7 +24,8 @@ Many thanks go to:
   <http://effbot.org/zone/pyref.htm>`_ project from which Sphinx got many good
   ideas.
 
-See :ref:`reporting-bugs` for information how to report bugs in Python itself.
+See :ref:`reporting-bugs` for information how to report bugs in this
+documentation, or Python itself.
 
 .. including the ACKS file here so that it can be maintained separately
 .. include:: ACKS.txt
diff --git a/Doc/bugs.rst b/Doc/bugs.rst
index 9c6e524..dc7d388 100644
--- a/Doc/bugs.rst
+++ b/Doc/bugs.rst
@@ -19,6 +19,9 @@ the problem has already been fixed for the next release, or additional
 information is needed (in which case you are welcome to provide it if you can!).
 To do this, search the bug database using the search box on the top of the page.
 
+In the case of documentation bugs, look at the most recent development docs at
+http://docs.python.org/dev to see if the bug has been fixed.
+
 If the problem you're reporting is not already in the bug tracker, go back to
 the Python Bug Tracker.  If you don't already have a tracker account, select the
 "Register" link in the sidebar and undergo the registration procedure.
diff --git a/Doc/includes/sqlite3/text_factory.py b/Doc/includes/sqlite3/text_factory.py
index 2dab8e4..4c25b00 100644
--- a/Doc/includes/sqlite3/text_factory.py
+++ b/Doc/includes/sqlite3/text_factory.py
@@ -13,7 +13,7 @@ cur.execute("select ?", (AUSTRIA,))
 row = cur.fetchone()
 assert row[0] == AUSTRIA
 
-# but we can make pysqlite always return bytestrings ...
+# but we can make sqlite3 always return bytestrings ...
 con.text_factory = str
 cur.execute("select ?", (AUSTRIA,))
 row = cur.fetchone()
@@ -26,11 +26,12 @@ assert row[0] == AUSTRIA.encode("utf-8")
 # here we implement one that will ignore Unicode characters that cannot be
 # decoded from UTF-8
 con.text_factory = lambda x: str(x, "utf-8", "ignore")
-cur.execute("select ?", ("this is latin1 and would normally create errors" + "\xe4\xf6\xfc".encode("latin1"),))
+cur.execute("select ?", ("this is latin1 and would normally create errors" +
+                         "\xe4\xf6\xfc".encode("latin1"),))
 row = cur.fetchone()
 assert type(row[0]) == str
 
-# pysqlite offers a builtin optimized text_factory that will return bytestring
+# sqlite3 offers a builtin optimized text_factory that will return bytestring
 # objects, if the data is in ASCII only, and otherwise return unicode objects
 con.text_factory = sqlite3.OptimizedUnicode
 cur.execute("select ?", (AUSTRIA,))
diff --git a/Doc/library/ctypes.rst b/Doc/library/ctypes.rst
index ac2f2fd..ba80478 100644
--- a/Doc/library/ctypes.rst
+++ b/Doc/library/ctypes.rst
@@ -338,9 +338,9 @@ within *IDLE* or *PythonWin*::
    >>> printf("Hello, %s\n", "World!")
    Hello, World!
    14
-   >>> printf("Hello, %S", u"World!")
+   >>> printf("Hello, %S\n", u"World!")
    Hello, World!
-   13
+   14
    >>> printf("%d bottles of beer\n", 42)
    42 bottles of beer
    19
@@ -355,7 +355,7 @@ unicode strings have to be wrapped in their corresponding ``ctypes`` type, so
 that they can be converted to the required C data type::
 
    >>> printf("An int %d, a double %f\n", 1234, c_double(3.14))
-   Integer 1234, double 3.1400001049
+   An int 1234, a double 3.140000
    31
    >>>
 
@@ -411,9 +411,9 @@ prototype for a C function), and tries to convert the arguments to valid types::
    Traceback (most recent call last):
      File "<stdin>", line 1, in ?
    ArgumentError: argument 2: exceptions.TypeError: wrong type
-   >>> printf("%s %d %f", "X", 2, 3)
-   X 2 3.00000012
-   12
+   >>> printf("%s %d %f\n", "X", 2, 3)
+   X 2 3.000000
+   13
    >>>
 
 If you have defined your own classes which you pass to function calls, you have
diff --git a/Doc/library/optparse.rst b/Doc/library/optparse.rst
index 2cf8042..eae6121 100644
--- a/Doc/library/optparse.rst
+++ b/Doc/library/optparse.rst
@@ -1072,10 +1072,10 @@ to a particular option, or fail to pass a required option attribute,
   tells :mod:`optparse` where to write it: :attr:`dest` names an attribute of the
   ``options`` object that :mod:`optparse` builds as it parses the command line.
 
-* ``default`` (deprecated)
+* ``default``
 
   The value to use for this option's destination if the option is not seen on the
-  command line.  Deprecated; use ``parser.set_defaults()`` instead.
+  command line.  See also ``parser.set_defaults()``.
 
 * ``nargs`` (default: 1)
 
diff --git a/Doc/library/sqlite3.rst b/Doc/library/sqlite3.rst
index d849247..6c3f6e2 100644
--- a/Doc/library/sqlite3.rst
+++ b/Doc/library/sqlite3.rst
@@ -13,7 +13,7 @@ SQLite for internal data storage.  It's also possible to prototype an
 application using SQLite and then port the code to a larger database such as
 PostgreSQL or Oracle.
 
-pysqlite was written by Gerhard Häring and provides a SQL interface compliant
+sqlite3 was written by Gerhard Häring and provides a SQL interface compliant
 with the DB-API 2.0 specification described by :pep:`249`.
 
 To use the module, you must first create a :class:`Connection` object that
@@ -50,8 +50,9 @@ is insecure; it makes your program vulnerable to an SQL injection attack.
 
 Instead, use the DB-API's parameter substitution.  Put ``?`` as a placeholder
 wherever you want to use a value, and then provide a tuple of values as the
-second argument to the cursor's :meth:`~Cursor.execute` method.  (Other database modules
-may use a different placeholder, such as ``%s`` or ``:1``.) For example::
+second argument to the cursor's :meth:`~Cursor.execute` method.  (Other database
+modules may use a different placeholder, such as ``%s`` or ``:1``.) For
+example::
 
    # Never do this -- insecure!
    symbol = 'IBM'
@@ -90,11 +91,12 @@ This example uses the iterator form::
 .. seealso::
 
    http://www.pysqlite.org
-      The pysqlite web page.
+      The pysqlite web page -- sqlite3 is developed externally under the name
+      "pysqlite".
 
    http://www.sqlite.org
-      The SQLite web page; the documentation describes the syntax and the available
-      data types for the supported SQL dialect.
+      The SQLite web page; the documentation describes the syntax and the
+      available data types for the supported SQL dialect.
 
    :pep:`249` - Database API Specification 2.0
       PEP written by Marc-André Lemburg.
@@ -784,10 +786,10 @@ So if you are within a transaction and issue a command like ``CREATE TABLE
 ...``, ``VACUUM``, ``PRAGMA``, the :mod:`sqlite3` module will commit implicitly
 before executing that command. There are two reasons for doing that. The first
 is that some of these commands don't work within transactions. The other reason
-is that pysqlite needs to keep track of the transaction state (if a transaction
+is that sqlite3 needs to keep track of the transaction state (if a transaction
 is active or not).
 
-You can control which kind of ``BEGIN`` statements pysqlite implicitly executes
+You can control which kind of ``BEGIN`` statements sqlite3 implicitly executes
 (or none at all) via the *isolation_level* parameter to the :func:`connect`
 call, or via the :attr:`isolation_level` property of connections.
 
@@ -799,8 +801,8 @@ statement, or set it to one of SQLite's supported isolation levels: "DEFERRED",
 
 
 
-Using pysqlite efficiently
---------------------------
+Using :mod:`sqlite3` efficiently
+--------------------------------
 
 
 Using shortcut methods
diff --git a/Doc/library/webbrowser.rst b/Doc/library/webbrowser.rst
index 380080b..975d668 100644
--- a/Doc/library/webbrowser.rst
+++ b/Doc/library/webbrowser.rst
@@ -22,7 +22,7 @@ override the platform default list of browsers, as a os.pathsep-separated list
 of browsers to try in order.  When the value of a list part contains the string
 ``%s``, then it is  interpreted as a literal browser command line to be used
 with the argument URL substituted for ``%s``; if the part does not contain
-``%s``, it is simply interpreted as the name of the browser to launch.
+``%s``, it is simply interpreted as the name of the browser to launch. [1]_
 
 For non-Unix platforms, or when a remote browser is available on Unix, the
 controlling process will not wait for the user to finish with the browser, but
@@ -193,3 +193,9 @@ module-level convenience functions:
 
    Open *url* in a new page ("tab") of the browser handled by this controller, if
    possible, otherwise equivalent to :func:`open_new`.
+
+
+.. rubric:: Footnotes
+
+.. [1] Executables named here without a full path will be searched in the
+       directories given in the :envvar:`PATH` environment variable.
diff --git a/Doc/library/xml.dom.minidom.rst b/Doc/library/xml.dom.minidom.rst
index fb3f5cf..b7e4216 100644
--- a/Doc/library/xml.dom.minidom.rst
+++ b/Doc/library/xml.dom.minidom.rst
@@ -28,7 +28,7 @@ DOM applications typically start by parsing some XML into a DOM.  With
 The :func:`parse` function can take either a filename or an open file object.
 
 
-.. function:: parse(filename_or_file, parser)
+.. function:: parse(filename_or_file[, parser[, bufsize]])
 
    Return a :class:`Document` from the given input. *filename_or_file* may be
    either a file name, or a file-like object. *parser*, if given, must be a SAX2
diff --git a/Doc/reference/datamodel.rst b/Doc/reference/datamodel.rst
index 83d2358..2161706 100644
--- a/Doc/reference/datamodel.rst
+++ b/Doc/reference/datamodel.rst
@@ -1700,11 +1700,11 @@ through the container; for mappings, :meth:`__iter__` should be the same as
    reverse iteration.  It should return a new iterator object that iterates
    over all the objects in the container in reverse order.
 
-   If the :meth:`__reversed__` method is not provided, the
-   :func:`reversed` builtin will fall back to using the sequence protocol
-   (:meth:`__len__` and :meth:`__getitem__`).  Objects should normally
-   only provide :meth:`__reversed__` if they do not support the sequence
-   protocol and an efficient implementation of reverse iteration is possible.
+   If the :meth:`__reversed__` method is not provided, the :func:`reversed`
+   builtin will fall back to using the sequence protocol (:meth:`__len__` and
+   :meth:`__getitem__`).  Objects that support the sequence protocol should
+   only provide :meth:`__reversed__` if they can provide an implementation
+   that is more efficient than the one provided by :func:`reversed`.
 
 
 The membership test operators (:keyword:`in` and :keyword:`not in`) are normally