Correct grammar, use shorter sentences, rewrap to one sentence per line, inline links, update outputs.

1 files changed, 93 insertions, 86 deletions

diff --git a/docs/tutorials/wiki/installation.rst b/docs/tutorials/wiki/installation.rst
index d0037e584..b89822e83 100644
--- a/docs/tutorials/wiki/installation.rst
+++ b/docs/tutorials/wiki/installation.rst
@@ -4,12 +4,13 @@
 Installation
 ============
 
+
 Before you begin
 ----------------
 
-This tutorial assumes that you have already followed the steps in
-:ref:`installing_chapter`, except **do not create a virtual environment or
-install Pyramid**.  Thereby you will satisfy the following requirements.
+This tutorial assumes that you have already followed the steps in :ref:`installing_chapter`, except **do not create a virtual environment or
+install Pyramid**.
+Thereby you will satisfy the following requirements.
 
 * A Python interpreter is installed on your operating system.
 * You've satisfied the :ref:`requirements-for-installing-packages`.
@@ -17,13 +18,17 @@ install Pyramid**.  Thereby you will satisfy the following requirements.
 
 Install cookiecutter
 --------------------
-We will use a :term:`cookiecutter` to create a Python package project from a Python package project template.  See `Cookiecutter Installation <https://cookiecutter.readthedocs.io/en/latest/installation.html>`_ for instructions.
+We will use a :term:`cookiecutter` to create a Python package project from a Python package project template.
+See `Cookiecutter Installation <https://cookiecutter.readthedocs.io/en/latest/installation.html>`_ for instructions.
 
 
 Generate a Pyramid project from a cookiecutter
 ----------------------------------------------
 
-We will create a Pyramid project in your home directory for Unix or at the root for Windows. It is assumed you know the path to where you installed ``cookiecutter``. Issue the following commands and override the defaults in the prompts as follows.
+We will create a Pyramid project in your home directory for Unix or at the root for Windows.
+It is assumed you know the path to where you installed ``cookiecutter``.
+Issue the following commands and override the defaults in the prompts as follows.
+
 
 On Unix
 ^^^^^^^
@@ -33,6 +38,7 @@ On Unix
     cd ~
     cookiecutter gh:Pylons/pyramid-cookiecutter-starter --checkout master
 
+
 On Windows
 ^^^^^^^^^^
 
@@ -41,30 +47,33 @@ On Windows
     cd \
     cookiecutter gh:Pylons/pyramid-cookiecutter-starter --checkout master
 
+
 On all operating systems
 ^^^^^^^^^^^^^^^^^^^^^^^^
 If prompted for the first item, accept the default ``yes`` by hitting return.
 
 .. code-block:: text
 
-    You've cloned ~/.cookiecutters/pyramid-cookiecutter-theone before.
-    Is it okay to delete and re-clone it? [yes]: yes
+    You've downloaded ~/.cookiecutters/pyramid-cookiecutter-starter before.
+    Is it okay to delete and re-download it? [yes]: yes
     project_name [Pyramid Scaffold]: myproj
     repo_name [myproj]: tutorial
     Select template_language:
     1 - jinja2
     2 - chameleon
     3 - mako
-    Choose from 1, 2, 3 [1]: 1
+    Choose from 1, 2, 3 [1]: 2
     Select backend:
     1 - none
     2 - sqlalchemy
     3 - zodb
     Choose from 1, 2, 3 [1]: 3
 
+
 Change directory into your newly created project
 ------------------------------------------------
 
+
 On Unix
 ^^^^^^^
 
@@ -72,6 +81,7 @@ On Unix
 
     cd tutorial
 
+
 On Windows
 ^^^^^^^^^^
 
@@ -85,6 +95,7 @@ Set and use a ``VENV`` environment variable
 
 We will set the ``VENV`` environment variable to the absolute path of the virtual environment, and use it going forward.
 
+
 On Unix
 ^^^^^^^
 
@@ -92,6 +103,7 @@ On Unix
 
     export VENV=~/tutorial
 
+
 On Windows
 ^^^^^^^^^^
 
@@ -103,6 +115,7 @@ On Windows
 Create a virtual environment
 ----------------------------
 
+
 On Unix
 ^^^^^^^
 
@@ -110,17 +123,10 @@ On Unix
 
     python3 -m venv $VENV
 
+
 On Windows
 ^^^^^^^^^^
 
-Each version of Python uses different paths, so you might need to adjust the path to the command for your Python version. Recent versions of the Python 3 installer for Windows now install a Python launcher.
-
-Python 2.7:
-
-.. code-block:: doscon
-
-    c:\Python27\Scripts\virtualenv %VENV%
-
 Python 3.7:
 
 .. code-block:: doscon
@@ -131,6 +137,7 @@ Python 3.7:
 Upgrade packaging tools in the virtual environment
 --------------------------------------------------
 
+
 On Unix
 ^^^^^^^
 
@@ -138,6 +145,7 @@ On Unix
 
     $VENV/bin/pip install --upgrade pip setuptools
 
+
 On Windows
 ^^^^^^^^^^
 
@@ -151,7 +159,10 @@ On Windows
 Installing the project in development mode
 ------------------------------------------
 
-In order to do development on the project easily, you must "register" the project as a development egg in your workspace. We will install testing requirements at the same time. We do so with the following command.
+In order to work on the project, you must "register" the project as a development egg in your workspace.
+We will install testing requirements at the same time.
+We do so with the following command.
+
 
 On Unix
 ^^^^^^^
@@ -160,6 +171,7 @@ On Unix
 
     $VENV/bin/pip install -e ".[testing]"
 
+
 On Windows
 ^^^^^^^^^^
 
@@ -167,6 +179,7 @@ On Windows
 
     %VENV%\Scripts\pip install -e ".[testing]"
 
+
 On all operating systems
 ^^^^^^^^^^^^^^^^^^^^^^^^
 
@@ -174,16 +187,18 @@ The console will show ``pip`` checking for packages and installing missing packa
 
 .. code-block:: bash
 
-    Successfully installed BTrees-4.3.1 Chameleon-3.0 Mako-1.0.6 \
-    MarkupSafe-0.23 PasteDeploy-1.5.2 Pygments-2.1.3 WebOb-1.6.3 \
-    WebTest-2.0.23 ZConfig-3.1.0 ZEO-5.0.4 ZODB-5.1.1 ZODB3-3.11.0 \
-    beautifulsoup4-4.5.1 coverage-4.2 mock-2.0.0 pbr-1.10.0 persistent-4.2.2 \
-    py-1.4.31 pyramid-1.7.3 pyramid-chameleon-0.3 pyramid-debugtoolbar-3.0.5 \
-    pyramid-mako-1.0.2 pyramid-tm-1.1.1 pyramid-zodbconn-0.7 pytest-3.0.5 \
-    pytest-cov-2.4.0 repoze.lru-0.6 six-1.10.0 transaction-2.0.3 \
-    translationstring-1.3 tutorial venusian-1.0 waitress-1.0.1 \
-    zc.lockfile-1.2.1 zdaemon-4.2.0 zodbpickle-0.6.0 zodburi-2.0 \
-    zope.deprecation-4.2.0 zope.interface-4.3.3
+    Successfully installed BTrees-4.5.1 Chameleon-3.5 Mako-1.0.7 \
+    MarkupSafe-1.1.0 PasteDeploy-1.5.2 Pygments-2.2.0 WebTest-2.0.32 \
+    ZConfig-3.3.0 ZEO-5.2.0 ZODB-5.5.1 ZODB3-3.11.0 atomicwrites-1.2.1 \
+    attrs-18.2.0 beautifulsoup4-4.6.3 coverage-4.5.2 hupper-1.4.1 \
+    more-itertools-4.3.0 persistent-4.4.3 plaster-1.0 plaster-pastedeploy-0.6 \
+    pluggy-0.8.0 py-1.7.0 pyramid-1.10.1 pyramid-chameleon-0.3 \
+    pyramid-debugtoolbar-4.5 pyramid-mako-1.0.2 pyramid-retry-1.0 \
+    pyramid-tm-2.2.1 pyramid-zodbconn-0.8.1 pytest-4.0.0 pytest-cov-2.6.0 \
+    repoze.lru-0.7 six-1.11.0 transaction-2.4.0 translationstring-1.3 \
+    tutorial venusian-1.1.0 waitress-1.1.0 webob-1.8.4 zc.lockfile-1.4 \
+    zdaemon-4.3 zodbpickle-1.0.2 zodburi-2.3.0 zope.deprecation-4.3.0 \
+    zope.interface-4.6.0
 
 Testing requirements are defined in our project's ``setup.py`` file, in the ``tests_require`` and ``extras_require`` stanzas.
 
@@ -208,6 +223,7 @@ requirements, you may run the tests for the project. The following commands
 provide options to ``pytest`` that specify the module for which its tests shall be
 run, and to run ``pytest`` in quiet mode.
 
+
 On Unix
 ^^^^^^^
 
@@ -215,6 +231,7 @@ On Unix
 
     $VENV/bin/pytest -q
 
+
 On Windows
 ^^^^^^^^^^
 
@@ -233,13 +250,11 @@ For a successful test run, you should see output that ends like this:
 Expose test coverage information
 --------------------------------
 
-You can run the ``pytest`` command to see test coverage information. This
-runs the tests in the same way that ``pytest`` does, but provides additional
-:term:`coverage` information, exposing which lines of your project are covered by the
-tests.
+You can run the ``pytest`` command to see test coverage information.
+This runs the tests in the same way that ``pytest`` does, but provides additional :term:`coverage` information, exposing which lines of your project are covered by the tests.
+
+We've already installed the ``pytest-cov`` package into our virtual environment, so we can run the tests with coverage.
 
-We've already installed the ``pytest-cov`` package into our virtual
-environment, so we can run the tests with coverage.
 
 On Unix
 ^^^^^^^
@@ -248,6 +263,7 @@ On Unix
 
     $VENV/bin/pytest --cov --cov-report=term-missing
 
+
 On Windows
 ^^^^^^^^^^
 
@@ -259,23 +275,30 @@ If successful, you will see output something like this:
 
 .. code-block:: bash
 
-    ======================== test session starts ========================
-    platform Python 3.6.0, pytest-3.0.5, py-1.4.31, pluggy-0.4.0
-    rootdir: /Users/stevepiercy/tutorial, inifile:
-    plugins: cov-2.4.0
-    collected 1 items
+    ======================== test session starts =========================
+    platform darwin -- Python 3.7.0, pytest-4.0.0, py-1.7.0, pluggy-0.8.0
+    rootdir: /Users/stevepiercy/projects/hack-on-pyramid/tutorial, inifile: pytest.ini
+    plugins: cov-2.6.0
+    collected 1 item
 
     tutorial/tests.py .
-    ------------------ coverage: platform Python 3.6.0 ------------------
-    Name                   Stmts   Miss  Cover   Missing
-    -------------------------------------------------------
-    tutorial/__init__.py      14      9    36%   7-8, 14-20
-    tutorial/models.py        10      6    40%   9-14
-    tutorial/views.py          4      0   100%
-    -------------------------------------------------------
-    TOTAL                     28     15    46%
+                                                                    [100%]
+
+    ---------- coverage: platform darwin, python 3.7.0-final-0 -----------
+    Name                          Stmts   Miss  Cover   Missing
+    -----------------------------------------------------------
+    tutorial/__init__.py             17     12    29%   7-8, 14-23
+    tutorial/models/__init__.py       8      4    50%   9-12
+    tutorial/pshell.py                6      6     0%   1-12
+    tutorial/routes.py                2      2     0%   1-2
+    tutorial/views/__init__.py        0      0   100%
+    tutorial/views/default.py         4      0   100%
+    tutorial/views/notfound.py        4      4     0%   1-7
+    -----------------------------------------------------------
+    TOTAL                            41     28    32%
+
 
-    ===================== 1 passed in 0.31 seconds ======================
+    ===================== 1 passed in 0.31 seconds =======================
 
 Our package doesn't quite have 100% test coverage.
 
@@ -285,11 +308,10 @@ Our package doesn't quite have 100% test coverage.
 Test and coverage cookiecutter defaults
 ---------------------------------------
 
-The Pyramid cookiecutter includes configuration defaults for ``pytest`` and
-test coverage.  These configuration files are ``pytest.ini`` and
-``.coveragerc``, located at the root of your package. Without these defaults,
-we would need to specify the path to the module on which we want to run tests
-and coverage.
+The Pyramid cookiecutter includes configuration defaults for ``pytest`` and test coverage.
+These configuration files are ``pytest.ini`` and ``.coveragerc``, located at the root of your package.
+Without these defaults, we would need to specify the path to the module on which we want to run tests and coverage.
+
 
 On Unix
 ^^^^^^^
@@ -305,13 +327,11 @@ On Windows
 
     %VENV%\Scripts\pytest --cov=tutorial tutorial\tests.py -q
 
-``pytest`` follows :ref:`conventions for Python test discovery
-<pytest:test discovery>`, and the configuration defaults from the cookiecutter
-tell ``pytest`` where to find the module on which we want to run tests and
-coverage.
 
-.. seealso:: See ``pytest``'s documentation for :ref:`pytest:usage` or invoke
-   ``pytest -h`` to see its full set of options.
+``pytest`` follows :ref:`conventions for Python test discovery <pytest:test discovery>`.
+The configuration defaults from the cookiecutter tell ``pytest`` where to find the module on which we want to run tests and coverage.
+
+.. seealso:: See ``pytest``'s documentation for :ref:`pytest:usage` or invoke ``pytest -h`` to see its full set of options.
 
 
 .. _wiki-start-the-application:
@@ -319,8 +339,9 @@ coverage.
 Start the application
 ---------------------
 
-Start the application. See :ref:`what_is_this_pserve_thing` for more
-information on ``pserve``.
+Start the application.
+See :ref:`what_is_this_pserve_thing` for more information on ``pserve``.
+
 
 On Unix
 ^^^^^^^
@@ -329,6 +350,7 @@ On Unix
 
     $VENV/bin/pserve development.ini --reload
 
+
 On Windows
 ^^^^^^^^^^
 
@@ -336,10 +358,10 @@ On Windows
 
     %VENV%\Scripts\pserve development.ini --reload
 
+
 .. note::
 
-   Your OS firewall, if any, may pop up a dialog asking for authorization
-   to allow python to accept incoming network connections.
+   Your OS firewall, if any, may pop up a dialog asking for authorization to allow python to accept incoming network connections.
 
 If successful, you will see something like this on your console:
 
@@ -356,13 +378,12 @@ This means the server is ready to accept requests.
 Visit the application in a browser
 ----------------------------------
 
-In a browser, visit http://localhost:6543/. You will see the generated
-application's default page.
+In a browser, visit http://localhost:6543/.
+You will see the generated application's default page.
 
-One thing you'll notice is the "debug toolbar" icon on right hand side of the
-page.  You can read more about the purpose of the icon at
-:ref:`debug_toolbar`.  It allows you to get information about your
-application while you develop.
+One thing you'll notice is the "debug toolbar" icon on right hand side of the page.
+You can read more about the purpose of the icon at :ref:`debug_toolbar`.
+It allows you to get information about your application while you develop.
 
 
 Decisions the cookiecutter backend option ``zodb`` has made for you
@@ -374,24 +395,10 @@ When creating a project and selecting the backend option of ``zodb``, the cookie
 
 - You are willing to use :term:`traversal` to map URLs to code.
 
-- You want to use pyramid_zodbconn_, pyramid_tm_, and the transaction_ packages
-  to manage connections and transactions with :term:`ZODB`.
+- You want to use `pyramid_zodbconn <https://docs.pylonsproject.org/projects/pyramid-zodbconn/en/latest/>`_, `pyramid_tm <https://docs.pylonsproject.org/projects/pyramid-tm/en/latest/>`_, and the `transaction <https://zodb.readthedocs.io/en/latest/transactions.html>`_ packages to manage connections and transactions with :term:`ZODB`.
 
 .. note::
 
-   :app:`Pyramid` supports any persistent storage mechanism (e.g., an SQL
-   database or filesystem files). It also supports an additional mechanism to
-   map URLs to code (:term:`URL dispatch`). However, for the purposes of this
-   tutorial, we'll only be using :term:`traversal` and :term:`ZODB`.
-
-.. _pyramid_chameleon:
-   https://docs.pylonsproject.org/projects/pyramid-chameleon/en/latest/
-
-.. _pyramid_tm:
-   https://docs.pylonsproject.org/projects/pyramid-tm/en/latest/
-
-.. _pyramid_zodbconn:
-   https://docs.pylonsproject.org/projects/pyramid-zodbconn/en/latest/
-
-.. _transaction:
-   https://zodb.readthedocs.io/en/latest/transactions.html
+    :app:`Pyramid` supports any persistent storage mechanism (e.g., an SQL database or filesystem files).
+    It also supports an additional mechanism to map URLs to code (:term:`URL dispatch`).
+    However, for the purposes of this tutorial, we will only use :term:`traversal` and :term:`ZODB`.