Merge edits from 3.2 (#13716, #1040439, #2945, #13770, #6715)

8 files changed, 16 insertions, 17 deletions

diff --git a/Doc/library/archiving.rst b/Doc/library/archiving.rst
index b7d400c..c928494 100644
--- a/Doc/library/archiving.rst
+++ b/Doc/library/archiving.rst
@@ -6,7 +6,8 @@ Data Compression and Archiving
 
 The modules described in this chapter support data compression with the zlib,
 gzip, bzip2 and lzma algorithms, and the creation of ZIP- and tar-format
-archives.
+archives.  See also :ref:`archiving-operations` provided by the :mod:`shutil`
+module.
 
 
 .. toctree::
diff --git a/Doc/library/bz2.rst b/Doc/library/bz2.rst
index 7275e12..9577f31 100644
--- a/Doc/library/bz2.rst
+++ b/Doc/library/bz2.rst
@@ -12,9 +12,6 @@
 This module provides a comprehensive interface for compressing and
 decompressing data using the bzip2 compression algorithm.
 
-For related file formats, see the :mod:`gzip`, :mod:`lzma`, :mod:`zipfile`, and
-:mod:`tarfile` modules.
-
 The :mod:`bz2` module contains:
 
 * The :class:`BZ2File` class for reading and writing compressed files.
diff --git a/Doc/library/gzip.rst b/Doc/library/gzip.rst
index 4491acc..82c9522 100644
--- a/Doc/library/gzip.rst
+++ b/Doc/library/gzip.rst
@@ -21,9 +21,6 @@ Note that additional file formats which can be decompressed by the
 :program:`gzip` and :program:`gunzip` programs, such  as those produced by
 :program:`compress` and :program:`pack`, are not supported by this module.
 
-For related file formats, see the :mod:`bz2`, :mod:`lzma`, :mod:`zipfile`, and
-:mod:`tarfile` modules.
-
 The module defines the following items:
 
 
diff --git a/Doc/library/json.rst b/Doc/library/json.rst
index 4ee17f2..a791259 100644
--- a/Doc/library/json.rst
+++ b/Doc/library/json.rst
@@ -125,6 +125,10 @@ Basic Usage
    :class:`bytes` objects. Therefore, ``fp.write()`` must support :class:`str`
    input.
 
+   If *ensure_ascii* is ``True`` (the default), the output is guaranteed to
+   have all incoming non-ASCII characters escaped.  If *ensure_ascii* is
+   ``False``, these characters will be output as-is.
+
    If *check_circular* is ``False`` (default: ``True``), then the circular
    reference check for container types will be skipped and a circular reference
    will result in an :exc:`OverflowError` (or worse).
diff --git a/Doc/library/shutil.rst b/Doc/library/shutil.rst
index 9e8784b..77ce6b0 100644
--- a/Doc/library/shutil.rst
+++ b/Doc/library/shutil.rst
@@ -31,6 +31,8 @@ copying and removal. For operations on individual files, see also the
    are not copied.
 
 
+.. _file-operations:
+
 Directory and files operations
 ------------------------------
 
@@ -234,7 +236,7 @@ Directory and files operations
    (*srcname*, *dstname*, *exception*).
 
 
-.. _shutil-example:
+.. _shutil-copytree-example:
 
 copytree example
 ::::::::::::::::
@@ -301,6 +303,9 @@ Another example that uses the *ignore* argument to add a logging call::
 Archiving operations
 --------------------
 
+High-level utilities to create and read compressed and archived files are also
+provided.  They rely on the :mod:`zipfile` and :mod:`tarfile` modules.
+
 .. function:: make_archive(base_name, format, [root_dir, [base_dir, [verbose, [dry_run, [owner, [group, [logger]]]]]]])
 
    Create an archive file (such as zip or tar) and return its name.
@@ -428,6 +433,7 @@ Archiving operations
    .. versionadded:: 3.2
 
 
+.. _shutil-archiving-example:
 
 Archiving example
 :::::::::::::::::
@@ -453,5 +459,3 @@ The resulting archive contains::
     -rw------- tarek/staff    1675 2008-06-09 13:26:54 ./id_rsa
     -rw-r--r-- tarek/staff     397 2008-06-09 13:26:54 ./id_rsa.pub
     -rw-r--r-- tarek/staff   37192 2010-02-06 18:23:10 ./known_hosts
-
-
diff --git a/Doc/library/tarfile.rst b/Doc/library/tarfile.rst
index 4a9db8e..92e9df7 100644
--- a/Doc/library/tarfile.rst
+++ b/Doc/library/tarfile.rst
@@ -14,7 +14,8 @@
 
 The :mod:`tarfile` module makes it possible to read and write tar
 archives, including those using gzip, bz2 and lzma compression.
-(:file:`.zip` files can be read and written using the :mod:`zipfile` module.)
+Use the :mod:`zipfile` module to read or write :file:`.zip` files, or the
+higher-level functions in :ref:`shutil <archiving-operations>`.
 
 Some facts and figures:
 
diff --git a/Doc/library/zipfile.rst b/Doc/library/zipfile.rst
index c3e13ed..bcec134 100644
--- a/Doc/library/zipfile.rst
+++ b/Doc/library/zipfile.rst
@@ -23,9 +23,6 @@ decryption of encrypted files in ZIP archives, but it currently cannot
 create an encrypted file.  Decryption is extremely slow as it is
 implemented in native Python rather than C.
 
-For related file formats, see the :mod:`bz2`, :mod:`gzip`, :mod:`lzma`, and
-:mod:`tarfile` modules.
-
 The module defines the following items:
 
 .. exception:: BadZipFile
diff --git a/Doc/library/zlib.rst b/Doc/library/zlib.rst
index 7ad3624..1e9a2bc 100644
--- a/Doc/library/zlib.rst
+++ b/Doc/library/zlib.rst
@@ -18,9 +18,7 @@ order.  This documentation doesn't attempt to cover all of the permutations;
 consult the zlib manual at http://www.zlib.net/manual.html for authoritative
 information.
 
-For reading and writing ``.gz`` files see the :mod:`gzip` module. For other
-related file formats, see the :mod:`bz2`, :mod:`lzma`, :mod:`zipfile`, and
-:mod:`tarfile` modules.
+For reading and writing ``.gz`` files see the :mod:`gzip` module.
 
 The available exception and functions in this module are: