Issue #27285: Document the deprecation of the pyvenv script.

As part of the update, the documentation was updated to normalize
around the term "virtual environment" instead of relying too heavily
on "venv" for the same meaning and leading to inconsistent usage of
either.

Thanks to Steve Piercy for the patch.

Doc/using/venv-create.inc

@@ -1,31 +1,39 @@
 Creation of :ref:`virtual environments <venv-def>` is done by executing the
-``pyvenv`` script::
+command ``venv``::
 
-    pyvenv /path/to/new/virtual/environment
+    python3 -m venv /path/to/new/virtual/environment
 
 Running this command creates the target directory (creating any parent
 directories that don't exist already) and places a ``pyvenv.cfg`` file in it
-with a ``home`` key pointing to the Python installation the command was run
-from.  It also creates a ``bin`` (or ``Scripts`` on Windows) subdirectory
+with a ``home`` key pointing to the Python installation from which the command
+was run.  It also creates a ``bin`` (or ``Scripts`` on Windows) subdirectory
 containing a copy of the ``python`` binary (or binaries, in the case of
 Windows).  It also creates an (initially empty) ``lib/pythonX.Y/site-packages``
 subdirectory (on Windows, this is ``Lib\site-packages``).
 
+.. deprecated:: 3.6
+   ``pyvenv`` was the recommended tool for creating virtual environments for
+   Python 3.3 and 3.4, and is `deprecated in Python 3.6
+   <https://docs.python.org/dev/whatsnew/3.6.html#deprecated-features>`_.
+
+.. versionchanged:: 3.5
+   The use of ``venv`` is now recommended for creating virtual environments.
+
 .. seealso::
 
    `Python Packaging User Guide: Creating and using virtual environments
-   <https://packaging.python.org/en/latest/installing/#creating-virtual-environments>`__
+   <https://packaging.python.org/installing/#creating-virtual-environments>`__
 
 .. highlight:: none
 
-On Windows, you may have to invoke the ``pyvenv`` script as follows, if you
-don't have the relevant PATH and PATHEXT settings::
+On Windows, invoke the ``venv`` command as follows::
 
-    c:\Temp>c:\Python35\python c:\Python35\Tools\Scripts\pyvenv.py myenv
+    c:\>c:\Python35\python -m venv c:\path\to\myenv
 
-or equivalently::
+Alternatively, if you configured the ``PATH`` and ``PATHEXT`` variables for
+your :ref:`Python installation <using-on-windows>`::
 
-    c:\Temp>c:\Python35\python -m venv myenv
+    c:\>python -m venv myenv c:\path\to\myenv
 
 The command, if run with ``-h``, will show the available options::
 
@@ -36,25 +44,26 @@ The command, if run with ``-h``, will show the available options::
     Creates virtual Python environments in one or more target directories.
 
     positional arguments:
-      ENV_DIR             A directory to create the environment in.
+      ENV_DIR               A directory to create the environment in.
 
     optional arguments:
-      -h, --help             show this help message and exit
-      --system-site-packages Give the virtual environment access to the system
-                             site-packages dir.
-      --symlinks             Try to use symlinks rather than copies, when symlinks
-                             are not the default for the platform.
-      --copies               Try to use copies rather than symlinks, even when
-                             symlinks are the default for the platform.
-      --clear                Delete the contents of the environment directory if it
-                             already exists, before environment creation.
-      --upgrade              Upgrade the environment directory to use this version
-                             of Python, assuming Python has been upgraded in-place.
-      --without-pip          Skips installing or upgrading pip in the virtual
-                             environment (pip is bootstrapped by default)
+      -h, --help            show this help message and exit
+      --system-site-packages
+                            Give the virtual environment access to the system
+                            site-packages dir.
+      --symlinks            Try to use symlinks rather than copies, when symlinks
+                            are not the default for the platform.
+      --copies              Try to use copies rather than symlinks, even when
+                            symlinks are the default for the platform.
+      --clear               Delete the contents of the environment directory if it
+                            already exists, before environment creation.
+      --upgrade             Upgrade the environment directory to use this version
+                            of Python, assuming Python has been upgraded in-place.
+      --without-pip         Skips installing or upgrading pip in the virtual
+                            environment (pip is bootstrapped by default)
 
-Depending on how the ``venv`` functionality has been invoked, the usage message
-may vary slightly, e.g. referencing ``pyvenv`` rather than ``venv``.
+    Once an environment has been created, you may wish to activate it, e.g. by
+    sourcing an activate script in its bin directory.
 
 .. versionchanged:: 3.4
    Installs pip by default, added the ``--without-pip``  and ``--copies``
@@ -73,12 +82,13 @@ run with the ``--system-site-packages`` option, ``false`` otherwise.
 Unless the ``--without-pip`` option is given, :mod:`ensurepip` will be
 invoked to bootstrap ``pip`` into the virtual environment.
 
-Multiple paths can be given to ``pyvenv``, in which case an identical
-virtualenv will be created, according to the given options, at each
-provided path.
+Multiple paths can be given to ``venv``, in which case an identical virtual
+environment will be created, according to the given options, at each provided
+path.
 
-Once a venv has been created, it can be "activated" using a script in the
-venv's binary directory. The invocation of the script is platform-specific:
+Once a virtual environment has been created, it can be "activated" using a
+script in the virtual environment's binary directory. The invocation of the
+script is platform-specific:
 
 +-------------+-----------------+-----------------------------------------+
 | Platform    | Shell           | Command to activate virtual environment |
@@ -95,16 +105,17 @@ venv's binary directory. The invocation of the script is platform-specific:
 +-------------+-----------------+-----------------------------------------+
 
 You don't specifically *need* to activate an environment; activation just
-prepends the venv's binary directory to your path, so that "python" invokes the
-venv's Python interpreter and you can run installed scripts without having to
-use their full path. However, all scripts installed in a venv should be
-runnable without activating it, and run with the venv's Python automatically.
+prepends the virtual environment's binary directory to your path, so that
+"python" invokes the virtual environment's Python interpreter and you can run
+installed scripts without having to use their full path. However, all scripts
+installed in a virtual environment should be runnable without activating it,
+and run with the virtual environment's Python automatically.
 
-You can deactivate a venv by typing "deactivate" in your shell. The exact
-mechanism is platform-specific: for example, the Bash activation script defines
-a "deactivate" function, whereas on Windows there are separate scripts called
-``deactivate.bat`` and ``Deactivate.ps1`` which are installed when the venv is
-created.
+You can deactivate a virtual environment by typing "deactivate" in your shell.
+The exact mechanism is platform-specific: for example, the Bash activation
+script defines a "deactivate" function, whereas on Windows there are separate
+scripts called ``deactivate.bat`` and ``Deactivate.ps1`` which are installed
+when the virtual environment is created.
 
 .. versionadded:: 3.4
    ``fish`` and ``csh`` activation scripts.