branch merge?

11 files changed, 60 insertions, 19 deletions

diff --git a/Doc/c-api/intro.rst b/Doc/c-api/intro.rst
index 83b98f9..843707d 100644
--- a/Doc/c-api/intro.rst
+++ b/Doc/c-api/intro.rst
@@ -588,8 +588,8 @@ frequently-used builds will be described in the remainder of this section.
 
 Compiling the interpreter with the :c:macro:`Py_DEBUG` macro defined produces
 what is generally meant by "a debug build" of Python. :c:macro:`Py_DEBUG` is
-enabled in the Unix build by adding :option:`--with-pydebug` to the
-:file:`configure` command.  It is also implied by the presence of the
+enabled in the Unix build by adding ``--with-pydebug`` to the
+:file:`./configure` command.  It is also implied by the presence of the
 not-Python-specific :c:macro:`_DEBUG` macro.  When :c:macro:`Py_DEBUG` is enabled
 in the Unix build, compiler optimization is disabled.
 
diff --git a/Doc/distutils/introduction.rst b/Doc/distutils/introduction.rst
index 8dc604d..57d34a4 100644
--- a/Doc/distutils/introduction.rst
+++ b/Doc/distutils/introduction.rst
@@ -79,11 +79,17 @@ Some observations:
   for an example)
 
 To create a source distribution for this module, you would create a setup
-script, :file:`setup.py`, containing the above code, and run::
+script, :file:`setup.py`, containing the above code, and run this command from a
+terminal::
 
    python setup.py sdist
 
-which will create an archive file (e.g., tarball on Unix, ZIP file on Windows)
+For Windows, open a command prompt windows ("DOS box") and change the command
+to::
+
+   setup.py sdist
+
+:command:`sdist` will create an archive file (e.g., tarball on Unix, ZIP file on Windows)
 containing your setup script :file:`setup.py`, and your module :file:`foo.py`.
 The archive file will be named :file:`foo-1.0.tar.gz` (or :file:`.zip`), and
 will unpack into a directory :file:`foo-1.0`.
diff --git a/Doc/documenting/markup.rst b/Doc/documenting/markup.rst
index 57d9eeb..c005d0c 100644
--- a/Doc/documenting/markup.rst
+++ b/Doc/documenting/markup.rst
@@ -98,11 +98,12 @@ following example shows all of the features of this directive type::
 
        Spam or ham the foo.
 
-The signatures of object methods or data attributes should always include the
-type name (``.. method:: FileInput.input(...)``), even if it is obvious from the
-context which type they belong to; this is to enable consistent
-cross-references.  If you describe methods belonging to an abstract protocol,
-such as "context managers", include a (pseudo-)type name too to make the
+The signatures of object methods or data attributes should not include the
+class name, but be nested in a class directive.  The generated files will
+reflect this nesting, and the target identifiers (for HTML output) will use
+both the class and method name, to enable consistent cross-references.  If you
+describe methods belonging to an abstract protocol such as context managers,
+use a class directive with a (pseudo-)type name too to make the
 index entries more informative.
 
 The directives are:
diff --git a/Doc/install/index.rst b/Doc/install/index.rst
index 31c1d7f..f8d6305 100644
--- a/Doc/install/index.rst
+++ b/Doc/install/index.rst
@@ -96,10 +96,16 @@ in the name of the downloaded archive, e.g. :file:`foo-1.0.tar.gz` or
 directory: :file:`foo-1.0` or :file:`widget-0.9.7`.  Additionally, the
 distribution will contain a setup script :file:`setup.py`, and a file named
 :file:`README.txt` or possibly just :file:`README`, which should explain that
-building and installing the module distribution is a simple matter of running ::
+building and installing the module distribution is a simple matter of running
+one command from a terminal::
 
    python setup.py install
 
+For Windows, this command should be run from a command prompt windows ("DOS
+box")::
+
+   setup.py install
+
 If all these things are true, then you already know how to build and install the
 modules you've just downloaded:  Run the command above. Unless you need to
 install things in a non-standard way or customize the build process, you don't
@@ -113,14 +119,11 @@ Standard Build and Install
 ==========================
 
 As described in section :ref:`inst-new-standard`, building and installing a module
-distribution using the Distutils is usually one simple command::
+distribution using the Distutils is usually one simple command to run from a
+terminal::
 
    python setup.py install
 
-On Unix, you'd run this command from a shell prompt; on Windows, you have to
-open a command prompt window ("DOS box") and do it there; on Mac OS X, you open
-a :command:`Terminal` window to get a shell prompt.
-
 
 .. _inst-platform-variations:
 
diff --git a/Doc/library/builtins.rst b/Doc/library/builtins.rst
index c495728..d4199d2 100644
--- a/Doc/library/builtins.rst
+++ b/Doc/library/builtins.rst
@@ -7,7 +7,9 @@
 
 This module provides direct access to all 'built-in' identifiers of Python; for
 example, ``builtins.open`` is the full name for the built-in function
-:func:`open`.
+:func:`open`.  See :ref:`built-in-funcs` and :ref:`built-in-consts` for
+documentation.
+
 
 This module is not normally accessed explicitly by most applications, but can be
 useful in modules that provide objects with the same name as a built-in value,
diff --git a/Doc/library/constants.rst b/Doc/library/constants.rst
index 51a1c26..fa61f68 100644
--- a/Doc/library/constants.rst
+++ b/Doc/library/constants.rst
@@ -1,3 +1,5 @@
+.. _built-in-consts:
+
 Built-in Constants
 ==================
 
diff --git a/Doc/library/logging.handlers.rst b/Doc/library/logging.handlers.rst
index eda9302..378c071 100644
--- a/Doc/library/logging.handlers.rst
+++ b/Doc/library/logging.handlers.rst
@@ -436,6 +436,21 @@ supports sending logging messages to a remote or local Unix syslog.
       The record is formatted, and then sent to the syslog server. If exception
       information is present, it is *not* sent to the server.
 
+      .. versionchanged:: 3.2.1
+         (See: :issue:`12168`.) In earlier versions, the message sent to the
+         syslog daemons was always terminated with a NUL byte, because early
+         versions of these daemons expected a NUL terminated message - even
+         though it's not in the relevant specification (RF 5424). More recent
+         versions of these daemons don't expect the NUL byte but strip it off
+         if it's there, and even more recent daemons (which adhere more closely
+         to RFC 5424) pass the NUL byte on as part of the message.
+
+         To enable easier handling of syslog messages in the face of all these
+         differing daemon behaviours, the appending of the NUL byte has been
+         made configurable, through the use of a class-level attribute,
+         ``append_nul``. This defaults to ``True`` (preserving the existing
+         behaviour) but can be set to ``False`` on a ``SysLogHandler`` instance
+         in order for that instance to *not* append the NUL terminator.
 
    .. method:: encodePriority(facility, priority)
 
diff --git a/Doc/library/logging.rst b/Doc/library/logging.rst
index 32f762d..20cd57c 100644
--- a/Doc/library/logging.rst
+++ b/Doc/library/logging.rst
@@ -453,6 +453,13 @@ The useful mapping keys in a :class:`LogRecord` are given in the section on
       record. Otherwise, the ISO8601 format is used.  The resulting string is
       returned.
 
+      This function uses a user-configurable function to convert the creation
+      time to a tuple. By default, :func:`time.localtime` is used; to change
+      this for a particular formatter instance, set the ``converter`` attribute
+      to a function with the same signature as :func:`time.localtime` or
+      :func:`time.gmtime`. To change it for all formatters, for example if you
+      want all logging times to be shown in GMT, set the ``converter``
+      attribute in the ``Formatter`` class.
 
    .. method:: formatException(exc_info)
 
@@ -544,6 +551,9 @@ wire).
    :param name:  The name of the logger used to log the event represented by
                  this LogRecord.
    :param level: The numeric level of the logging event (one of DEBUG, INFO etc.)
+                 Note that this is converted to *two* attributes of the LogRecord:
+                 ``levelno`` for the numeric value and ``levelname`` for the
+                 corresponding level name.
    :param pathname: The full pathname of the source file where the logging call
                     was made.
    :param lineno: The line number in the source file where the logging call was
diff --git a/Doc/license.rst b/Doc/license.rst
index a32b7ab..b471828 100644
--- a/Doc/license.rst
+++ b/Doc/license.rst
@@ -845,7 +845,7 @@ expat
 -----
 
 The :mod:`pyexpat` extension is built using an included copy of the expat
-sources unless the build is configured :option:`--with-system-expat`::
+sources unless the build is configured ``--with-system-expat``::
 
   Copyright (c) 1998, 1999, 2000 Thai Open Source Software Center Ltd
                                  and Clark Cooper
@@ -874,7 +874,7 @@ libffi
 ------
 
 The :mod:`_ctypes` extension is built using an included copy of the libffi
-sources unless the build is configured :option:`--with-system-libffi`::
+sources unless the build is configured ``--with-system-libffi``::
 
    Copyright (c) 1996-2008  Red Hat, Inc and others.
 
diff --git a/Doc/tutorial/interpreter.rst b/Doc/tutorial/interpreter.rst
index 8d743de..29afc50 100644
--- a/Doc/tutorial/interpreter.rst
+++ b/Doc/tutorial/interpreter.rst
@@ -169,6 +169,8 @@ also be ``.pyw``, in that case, the console window that normally appears is
 suppressed.
 
 
+.. _tut-source-encoding:
+
 Source Code Encoding
 --------------------
 
diff --git a/Doc/using/cmdline.rst b/Doc/using/cmdline.rst
index d1f47eb..16a753c 100644
--- a/Doc/using/cmdline.rst
+++ b/Doc/using/cmdline.rst
@@ -501,7 +501,7 @@ Debug-mode variables
 ~~~~~~~~~~~~~~~~~~~~
 
 Setting these variables only has an effect in a debug build of Python, that is,
-if Python was configured with the :option:`--with-pydebug` build option.
+if Python was configured with the ``--with-pydebug`` build option.
 
 .. envvar:: PYTHONTHREADDEBUG