Branch merge

12 files changed, 50 insertions, 34 deletions

diff --git a/Doc/c-api/init.rst b/Doc/c-api/init.rst
index 7c702812d6..c323eef4cf 100644
--- a/Doc/c-api/init.rst
+++ b/Doc/c-api/init.rst
@@ -126,7 +126,7 @@ Process-wide parameters
    program name is ``'/usr/local/bin/python'``, the prefix is ``'/usr/local'``. The
    returned string points into static storage; the caller should not modify its
    value.  This corresponds to the :makevar:`prefix` variable in the top-level
-   :file:`Makefile` and the :option:`--prefix` argument to the :program:`configure`
+   :file:`Makefile` and the ``--prefix`` argument to the :program:`configure`
    script at build time.  The value is available to Python code as ``sys.prefix``.
    It is only useful on Unix.  See also the next function.
 
@@ -139,7 +139,7 @@ Process-wide parameters
    program name is ``'/usr/local/bin/python'``, the exec-prefix is
    ``'/usr/local'``.  The returned string points into static storage; the caller
    should not modify its value.  This corresponds to the :makevar:`exec_prefix`
-   variable in the top-level :file:`Makefile` and the :option:`--exec-prefix`
+   variable in the top-level :file:`Makefile` and the ``--exec-prefix``
    argument to the :program:`configure` script at build  time.  The value is
    available to Python code as ``sys.exec_prefix``.  It is only useful on Unix.
 
diff --git a/Doc/documenting/building.rst b/Doc/documenting/building.rst
index 02b3ee3536..dc1c6a0d9a 100644
--- a/Doc/documenting/building.rst
+++ b/Doc/documenting/building.rst
@@ -17,9 +17,9 @@ installed Python and Subversion, you can just run ::
    cd Doc
    make html
 
-to check out the necessary toolset in the `tools/` subdirectory and build the
-HTML output files.  To view the generated HTML, point your favorite browser at
-the top-level index `build/html/index.html` after running "make".
+to check out the necessary toolset in the :file:`tools/` subdirectory and build
+the HTML output files.  To view the generated HTML, point your favorite browser
+at the top-level index :file:`build/html/index.html` after running "make".
 
 Available make targets are:
 
@@ -50,10 +50,10 @@ Available make targets are:
 
  * "pydoc-topics", which builds a Python module containing a dictionary with
    plain text documentation for the labels defined in
-   `tools/sphinxext/pyspecific.py` -- pydoc needs these to show topic and
+   :file:`tools/sphinxext/pyspecific.py` -- pydoc needs these to show topic and
    keyword help.
 
-A "make update" updates the Subversion checkouts in `tools/`.
+A "make update" updates the Subversion checkouts in :file:`tools/`.
 
 
 Without make
diff --git a/Doc/documenting/markup.rst b/Doc/documenting/markup.rst
index 4f1fcae9e7..25801c7564 100644
--- a/Doc/documenting/markup.rst
+++ b/Doc/documenting/markup.rst
@@ -472,7 +472,10 @@ in a different style:
 
 .. describe:: keyword
 
-   The name of a keyword in Python.
+   The name of a Python keyword.  Using this role will generate a link to the
+   documentation of the keyword.  ``True``, ``False`` and ``None`` do not use
+   this role, but simple code markup (````True````), given that they're
+   fundamental to the language and should be known to any programmer.
 
 .. describe:: mailheader
 
diff --git a/Doc/faq/design.rst b/Doc/faq/design.rst
index 0943796e69..962b4ef4fc 100644
--- a/Doc/faq/design.rst
+++ b/Doc/faq/design.rst
@@ -684,7 +684,7 @@ construction of large programs.
 Python 2.6 adds an :mod:`abc` module that lets you define Abstract Base Classes
 (ABCs).  You can then use :func:`isinstance` and :func:`issubclass` to check
 whether an instance or a class implements a particular ABC.  The
-:mod:`collections` modules defines a set of useful ABCs such as
+:mod:`collections` module defines a set of useful ABCs such as
 :class:`Iterable`, :class:`Container`, and :class:`MutableMapping`.
 
 For Python, many of the advantages of interface specifications can be obtained
diff --git a/Doc/faq/windows.rst b/Doc/faq/windows.rst
index 47c09ad014..96d1c51710 100644
--- a/Doc/faq/windows.rst
+++ b/Doc/faq/windows.rst
@@ -542,7 +542,7 @@ A trick to get it to run an arbitrary file is to construct a call to
 :func:`execfile` with the name of your file as argument.
 
 Also note that you can not mix-and-match Debug and Release versions.  If you
-wish to use the Debug Multithreaded DLL, then your module *must* have an "_d"
+wish to use the Debug Multithreaded DLL, then your module *must* have ``_d``
 appended to the base name.
 
 
diff --git a/Doc/library/argparse.rst b/Doc/library/argparse.rst
index bf0899d8ab..09f97a9a16 100644
--- a/Doc/library/argparse.rst
+++ b/Doc/library/argparse.rst
@@ -153,7 +153,7 @@ ArgumentParser objects
      conflicting optionals.
 
    * prog_ - The name of the program (default:
-     :data:`sys.argv[0]`)
+     ``sys.argv[0]``)
 
    * usage_ - The string describing the program usage (default: generated)
 
diff --git a/Doc/library/string.rst b/Doc/library/string.rst
index 9ee81b596c..20fcae9773 100644
--- a/Doc/library/string.rst
+++ b/Doc/library/string.rst
@@ -248,6 +248,8 @@ keyword.  If it's a number, it refers to a positional argument, and if it's a ke
 it refers to a named keyword argument.  If the numerical arg_names in a format string
 are 0, 1, 2, ... in sequence, they can all be omitted (not just some)
 and the numbers 0, 1, 2, ... will be automatically inserted in that order.
+Because *arg_name* is not quote-delimited, it is not possible to specify arbitrary
+dictionary keys (e.g., the strings ``'10'`` or ``':-]'``) within a format string.
 The *arg_name* can be followed by any number of index or
 attribute expressions. An expression of the form ``'.name'`` selects the named
 attribute using :func:`getattr`, while an expression of the form ``'[index]'``
diff --git a/Doc/library/struct.rst b/Doc/library/struct.rst
index 9c7fdd8138..817c570ee0 100644
--- a/Doc/library/struct.rst
+++ b/Doc/library/struct.rst
@@ -22,8 +22,8 @@ structs and the intended conversion to/from Python values.
    alignment is taken into account when unpacking.  This behavior is chosen so
    that the bytes of a packed struct correspond exactly to the layout in memory
    of the corresponding C struct.  To handle platform-independent data formats
-   or omit implicit pad bytes, use `standard` size and alignment instead of
-   `native` size and alignment: see :ref:`struct-alignment` for details.
+   or omit implicit pad bytes, use ``standard`` size and alignment instead of
+   ``native`` size and alignment: see :ref:`struct-alignment` for details.
 
 Functions and Exceptions
 ------------------------
diff --git a/Doc/library/unittest.rst b/Doc/library/unittest.rst
index 42ae8e2c57..16a3a36695 100644
--- a/Doc/library/unittest.rst
+++ b/Doc/library/unittest.rst
@@ -307,7 +307,7 @@ as the start directory.
 
     Test discovery loads tests by importing them. Once test discovery has
     found all the test files from the start directory you specify it turns the
-    paths into package names to import. For example `foo/bar/baz.py` will be
+    paths into package names to import. For example :file:`foo/bar/baz.py` will be
     imported as ``foo.bar.baz``.
 
     If you have a package installed globally and attempt test discovery on
@@ -905,11 +905,11 @@ Test cases
    +---------------------------------------------------------+--------------------------------------+------------+
    | Method                                                  | Checks that                          | New in     |
    +=========================================================+======================================+============+
-   | :meth:`assertRaises(exc, fun, *args, **kwds)            | ``fun(*args, **kwds)`` raises `exc`  |            |
+   | :meth:`assertRaises(exc, fun, *args, **kwds)            | ``fun(*args, **kwds)`` raises *exc*  |            |
    | <TestCase.assertRaises>`                                |                                      |            |
    +---------------------------------------------------------+--------------------------------------+------------+
-   | :meth:`assertRaisesRegexp(exc, re, fun, *args, **kwds)  | ``fun(*args, **kwds)`` raises `exc`  | 2.7        |
-   | <TestCase.assertRaisesRegexp>`                          | and the message matches `re`         |            |
+   | :meth:`assertRaisesRegexp(exc, re, fun, *args, **kwds)  | ``fun(*args, **kwds)`` raises *exc*  | 2.7        |
+   | <TestCase.assertRaisesRegexp>`                          | and the message matches *re*         |            |
    +---------------------------------------------------------+--------------------------------------+------------+
 
    .. method:: assertRaises(exception, callable, *args, **kwds)
@@ -995,7 +995,7 @@ Test cases
    | <TestCase.assertItemsEqual>`          | works with unhashable objs     |              |
    +---------------------------------------+--------------------------------+--------------+
    | :meth:`assertDictContainsSubset(a, b) | all the key/value pairs        | 2.7          |
-   | <TestCase.assertDictContainsSubset>`  | in `a` exist in `b`            |              |
+   | <TestCase.assertDictContainsSubset>`  | in *a* exist in *b*            |              |
    +---------------------------------------+--------------------------------+--------------+
 
 
diff --git a/Doc/library/urllib2.rst b/Doc/library/urllib2.rst
index d0d4727b6d..b66ebd73d8 100644
--- a/Doc/library/urllib2.rst
+++ b/Doc/library/urllib2.rst
@@ -36,7 +36,7 @@ The :mod:`urllib2` module defines the following functions:
    :mimetype:`application/x-www-form-urlencoded` format.  The
    :func:`urllib.urlencode` function takes a mapping or sequence of 2-tuples and
    returns a string in this format. urllib2 module sends HTTP/1.1 requests with
-   `Connection:close` header included.
+   ``Connection:close`` header included.
 
    The optional *timeout* parameter specifies a timeout in seconds for blocking
    operations like the connection attempt (if not specified, the global default
diff --git a/Lib/compileall.py b/Lib/compileall.py
index 910f3057f4..5cfa8bed3f 100644
--- a/Lib/compileall.py
+++ b/Lib/compileall.py
@@ -1,4 +1,4 @@
-"""Module/script to "compile" all .py files to .pyc (or .pyo) file.
+"""Module/script to byte-compile all .py files to .pyc (or .pyo) files.
 
 When called as a script with arguments, this compiles the directories
 given as arguments recursively; the -l option prevents it from
@@ -26,8 +26,8 @@ def compile_dir(dir, maxlevels=10, ddir=None,
 
     dir:       the directory to byte-compile
     maxlevels: maximum recursion level (default 10)
-    ddir:      if given, purported directory name (this is the
-               directory name that will show up in error messages)
+    ddir:      the directory that will be prepended to the path to the
+               file as it is compiled into each byte-code file.
     force:     if 1, force compilation, even if timestamps are up-to-date
     quiet:     if 1, be quiet during compilation
     """
@@ -64,8 +64,8 @@ def compile_file(fullname, ddir=None, force=0, rx=None, quiet=0):
     Arguments (only fullname is required):
 
     fullname:  the file to byte-compile
-    ddir:      if given, purported directory name (this is the
-               directory name that will show up in error messages)
+    ddir:      if given, the directory name compiled in to the
+               byte-code file.
     force:     if 1, force compilation, even if timestamps are up-to-date
     quiet:     if 1, be quiet during compilation
     """
@@ -157,14 +157,27 @@ def main():
         print msg
         print "usage: python compileall.py [-l] [-f] [-q] [-d destdir] " \
               "[-x regexp] [-i list] [directory|file ...]"
-        print "-l: don't recurse down"
+        print
+        print "arguments: zero or more file and directory names to compile; " \
+              "if no arguments given, "
+        print "           defaults to the equivalent of -l sys.path"
+        print
+        print "options:"
+        print "-l: don't recurse into subdirectories"
         print "-f: force rebuild even if timestamps are up-to-date"
-        print "-q: quiet operation"
-        print "-d destdir: purported directory name for error messages"
-        print "   if no directory arguments, -l sys.path is assumed"
-        print "-x regexp: skip files matching the regular expression regexp"
-        print "   the regexp is searched for in the full path of the file"
-        print "-i list: expand list with its content (file and directory names)"
+        print "-q: output only error messages"
+        print "-d destdir: directory to prepend to file paths for use in " \
+              "compile-time tracebacks and in"
+        print "            runtime tracebacks in cases where the source " \
+              "file is unavailable"
+        print "-x regexp: skip files matching the regular expression regexp; " \
+              "the regexp is searched for"
+        print "           in the full path of each file considered for " \
+              "compilation"
+        print "-i file: add all the files and directories listed in file to " \
+              "the list considered for"
+        print '         compilation; if "-", names are read from stdin'
+
         sys.exit(2)
     maxlevels = 10
     ddir = None
@@ -205,7 +218,7 @@ def main():
         else:
             success = compile_path()
     except KeyboardInterrupt:
-        print "\n[interrupt]"
+        print "\n[interrupted]"
         success = 0
     return success
 
diff --git a/Lib/pipes.py b/Lib/pipes.py
index 02e125743b..26750f6ab8 100644
--- a/Lib/pipes.py
+++ b/Lib/pipes.py
@@ -54,8 +54,6 @@ for the built-in function open() or for os.popen().
 
 To create a new template object initialized to a given one:
    t2 = t.clone()
-
-For an example, see the function test() at the end of the file.
 """                                     # '