Update Windows installation instructions and related bits.

- Use proper Windows commands, drives, and paths
- Use doscon for Windows console lexer

8 files changed, 54 insertions, 39 deletions

diff --git a/docs/conventions.rst b/docs/conventions.rst
index 43853882c..de041da04 100644
--- a/docs/conventions.rst
+++ b/docs/conventions.rst
@@ -57,23 +57,16 @@ character, e.g.:
 
      $ $VENV/bin/py.test -q
 
-(See :term:`venv` for the meaning of ``$VENV``)
+See :term:`venv` for the meaning of ``$VENV``.
 
-Example blocks representing Windows ``cmd.exe`` commands are prefixed with a
-drive letter and/or a directory name, e.g.:
+Example blocks representing Windows commands are prefixed with a drive letter
+with an optional directory name, e.g.:
 
   .. code-block:: doscon
 
      c:\examples> %VENV%\Scripts\py.test -q
 
-(See :term:`venv` for the meaning of ``%VENV%``)
-
-Sometimes, when it's unknown which directory is current, Windows ``cmd.exe``
-example block commands are prefixed only with a ``>`` character, e.g.:
-
-  .. code-block:: doscon
-
-     > %VENV%\Scripts\py.test -q
+See :term:`venv` for the meaning of ``%VENV%``.
 
 When a command that should be typed on one line is too long to fit on a page,
 the backslash ``\`` is used to indicate that the following printed line should
diff --git a/docs/narr/firstapp.rst b/docs/narr/firstapp.rst
index a8491eabd..ad05976c0 100644
--- a/docs/narr/firstapp.rst
+++ b/docs/narr/firstapp.rst
@@ -27,15 +27,15 @@ installed, an HTTP server is started on TCP port 8080.
 
 On UNIX:
 
-.. code-block:: text
+.. code-block:: bash
 
    $ $VENV/bin/python helloworld.py
 
 On Windows:
 
-.. code-block:: text
+.. code-block:: doscon
 
-   C:\> %VENV%\Scripts\python.exe helloworld.py
+   c:\> %VENV%\Scripts\python helloworld.py
 
 This command will not return and nothing will be printed to the console. When
 port 8080 is visited by a browser on the URL ``/hello/world``, the server will
diff --git a/docs/narr/i18n.rst b/docs/narr/i18n.rst
index 131832aae..3549b53a5 100644
--- a/docs/narr/i18n.rst
+++ b/docs/narr/i18n.rst
@@ -294,7 +294,7 @@ Lingua like so:
 
 .. code-block:: doscon
 
-   C> %VENV%\Scripts\pip install lingua
+   c:\> %VENV%\Scripts\pip install lingua
 
 
 .. index::
diff --git a/docs/narr/install.rst b/docs/narr/install.rst
index 7d96f4074..c59ced2a5 100644
--- a/docs/narr/install.rst
+++ b/docs/narr/install.rst
@@ -92,8 +92,24 @@ If your Windows system doesn't have a Python interpreter, you'll need to
 install it by downloading a Python 3.x-series interpreter executable from
 `python.org's download section <https://www.python.org/downloads/>`_ (the files
 labeled "Windows Installer").  Once you've downloaded it, double click on the
-executable and accept the defaults during the installation process. You may
-also need to download and install the Python for Windows extensions.
+executable, and select appropriate options during the installation process. To
+standardize this documentation, we used the GUI installer and selected the
+following options:
+
+- Screen 1: Install Python 3.x.x (32- or 64-bit)
+    - Check "Install launcher for all users (recommended)"
+    - Check "Add Python 3.x to PATH"
+    - Click "Customize installation"
+- Screen 2: Optional Features
+    - Check all options
+    - Click "Next"
+- Screen 3: Advanced Options
+    - Check all options
+    - Customize install location: "C:\\Python3x", where "x" is the minor
+      version of Python
+    - Click "Next"
+
+You might also need to download and install the Python for Windows extensions.
 
 .. seealso:: See the official Python documentation :ref:`Using Python on
    Windows <python:using-on-windows>` for full details.
@@ -104,14 +120,19 @@ also need to download and install the Python for Windows extensions.
    directions. Make sure you get the proper 32- or 64-bit build and Python
    version.
 
+.. seealso:: `Python launcher for Windows
+   <https://docs.python.org/3/using/windows.html#launcher>`_ provides a command
+   ``py`` that allows users to run any installed version of Python.
+
 .. warning::
 
-   After you install Python on Windows, you may need to add the ``C:\Python3x``
-   directory to your environment's ``Path``, where ``x`` is the minor version
-   of installed Python, in order to make it possible to invoke Python from a
-   command prompt by typing ``python``. To do so, right click ``My Computer``,
-   select ``Properties`` --> ``Advanced Tab`` --> ``Environment Variables`` and
-   add that directory to the end of the ``Path`` environment variable.
+   After you install Python on Windows, you might need to add the
+   ``c:\Python3x`` directory to your environment's ``Path``, where ``x`` is the
+   minor version of installed Python, in order to make it possible to invoke
+   Python from a command prompt by typing ``python``. To do so, right click
+   ``My Computer``, select ``Properties`` --> ``Advanced Tab`` -->
+   ``Environment Variables``, and add that directory to the end of the ``Path``
+   environment variable.
 
    .. seealso:: See `Configuring Python (on Windows)
       <https://docs.python.org/3/using/windows.html#configuring-python>`_ for
@@ -190,7 +211,8 @@ After installing Python as described previously in
 
       c:\> set VENV=c:\env
       # replace "x" with your minor version of Python 3
-      c:\> c:\Python3x\Scripts\python3 -m venv %VENV%
+      c:\> c:\Python3x\python -m venv %VENV%
+      c:\> cd %VENV%
 
    You can either follow the use of the environment variable ``%VENV%``, or
    replace it with the root directory of the virtual environment. If you choose
@@ -204,7 +226,7 @@ After installing Python as described previously in
 
    .. parsed-literal::
 
-      c:\\env> %VENV%\\Scripts\\pip install "pyramid==\ |release|\ "
+      c:\\> %VENV%\\Scripts\\pip install "pyramid==\ |release|\ "
 
 
 What Gets Installed
diff --git a/docs/narr/project.rst b/docs/narr/project.rst
index 1ce12a938..812404b76 100644
--- a/docs/narr/project.rst
+++ b/docs/narr/project.rst
@@ -87,9 +87,9 @@ On UNIX:
 
 Or on Windows:
 
-.. code-block:: text
+.. code-block:: doscon
 
-   > %VENV%\Scripts\pcreate -s starter MyProject
+   c:\> %VENV%\Scripts\pcreate -s starter MyProject
 
 As a result of invoking the ``pcreate`` command, a directory named
 ``MyProject`` is created.  That directory is a :term:`project` directory. The
@@ -161,8 +161,8 @@ Or on Windows:
 
 .. code-block:: doscon
 
-   > cd MyProject
-   > %VENV%\Scripts\pip install -e .
+   c:\> cd MyProject
+   c:\> %VENV%\Scripts\pip install -e .
 
 Elided output from a run of this command on UNIX is shown below:
 
@@ -199,7 +199,7 @@ On Windows:
 
 .. code-block:: doscon
 
-   > %VENV%\Scripts\pip install -e ".[testing]"
+   c:\> %VENV%\Scripts\pip install -e ".[testing]"
 
 Once the testing requirements are installed, then you can run the tests using
 the ``py.test`` command that was just installed in the ``bin`` directory of
@@ -215,7 +215,7 @@ On Windows:
 
 .. code-block:: doscon
 
-   > %VENV%\Scripts\py.test -q
+   c:\> %VENV%\Scripts\py.test -q
 
 Here's sample output from a test run on UNIX:
 
@@ -266,7 +266,7 @@ path to the module on which we want to run tests and coverage.
 Running the Project Application
 -------------------------------
 
-.. seealso:: See also the output of :ref:`pserve --help <pserve_script>`.
+.. seealso:: See also the output of :ref:`pserve --help <pserve_scriptc:\>`.
 
 Once a project is installed for development, you can run the application it
 represents using the ``pserve`` command against the generated configuration
@@ -282,7 +282,7 @@ On Windows:
 
 .. code-block:: text
 
-   > %VENV%\Scripts\pserve development.ini
+   c:\> %VENV%\Scripts\pserve development.ini
 
 Here's sample output from a run of ``pserve`` on UNIX:
 
diff --git a/docs/narr/upgrading.rst b/docs/narr/upgrading.rst
index 21b696775..4e434c3c6 100644
--- a/docs/narr/upgrading.rst
+++ b/docs/narr/upgrading.rst
@@ -205,10 +205,10 @@ On UNIX, you can do that via:
 
 On Windows, you need to issue two commands:
 
-.. code-block:: bash
+.. code-block:: doscon
 
-   C:\> set PYTHONWARNINGS=default
-   C:\> Scripts/pserve.exe development.ini
+   c:\> set PYTHONWARNINGS=default
+   c:\> Scripts/pserve.exe development.ini
 
 At this point, it's ensured that deprecation warnings will be printed to the
 console whenever a codepath is hit that generates one.  You can then click
diff --git a/docs/quick_tour.rst b/docs/quick_tour.rst
index dde91b495..fb957be1c 100644
--- a/docs/quick_tour.rst
+++ b/docs/quick_tour.rst
@@ -44,9 +44,9 @@ For Windows:
 .. parsed-literal::
 
     # set an environment variable to where you want your virtual environment
-    c:\> set VENV=c:\env
+    c:\\> set VENV=c:\\env
     # create the virtual environment
-    c:\\> c:\\Python35\\python3 -m venv %VENV%
+    c:\\> %VENV%\\Scripts\\python -m venv %VENV%
     # install pyramid
     c:\\> %VENV%\\Scripts\\pip install pyramid
     # or for a specific released version
diff --git a/docs/quick_tutorial/requirements.rst b/docs/quick_tutorial/requirements.rst
index 62dd570fc..958347a90 100644
--- a/docs/quick_tutorial/requirements.rst
+++ b/docs/quick_tutorial/requirements.rst
@@ -156,7 +156,7 @@ environment variable.
 .. code-block:: doscon
 
     # Windows
-    c:\> c:\Python35\python3 -m venv %VENV%
+    c:\> c:\Python35\python -m venv %VENV%
 
 .. seealso:: See also Python 3's :mod:`venv module <python:venv>` and Python
    2's `virtualenv <https://virtualenv.pypa.io/en/latest/>`_ package.