Merge branch 'master' of github.com:Pylons/pyramid

36 files changed, 351 insertions, 260 deletions

diff --git a/docs/tutorials/bfg/index.rst b/docs/tutorials/bfg/index.rst
index e68e63b0b..a50637279 100644
--- a/docs/tutorials/bfg/index.rst
+++ b/docs/tutorials/bfg/index.rst
@@ -47,7 +47,7 @@ Here's how to convert a :mod:`repoze.bfg` application to a
 
    .. code-block:: bash
 
-     $ bfgenv/bin/python setup.py test
+     $ $VENV/bin/python setup.py test
 
    ``bfgenv`` above will be the virtualenv into which you've installed
    :mod:`repoze.bfg` 1.3.
@@ -62,7 +62,7 @@ Here's how to convert a :mod:`repoze.bfg` application to a
       $ cd ~
       $ virtualenv --no-site-packages pyramidenv
       $ cd pyramidenv
-      $ bin/easy_install pyramid
+      $ $VENV/bin/easy_install pyramid
 
 #. Put a *copy* of your :mod:`repoze.bfg` application into a temporary
    location (perhaps by checking a fresh copy of the application out
@@ -186,7 +186,7 @@ Here's how to convert a :mod:`repoze.bfg` application to a
    .. code-block:: bash
 
      $ cd /tmp/bfgapp
-     $ ~/pyramidenv/bin/python setup.py test
+     $ $VENV/bin/python setup.py test
 
 #. Fix any test failures.
 
diff --git a/docs/tutorials/modwsgi/index.rst b/docs/tutorials/modwsgi/index.rst
index a22f12610..e0021f8db 100644
--- a/docs/tutorials/modwsgi/index.rst
+++ b/docs/tutorials/modwsgi/index.rst
@@ -53,7 +53,7 @@ specific path information for commands and files.
     .. code-block:: text
 
        $ cd ~/modwsgi/env
-       $ bin/easy_install pyramid
+       $ $VENV/bin/easy_install pyramid
     
 #.  Create and install your :app:`Pyramid` application.  For the purposes of
     this tutorial, we'll just be using the ``pyramid_starter`` application as
@@ -63,9 +63,9 @@ specific path information for commands and files.
     .. code-block:: text
 
        $ cd ~/modwsgi/env
-       $ bin/pcreate -s starter myapp
+       $ $VENV/bin/pcreate -s starter myapp
        $ cd myapp
-       $ ../bin/python setup.py install
+       $ $VENV/bin/python setup.py install
 
 #.  Within the virtualenv directory (``~/modwsgi/env``), create a
     script named ``pyramid.wsgi``.  Give it these contents:
diff --git a/docs/tutorials/wiki/NOTE-relocatable.txt b/docs/tutorials/wiki/NOTE-relocatable.txt
index cec2639f3..e942caba8 100644
--- a/docs/tutorials/wiki/NOTE-relocatable.txt
+++ b/docs/tutorials/wiki/NOTE-relocatable.txt
@@ -1,5 +1,5 @@
 We specifically use relative package references where possible so this demo
-works even if the user names their package (in the 'bin/paster create -t
+works even if the user names their package (in the '$VENV/bin/pcreate -s
 zodb ...' step) something other than 'tutorial'.
 
 Specifically:
diff --git a/docs/tutorials/wiki/authorization.rst b/docs/tutorials/wiki/authorization.rst
index e90dfe12d..460a852e0 100644
--- a/docs/tutorials/wiki/authorization.rst
+++ b/docs/tutorials/wiki/authorization.rst
@@ -32,9 +32,6 @@ Then we will add the login and logout feature:
 * Add a "Logout" link to be shown when logged in and viewing or editing a page
   (``view.pt``, ``edit.pt``).
 
-The source code for this tutorial stage can be browsed at
-`http://github.com/Pylons/pyramid/tree/1.3-branch/docs/tutorials/wiki/src/authorization/
-<http://github.com/Pylons/pyramid/tree/1.3-branch/docs/tutorials/wiki/src/authorization/>`_.
 
 Access Control
 --------------
@@ -58,8 +55,8 @@ returns one of these values:
 - If the userid *does not* exist in the system, it will
   return ``None``.
 
-For example, ``groupfinder('editor', request )`` returns ['group:editor'],
-``groupfinder('viewer', request)`` returns [], and ``groupfinder('admin', request)``
+For example, ``groupfinder('editor', request )`` returns ``['group:editor']``,
+``groupfinder('viewer', request)`` returns ``[]``, and ``groupfinder('admin', request)``
 returns ``None``.  We will use ``groupfinder()`` as an :term:`authentication policy`
 "callback" that will provide the :term:`principal` or principals
 for a user.
@@ -88,7 +85,7 @@ Add the following lines to the ``Wiki`` class:
    :language: python
 
 We import :data:`~pyramid.security.Allow`, an action that
-means that permission is allowed:, and
+means that permission is allowed, and
 :data:`~pyramid.security.Everyone`, a special :term:`principal`
 that is associated to all requests.  Both are used in the
 :term:`ACE` entries that make up the ACL.
@@ -96,8 +93,8 @@ that is associated to all requests.  Both are used in the
 The ACL is a list that needs to be named `__acl__` and be an
 attribute of a class.  We define an :term:`ACL` with two
 :term:`ACE` entries: the first entry allows any user the `view`
-permission.  The second entry allows the ``group:editors``
-principal  the `edit` permission.
+permission, and the second entry allows the ``group:editors``
+principal the `edit` permission.
 
 The ``Wiki`` class that contains the ACL is the :term:`resource`
 constructor for the :term:`root` resource, which is
@@ -107,7 +104,7 @@ the ``context`` attribute.
 
 It's only happenstance that we're assigning this ACL at class scope.  An ACL
 can be attached to an object *instance* too; this is how "row level security"
-can be achieved in :app:`Pyramid` applications.  We actually only need *one*
+can be achieved in :app:`Pyramid` applications.  We actually need only *one*
 ACL for the entire system, however, because our security requirements are
 simple, so this feature is not demonstrated.  See
 :ref:`assigning_acls` for more information about what an
@@ -147,18 +144,20 @@ machinery represented by this policy: it is required.  The ``callback`` is the
 
 Add permission declarations
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-Add a ``permission='edit'`` parameter to the ``@view_config``
-decorator for ``add_page()`` and ``edit_page()``, for example:
+Open ``tutorial/tutorial/views.py``.  Add a ``permission='edit'`` parameter
+to the ``@view_config`` decorator for ``add_page()`` and
+``edit_page()``, for example:
 
 .. code-block:: python
    :linenos:
-   :emphasize-lines: 2
+   :emphasize-lines: 3
 
-   @view_config(route_name='add_page', renderer='templates/edit.pt',
-                permission='edit')
+    @view_config(name='add_page', context='.models.Wiki',
+                 renderer='templates/edit.pt',
+                 permission='edit')
 
-(Only the highlighted line needs to be added.)
+(Only the highlighted line, along with its preceding comma,
+needs to be added.)
 
 The result is that only users who possess the ``edit``
 permission at the time of the request may invoke those two views.
@@ -170,10 +169,11 @@ decorator for ``view_wiki()`` and ``view_page()``, like this:
    :linenos:
    :emphasize-lines: 2
 
-   @view_config(route_name='view_page', renderer='templates/view.pt',
+   @view_config(context='.models.Page', renderer='templates/view.pt',
                 permission='view')
 
-(Only the highlighted line needs to be added.)
+(Only the highlighted line, along with its preceding comma,
+needs to be added.)
 
 This allows anyone to invoke these two views.
 
@@ -202,7 +202,8 @@ head of ``tutorial/tutorial/views.py``:
    :emphasize-lines: 3,6-9,11
    :language: python
 
-(Only the highlighted lines need to be added.)
+(Only the highlighted lines, with other necessary modifications,
+need to be added.)
 
 :meth:`~pyramid.view.forbidden_view_config` will be used
 to customize the default 403 Forbidden page.
@@ -217,16 +218,16 @@ Now add the ``login`` and ``logout`` views:
    :linenos:
    :language: python
 
-``login()`` is decorated with two decorators:
+``login()`` has two decorators:
 
 - a ``@view_config`` decorator which associates it with the
   ``login`` route and makes it visible when we visit ``/login``,
 - a ``@forbidden_view_config`` decorator which turns it into
-  an :term:`forbidden view`. ``login()`` will be invoked
-  when a users tries to execute a view callable that
-  they are not allowed to.  For example, if a user has not logged in
-  and tries to add or edit a Wiki page, he will be shown the
-  login form before being allowed to continue on.
+  a :term:`forbidden view`. ``login()`` will be invoked
+  when a user tries to execute a view callable for which they lack
+  authorization.  For example, if a user has not logged in
+  and tries to add or edit a Wiki page, they will be shown the
+  login form before being allowed to continue.
 
 The order of these two :term:`view configuration` decorators
 is unimportant.
@@ -244,8 +245,8 @@ content:
 .. literalinclude:: src/authorization/tutorial/templates/login.pt
    :language: xml
 
-The above template is referred to within the login view we just
-added to ``views.py``.
+The above template is referred in the login view that we just added
+in ``views.py``.
 
 Return a logged_in flag to the renderer
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -259,7 +260,8 @@ Add the following line to the import at the head of
    :emphasize-lines: 4
    :language: python
 
-(Only the highlighted line needs to be added.)
+(Only the highlighted line and a trailing comma on the preceding
+line need to be added.)
 
 Add a  ``logged_in`` parameter to the return value of
 ``view_page()``, ``edit_page()`` and  ``add_page()``,
@@ -274,11 +276,12 @@ like this:
                edit_url = edit_url,
                logged_in = authenticated_userid(request))
 
-(Only the highlighted line needs to be added.)
+(Only the highlighted line and a trailing comma on the preceding
+line need to be added.)
 
-:meth:`~pyramid.security.authenticated_userid()` will return None
-if the user is not authenticated, or some user id it the user
-is authenticated.
+:meth:`~pyramid.security.authenticated_userid()` will return ``None``
+if the user is not authenticated, or a user id if the user is
+authenticated.
 
 Add a "Logout" link when logged in
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
diff --git a/docs/tutorials/wiki/background.rst b/docs/tutorials/wiki/background.rst
index ac337abd5..6bbd5026e 100644
--- a/docs/tutorials/wiki/background.rst
+++ b/docs/tutorials/wiki/background.rst
@@ -11,7 +11,7 @@ Python web framework experience.
 
 To code along with this tutorial, the developer will need a UNIX
 machine with development tools (Mac OS X with XCode, any Linux or BSD
-variant, etc) *or* a Windows system of any kind.
+variant, etc.) *or* a Windows system of any kind.
 
 .. warning::
 
diff --git a/docs/tutorials/wiki/basiclayout.rst b/docs/tutorials/wiki/basiclayout.rst
index da381ad7b..f9d4775ad 100644
--- a/docs/tutorials/wiki/basiclayout.rst
+++ b/docs/tutorials/wiki/basiclayout.rst
@@ -4,19 +4,16 @@ Basic Layout
 
 The starter files generated by the ``zodb`` scaffold are basic, but
 they provide a good orientation for the high-level patterns common to most
-:term:`traversal` -based :app:`Pyramid` (and :term:`ZODB` based) projects.
+:term:`traversal` -based :app:`Pyramid` (and :term:`ZODB` -based) projects.
 
-The source code for this tutorial stage can be browsed via
-`http://github.com/Pylons/pyramid/tree/1.3-branch/docs/tutorials/wiki/src/basiclayout/
-<http://github.com/Pylons/pyramid/tree/1.3-branch/docs/tutorials/wiki/src/basiclayout/>`_.
 
 Application Configuration with ``__init__.py``
 ------------------------------------------------
 
 A directory on disk can be turned into a Python :term:`package` by containing
 an ``__init__.py`` file.  Even if empty, this marks a directory as a Python
-package.  Our application uses ``__init__.py`` as both a package marker, as
-well as to contain application configuration code.
+package.  Our application uses ``__init__.py`` both as a package marker and
+to contain application configuration code.
 
 When you run the application using the ``pserve`` command using the
 ``development.ini`` generated config file, the application configuration
@@ -31,14 +28,14 @@ point happens to be the ``main`` function within the file named
 
 #. *Lines 1-3*.  Perform some dependency imports.
 
-#. *Lines 6-8*  Define a root factory for our Pyramid application.
+#. *Lines 6-8*.  Define a root factory for our Pyramid application.
 
 #. *Line 14*.  We construct a :term:`Configurator` with a :term:`root
    factory` and the settings keywords parsed by :term:`PasteDeploy`.  The root
    factory is named ``root_factory``.
 
-#. *Line 15*.  Register a 'static view' which answers requests which start
-   with URL path ``/static`` using the
+#. *Line 15*.  Register a "static view" which answers requests whose URL path
+   start with ``/static`` using the
    :meth:`pyramid.config.Configurator.add_static_view method`.  This
    statement registers a view that will serve up static assets, such as CSS
    and image files, for us, in this case, at
@@ -47,16 +44,16 @@ point happens to be the ``main`` function within the file named
    will be ``/static``.  The second argument of this tag is the "path",
    which is a relative :term:`asset specification`, so it finds the resources
    it should serve within the ``static`` directory inside the ``tutorial``
-   package.  The scaffold could have alternately used an *absolute* asset
-   specification as the path (``tutorial:static``) but it does not.
+   package.  Alternatively the scaffold could have used an *absolute* asset
+   specification as the path (``tutorial:static``).
 
 #. *Line 16*.  Perform a :term:`scan`.  A scan will find :term:`configuration
-   decoration`, such as view configuration decorators (e.g. ``@view_config``)
+   decoration`, such as view configuration decorators (e.g., ``@view_config``)
    in the source code of the ``tutorial`` package and will take actions based
    on these decorators.  We don't pass any arguments to
    :meth:`~pyramid.config.Configurator.scan`, which implies that the scan
    should take place in the current package (in this case, ``tutorial``).
-   The scaffold could have equivalently said ``config.scan('tutorial')`` but
+   The scaffold could have equivalently said ``config.scan('tutorial')``, but
    it chose to omit the package name argument.
 
 #. *Line 17*.  Use the
@@ -73,7 +70,7 @@ tree represents the site structure, but it *also* represents the
 :term:`domain model` of the application, because each resource is a node
 stored persistently in a :term:`ZODB` database.  The ``models.py`` file is
 where the ``zodb`` scaffold put the classes that implement our
-resource objects, each of which happens also to be a domain model object.
+resource objects, each of which also happens to be a domain model object.
 
 Here is the source for ``models.py``:
 
@@ -82,7 +79,7 @@ Here is the source for ``models.py``:
       :language: py
 
 #. *Lines 4-5*.  The ``MyModel`` :term:`resource` class is implemented here.
-   Instances of this class will be capable of being persisted in :term:`ZODB`
+   Instances of this class are capable of being persisted in :term:`ZODB`
    because the class inherits from the
    :class:`persistent.mapping.PersistentMapping` class.  The ``__parent__``
    and ``__name__`` are important parts of the :term:`traversal` protocol.
@@ -140,7 +137,7 @@ Let's try to understand the components in this module:
    indeed if you look in the ``templates`` directory of this package, you'll
    see a ``mytemplate.pt`` template file, which renders the default home page
    of the generated project.  This asset specification is *relative* (to the
-   view.py's current package).  We could have alternately an used the
+   view.py's current package).  Alternatively we could have used the
    absolute asset specification ``tutorial:templates/mytemplate.pt``, but
    chose to use the relative version.
 
@@ -168,7 +165,7 @@ opposed to the tutorial :term:`package` directory) looks like this:
 .. literalinclude:: src/basiclayout/development.ini
    :language: ini
 
-Note the existence of an ``[app:main]`` section which specifies our WSGI
+Note the existence of a ``[app:main]`` section which specifies our WSGI
 application.  Our ZODB database settings are specified as the
 ``zodbconn.uri`` setting within this section.  This value, and the other
 values within this section are passed as ``**settings`` to the ``main``
diff --git a/docs/tutorials/wiki/definingmodels.rst b/docs/tutorials/wiki/definingmodels.rst
index 2cbe691fa..49372179f 100644
--- a/docs/tutorials/wiki/definingmodels.rst
+++ b/docs/tutorials/wiki/definingmodels.rst
@@ -14,9 +14,6 @@ constructors". Both our Page and Wiki constructors will be class objects.  A
 single instance of the "Wiki" class will serve as a container for "Page"
 objects, which will be instances of the "Page" class.
 
-The source code for this tutorial stage can be browsed via
-`http://github.com/Pylons/pyramid/tree/1.3-branch/docs/tutorials/wiki/src/models/
-<http://github.com/Pylons/pyramid/tree/1.3-branch/docs/tutorials/wiki/src/models/>`_.
 
 Delete the Database
 -------------------
@@ -36,7 +33,7 @@ Edit ``models.py``
 .. note::
 
   There is nothing automagically special about the filename ``models.py``.  A
-  project may have many models throughout its codebase in arbitrarily-named
+  project may have many models throughout its codebase in arbitrarily named
   files.  Files implementing models often have ``model`` in their filenames,
   or they may live in a Python subpackage of your application package named
   ``models``, but this is only by convention.
@@ -59,7 +56,7 @@ of the root model is also always ``None``.
 Then we'll add a ``Page`` class.  This class should inherit from the
 :class:`persistent.Persistent` class.  We'll also give it an ``__init__``
 method that accepts a single parameter named ``data``.  This parameter will
-contain the :term:`ReStructuredText` body representing the wiki page content.
+contain the :term:`reStructuredText` body representing the wiki page content.
 Note that ``Page`` objects don't have an initial ``__name__`` or
 ``__parent__`` attribute.  All objects in a traversal graph must have a
 ``__name__`` and a ``__parent__`` attribute.  We don't specify these here
diff --git a/docs/tutorials/wiki/definingviews.rst b/docs/tutorials/wiki/definingviews.rst
index 27f55da13..23ee142af 100644
--- a/docs/tutorials/wiki/definingviews.rst
+++ b/docs/tutorials/wiki/definingviews.rst
@@ -28,9 +28,6 @@ assumed to return a :term:`response` object.
 We're going to define several :term:`view callable` functions, then wire them
 into :app:`Pyramid` using some :term:`view configuration`.
 
-The source code for this tutorial stage can be browsed via
-`http://github.com/Pylons/pyramid/tree/1.3-branch/docs/tutorials/wiki/src/views/
-<http://github.com/Pylons/pyramid/tree/1.3-branch/docs/tutorials/wiki/src/views/>`_.
 
 Declaring Dependencies in Our ``setup.py`` File
 ===============================================
@@ -74,6 +71,13 @@ and a final view named ``edit_page`` will allow a page to be edited.
 The ``view_wiki`` view function
 -------------------------------
 
+Here is the code for the ``view_wiki`` view function and its decorator, which
+will be added to ``views.py``:
+
+.. literalinclude:: src/views/tutorial/views.py
+   :lines: 12-14
+   :language: python
+
 The ``view_wiki`` function will be configured to respond as the default view
 callable for a Wiki resource.  We'll provide it with a ``@view_config``
 decorator which names the class ``tutorial.models.Wiki`` as its context.
@@ -87,16 +91,22 @@ The ``view_wiki`` view callable always redirects to the URL of a Page
 resource named "FrontPage".  To do so, it returns an instance of the
 :class:`pyramid.httpexceptions.HTTPFound` class (instances of which implement
 the :class:`pyramid.interfaces.IResponse` interface like
-:class:`pyramid.response.Response` does).  The
-:meth:`pyramid.request.Request.resource_url` API.
+:class:`pyramid.response.Response` does).
 :meth:`pyramid.request.Request.resource_url` constructs a URL to the
-``FrontPage`` page resource (e.g. ``http://localhost:6543/FrontPage``), and
+``FrontPage`` page resource (i.e., ``http://localhost:6543/FrontPage``), and
 uses it as the "location" of the HTTPFound response, forming an HTTP
 redirect.
 
 The ``view_page`` view function
 -------------------------------
 
+Here is the code for the ``view_page`` view function and its decorator, which
+will be added to ``views.py``:
+
+.. literalinclude:: src/views/tutorial/views.py
+   :lines: 16-33
+   :language: python
+
 The ``view_page`` function will be configured to respond as the default view
 of a Page resource.  We'll provide it with a ``@view_config`` decorator which
 names the class ``tutorial.models.Page`` as its context.  This means that
@@ -104,7 +114,7 @@ when a Page resource is the context, and no :term:`view name` exists in the
 request, this view will be used.  We inform :app:`Pyramid` this view will use
 the ``templates/view.pt`` template file as a ``renderer``.
 
-The ``view_page`` function generates the :term:`ReStructuredText` body of a
+The ``view_page`` function generates the :term:`reStructuredText` body of a
 page (stored as the ``data`` attribute of the context passed to the view; the
 context will be a Page resource) as HTML.  Then it substitutes an HTML anchor
 for each *WikiWord* reference in the rendered HTML using a compiled regular
@@ -143,6 +153,13 @@ callable.  In the ``view_wiki`` view callable, we unconditionally return a
 The ``add_page`` view function
 ------------------------------
 
+Here is the code for the ``add_page`` view function and its decorator, which
+will be added to ``views.py``:
+
+.. literalinclude:: src/views/tutorial/views.py
+   :lines: 35-50
+   :language: python
+
 The ``add_page`` function will be configured to respond when the context
 resource is a Wiki and the :term:`view name` is ``add_page``.  We'll provide
 it with a ``@view_config`` decorator which names the string ``add_page`` as
@@ -174,7 +191,7 @@ we're trying to add.
 If the view rendering is *not* a result of a form submission (if the
 expression ``'form.submitted' in request.params`` is ``False``), the view
 renders a template.  To do so, it generates a "save url" which the template
-use as the form post URL during rendering.  We're lazy here, so we're trying
+uses as the form post URL during rendering.  We're lazy here, so we're trying
 to use the same template (``templates/edit.pt``) for the add view as well as
 the page edit view.  To do so, we create a dummy Page resource object in
 order to satisfy the edit form's desire to have *some* page object exposed as
@@ -190,6 +207,13 @@ the page body, and save it into "our context" (the Wiki) using the
 The ``edit_page`` view function
 -------------------------------
 
+Here is the code for the ``edit_page`` view function and its decorator, which
+will be added to ``views.py``:
+
+.. literalinclude:: src/views/tutorial/views.py
+   :lines: 52-60
+   :language: python
+
 The ``edit_page`` function will be configured to respond when the context is
 a Page resource and the :term:`view name` is ``edit_page``.  We'll provide it
 with a ``@view_config`` decorator which names the string ``edit_page`` as its
@@ -293,7 +317,7 @@ Our templates name a single static asset named ``pylons.css``.  We don't need
 to create this file within our package's ``static`` directory because it was
 provided at the time we created the project. This file is a little too long to
 replicate within the body of this guide, however it is available `online
-<http://github.com/Pylons/pyramid/blob/master/docs/tutorials/wiki/src/views/tutorial/static/pylons.css>`_.
+<https://github.com/Pylons/pyramid/blob/master/docs/tutorials/wiki/src/views/tutorial/static/pylons.css>`_.
 
 This CSS file will be accessed via
 e.g. ``/static/pylons.css`` by virtue of the call to
diff --git a/docs/tutorials/wiki/design.rst b/docs/tutorials/wiki/design.rst
index b44ccb10e..eb785dd1c 100644
--- a/docs/tutorials/wiki/design.rst
+++ b/docs/tutorials/wiki/design.rst
@@ -4,7 +4,7 @@ Design
 
 Following is a quick overview of our wiki application, to help
 us understand the changes that we will be doing next in our
-default files generated by the ``zodb`` scafffold.
+default files generated by the ``zodb`` scaffold.
 
 Overall
 -------
@@ -37,8 +37,8 @@ Views
 -----
 
 There will be three views to handle the normal operations of adding,
-editing and viewing wiki pages, plus one view for the wiki front page.
-Two templates will be used, one for viewing, and one for both for adding
+editing, and viewing wiki pages, plus one view for the wiki front page.
+Two templates will be used, one for viewing, and one for both adding
 and editing wiki pages.
 
 The default templating systems in :app:`Pyramid` are
@@ -57,7 +57,7 @@ use to do this are below.
   corresponding passwords.
 
 - GROUPS, a dictionary mapping usernames to a
-  list of groups they belong to.
+  list of groups to which they belong to.
 
 - ``groupfinder``, an *authorization callback* that looks up
   USERS and GROUPS.  It will be provided in a new
diff --git a/docs/tutorials/wiki/distributing.rst b/docs/tutorials/wiki/distributing.rst
index ed0af222f..9c63cf0bd 100644
--- a/docs/tutorials/wiki/distributing.rst
+++ b/docs/tutorials/wiki/distributing.rst
@@ -12,13 +12,13 @@ On UNIX:
 
 .. code-block:: text
 
-   $ ../bin/python setup.py sdist
+   $ $VENV/bin/python setup.py sdist
 
 On Windows:
 
 .. code-block:: text
 
-   c:\pyramidtut> ..\Scripts\python setup.py sdist
+   c:\pyramidtut> %VENV%\Scripts\python setup.py sdist
 
 The output of such a command will be something like:
 
diff --git a/docs/tutorials/wiki/index.rst b/docs/tutorials/wiki/index.rst
index c918f8765..981d135c7 100644
--- a/docs/tutorials/wiki/index.rst
+++ b/docs/tutorials/wiki/index.rst
@@ -10,8 +10,9 @@ tutorial, the developer will have created a basic Wiki application with
 authentication.
 
 For cut and paste purposes, the source code for all stages of this
-tutorial can be browsed at `https://github.com/Pylons/pyramid/tree/1.3-branch/docs/tutorials/wiki/src
-<https://github.com/Pylons/pyramid/tree/1.3-branch/docs/tutorials/wiki/src>`_.
+tutorial can be browsed on GitHub at `docs/tutorials/wiki/src
+<https://github.com/Pylons/pyramid/tree/master/docs/tutorials/wiki/src>`_,
+which corresponds to the same location if you have Pyramid sources.
 
 .. toctree::
    :maxdepth: 2
diff --git a/docs/tutorials/wiki/installation.rst b/docs/tutorials/wiki/installation.rst
index 488ab1883..b51254b92 100644
--- a/docs/tutorials/wiki/installation.rst
+++ b/docs/tutorials/wiki/installation.rst
@@ -22,7 +22,7 @@ Preparation, UNIX
 
    .. code-block:: text
 
-     $ bin/easy_install docutils pyramid_tm pyramid_zodbconn \
+     $ $VENV/bin/easy_install docutils pyramid_tm pyramid_zodbconn \
                pyramid_debugtoolbar nose coverage
 
 Preparation, Windows
@@ -39,7 +39,7 @@ Preparation, Windows
 
    .. code-block:: text
 
-     c:\pyramidtut> Scripts\easy_install docutils pyramid_tm \
+     c:\pyramidtut> %VENV%\Scripts\easy_install docutils pyramid_tm \
            pyramid_zodbconn pyramid_debugtoolbar nose coverage
 
 .. _making_a_project:
@@ -59,13 +59,13 @@ On UNIX:
 
 .. code-block:: text
 
-  $ bin/pcreate -s zodb tutorial
+  $ $VENV/bin/pcreate -s zodb tutorial
 
 On Windows:
 
 .. code-block:: text
 
-   c:\pyramidtut> Scripts\pcreate -s zodb tutorial
+   c:\pyramidtut> %VENV%\Scripts\pcreate -s zodb tutorial
 
 .. note:: You don't have to call it `tutorial` -- the code uses
    relative paths for imports and finding templates and static
@@ -91,14 +91,14 @@ On UNIX:
 .. code-block:: text
 
   $ cd tutorial
-  $ ../bin/python setup.py develop
+  $ $VENV/bin/python setup.py develop
 
 On Windows:
 
 .. code-block:: text
 
   C:\pyramidtut> cd tutorial
-  C:\pyramidtut\tutorial> ..\Scripts\python setup.py develop
+  C:\pyramidtut\tutorial> %VENV%\Scripts\python setup.py develop
 
 .. _running_tests:
 
@@ -112,13 +112,13 @@ On UNIX:
 
 .. code-block:: text
 
-  $ ../bin/python setup.py test -q
+  $ $VENV/bin/python setup.py test -q
 
 On Windows:
 
 .. code-block:: text
 
-  c:\pyramidtut\tutorial> ..\Scripts\python setup.py test -q
+  c:\pyramidtut\tutorial> %VENV%\Scripts\python setup.py test -q
 
 Expose Test Coverage Information
 ================================
@@ -133,13 +133,13 @@ On UNIX:
 
 .. code-block:: text
 
-  $ ../bin/nosetests --cover-package=tutorial --cover-erase --with-coverage
+  $ $VENV/bin/nosetests --cover-package=tutorial --cover-erase --with-coverage
 
 On Windows:
 
 .. code-block:: text
 
-  c:\pyramidtut\tutorial> ..\Scripts\nosetests --cover-package=tutorial ^
+  c:\pyramidtut\tutorial> %VENV%\Scripts\nosetests --cover-package=tutorial ^
        --cover-erase --with-coverage
 
 Looks like the code in the ``zodb`` scaffold for ZODB projects is
@@ -157,13 +157,13 @@ On UNIX:
 
 .. code-block:: text
 
-  $ ../bin/pserve development.ini --reload
+  $ $VENV/bin/pserve development.ini --reload
 
 On Windows:
 
 .. code-block:: text
 
-  c:\pyramidtut\tutorial> ..\Scripts\pserve development.ini --reload
+  c:\pyramidtut\tutorial> %VENV%\Scripts\pserve development.ini --reload
 
 .. note::
 
@@ -193,8 +193,7 @@ assumptions:
 
 .. note::
 
-   :app:`Pyramid` supports any persistent storage mechanism (e.g. a SQL
-   database or filesystem files, etc).  :app:`Pyramid` 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 traversal and ZODB.
-
+   :app:`Pyramid` supports any persistent storage mechanism (e.g., a SQL
+   database or filesystem files).  :app:`Pyramid` 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 traversal and ZODB.
diff --git a/docs/tutorials/wiki/src/authorization/setup.py b/docs/tutorials/wiki/src/authorization/setup.py
index 3164fd724..5d87fedbf 100644
--- a/docs/tutorials/wiki/src/authorization/setup.py
+++ b/docs/tutorials/wiki/src/authorization/setup.py
@@ -3,8 +3,10 @@ import os
 from setuptools import setup, find_packages
 
 here = os.path.abspath(os.path.dirname(__file__))
-README = open(os.path.join(here, 'README.txt')).read()
-CHANGES = open(os.path.join(here, 'CHANGES.txt')).read()
+with open(os.path.join(here, 'README.txt')) as f:
+    README = f.read()
+with open(os.path.join(here, 'CHANGES.txt')) as f:
+    CHANGES = f.read()
 
 requires = [
     'pyramid',
diff --git a/docs/tutorials/wiki/src/basiclayout/setup.py b/docs/tutorials/wiki/src/basiclayout/setup.py
index 4998be902..75ba02611 100644
--- a/docs/tutorials/wiki/src/basiclayout/setup.py
+++ b/docs/tutorials/wiki/src/basiclayout/setup.py
@@ -3,8 +3,10 @@ import os
 from setuptools import setup, find_packages
 
 here = os.path.abspath(os.path.dirname(__file__))
-README = open(os.path.join(here, 'README.txt')).read()
-CHANGES = open(os.path.join(here, 'CHANGES.txt')).read()
+with open(os.path.join(here, 'README.txt')) as f:
+    README = f.read()
+with open(os.path.join(here, 'CHANGES.txt')) as f:
+    CHANGES = f.read()
 
 requires = [
     'pyramid',
diff --git a/docs/tutorials/wiki/src/models/setup.py b/docs/tutorials/wiki/src/models/setup.py
index 4998be902..75ba02611 100644
--- a/docs/tutorials/wiki/src/models/setup.py
+++ b/docs/tutorials/wiki/src/models/setup.py
@@ -3,8 +3,10 @@ import os
 from setuptools import setup, find_packages
 
 here = os.path.abspath(os.path.dirname(__file__))
-README = open(os.path.join(here, 'README.txt')).read()
-CHANGES = open(os.path.join(here, 'CHANGES.txt')).read()
+with open(os.path.join(here, 'README.txt')) as f:
+    README = f.read()
+with open(os.path.join(here, 'CHANGES.txt')) as f:
+    CHANGES = f.read()
 
 requires = [
     'pyramid',
diff --git a/docs/tutorials/wiki/src/tests/setup.py b/docs/tutorials/wiki/src/tests/setup.py
index 702d34c4c..5ff7b545c 100644
--- a/docs/tutorials/wiki/src/tests/setup.py
+++ b/docs/tutorials/wiki/src/tests/setup.py
@@ -3,8 +3,10 @@ import os
 from setuptools import setup, find_packages
 
 here = os.path.abspath(os.path.dirname(__file__))
-README = open(os.path.join(here, 'README.txt')).read()
-CHANGES = open(os.path.join(here, 'CHANGES.txt')).read()
+with open(os.path.join(here, 'README.txt')) as f:
+    README = f.read()
+with open(os.path.join(here, 'CHANGES.txt')) as f:
+    CHANGES = f.read()
 
 requires = [
     'pyramid',
diff --git a/docs/tutorials/wiki/src/views/setup.py b/docs/tutorials/wiki/src/views/setup.py
index 3164fd724..5d87fedbf 100644
--- a/docs/tutorials/wiki/src/views/setup.py
+++ b/docs/tutorials/wiki/src/views/setup.py
@@ -3,8 +3,10 @@ import os
 from setuptools import setup, find_packages
 
 here = os.path.abspath(os.path.dirname(__file__))
-README = open(os.path.join(here, 'README.txt')).read()
-CHANGES = open(os.path.join(here, 'CHANGES.txt')).read()
+with open(os.path.join(here, 'README.txt')) as f:
+    README = f.read()
+with open(os.path.join(here, 'CHANGES.txt')) as f:
+    CHANGES = f.read()
 
 requires = [
     'pyramid',
diff --git a/docs/tutorials/wiki/tests.rst b/docs/tutorials/wiki/tests.rst
index 7a019dd04..e40dc286b 100644
--- a/docs/tutorials/wiki/tests.rst
+++ b/docs/tutorials/wiki/tests.rst
@@ -6,9 +6,6 @@ We will now add tests for the models and the views and a few functional
 tests in the ``tests.py``.  Tests ensure that an application works, and
 that it continues to work after some changes are made in the future.
 
-The source code for this tutorial stage can be browsed via
-`http://github.com/Pylons/pyramid/tree/1.3-branch/docs/tutorials/wiki/src/tests/
-<http://github.com/Pylons/pyramid/tree/1.3-branch/docs/tutorials/wiki/src/tests/>`_.
 
 Test the Models
 ===============
@@ -62,7 +59,7 @@ Change the ``requires`` list in ``setup.py`` to include ``WebTest``.
 .. literalinclude:: src/tests/setup.py
    :linenos:
    :language: python
-   :lines: 9-19
+   :lines: 11-21
    :emphasize-lines: 10
 
 After we've added a dependency on WebTest in ``setup.py``, we need to rerun
@@ -74,13 +71,13 @@ On UNIX:
 
 .. code-block:: text
 
-   $ ../bin/python setup.py develop
+   $ $VENV/bin/python setup.py develop
 
 On Windows:
 
 .. code-block:: text
 
-   c:\pyramidtut\tutorial> ..\Scripts\python setup.py develop
+   c:\pyramidtut\tutorial> %VENV%\Scripts\python setup.py develop
 
 Once that command has completed successfully, we can run the tests
 themselves:
@@ -89,13 +86,13 @@ On UNIX:
 
 .. code-block:: text
 
-   $ ../bin/python setup.py test -q
+   $ $VENV/bin/python setup.py test -q
 
 On Windows:
 
 .. code-block:: text
 
-   c:\pyramidtut\tutorial> ..\Scripts\python setup.py test -q
+   c:\pyramidtut\tutorial> %VENV%\Scripts\python setup.py test -q
 
 The expected result looks something like:
 
diff --git a/docs/tutorials/wiki2/authorization.rst b/docs/tutorials/wiki2/authorization.rst
index 321f1f9c4..5ede26920 100644
--- a/docs/tutorials/wiki2/authorization.rst
+++ b/docs/tutorials/wiki2/authorization.rst
@@ -36,9 +36,6 @@ Then we will add the login and logout feature:
 * Add a "Logout" link to be shown when logged in and viewing or editing a page
   (``view.pt``, ``edit.pt``).
 
-The source code for this tutorial stage can be browsed at
-`http://github.com/Pylons/pyramid/tree/1.3-branch/docs/tutorials/wiki2/src/authorization/
-<http://github.com/Pylons/pyramid/tree/1.3-branch/docs/tutorials/wiki2/src/authorization/>`_.
 
 Access Control
 --------------
diff --git a/docs/tutorials/wiki2/basiclayout.rst b/docs/tutorials/wiki2/basiclayout.rst
index e8874784c..6d6287126 100644
--- a/docs/tutorials/wiki2/basiclayout.rst
+++ b/docs/tutorials/wiki2/basiclayout.rst
@@ -6,9 +6,6 @@ The starter files generated by the ``alchemy`` scaffold are very basic, but
 they provide a good orientation for the high-level patterns common to most
 :term:`url dispatch` -based :app:`Pyramid` projects.
 
-The source code for this tutorial stage can be browsed at
-`http://github.com/Pylons/pyramid/tree/1.3-branch/docs/tutorials/wiki2/src/basiclayout/
-<http://github.com/Pylons/pyramid/tree/1.3-branch/docs/tutorials/wiki2/src/basiclayout/>`_.
 
 Application Configuration with ``__init__.py``
 ----------------------------------------------
@@ -46,9 +43,9 @@ above is executed.  It accepts some settings and returns a :term:`WSGI`
 application.  (See :ref:`startup_chapter` for more about ``pserve``.)
 
 The main function first creates a :term:`SQLAlchemy` database engine using
-``engine_from_config`` from the ``sqlalchemy.`` prefixed settings in the
-``development.ini`` file's ``[app:main]`` section.  This will be a URI
-(something like ``sqlite://``):
+:func:`sqlalchemy.engine_from_config` from the ``sqlalchemy.`` prefixed
+settings in the ``development.ini`` file's ``[app:main]`` section.
+This will be a URI (something like ``sqlite://``):
 
    .. literalinclude:: src/basiclayout/tutorial/__init__.py
       :lines: 13
@@ -135,11 +132,11 @@ Finally, ``main`` is finished configuring things, so it uses the
 View Declarations via ``views.py``
 ----------------------------------
 
-Mapping a :term:`route` to code that will be executed when a match for
-the route's pattern occurs is done by registering a :term:`view
-configuration`. Our application uses the
-:meth:`pyramid.view.view_config` decorator to map view callables to
-each route, thereby mapping URL patterns to code.
+Arguably, the main function of a web framework is mapping each URL
+patterns, see :term:`route`, to code, see :term:`view callable`, that is 
+executed when the requested URL matches the corresponding :term:`route`. Our 
+application uses the :meth:`pyramid.view.view_config` decorator to perform 
+this mapping.
 
 Open ``tutorial/tutorial/views.py``.  It should already contain the following:
 
@@ -229,13 +226,12 @@ To give a simple example of a  model class, we define one named ``MyModel``:
       :linenos:
       :language: py
 
-Our example model has an ``__init__`` method that takes a two arguments
+Our example model has an ``__init__`` method that takes two arguments
 (``name``, and ``value``).  It stores these values as ``self.name`` and
-``self.value``
-within the ``__init__`` function itself.  The ``MyModel`` class also has a
-``__tablename__`` attribute.  This informs SQLAlchemy which table to use to
-store the data representing instances of this class.
+``self.value`` within the ``__init__`` function itself.  The ``MyModel`` class 
+also has a ``__tablename__`` attribute.  This informs SQLAlchemy which table 
+to use to store the data representing instances of this class.
 
-That's about all there is to it to models, views, and initialization code in
+That's about all there is to it with models, views, and initialization code in
 our stock application.
 
diff --git a/docs/tutorials/wiki2/definingmodels.rst b/docs/tutorials/wiki2/definingmodels.rst
index dca6238dd..60427a911 100644
--- a/docs/tutorials/wiki2/definingmodels.rst
+++ b/docs/tutorials/wiki2/definingmodels.rst
@@ -6,9 +6,6 @@ The first change we'll make to our stock ``pcreate``-generated application will
 be to define a :term:`domain model` constructor representing a wiki page.
 We'll do this inside our ``models.py`` file.
 
-The source code for this tutorial stage can be browsed at
-`http://github.com/Pylons/pyramid/tree/1.3-branch/docs/tutorials/wiki2/src/models/
-<http://github.com/Pylons/pyramid/tree/1.3-branch/docs/tutorials/wiki2/src/models/>`_.
 
 Making Edits to ``models.py``
 -----------------------------
@@ -37,7 +34,7 @@ sample and we're not going to use it.
 
 Then, we added a ``Page`` class.  Because this is a SQLAlchemy application,
 this class inherits from an instance of
-:class:`sqlalchemy.ext.declarative.declarative_base`.
+:func:`sqlalchemy.ext.declarative.declarative_base`.
 
 .. literalinclude:: src/models/tutorial/models.py
    :pyobject: Page
@@ -48,9 +45,10 @@ As you can see, our ``Page`` class has a class level attribute
 ``__tablename__`` which equals the string ``'pages'``.  This means that
 SQLAlchemy will store our wiki data in a SQL table named ``pages``.  Our
 ``Page`` class will also have class-level attributes named ``id``, ``name`` and
-``data`` (all instances of :class:`sqlalchemy.Column`).  These will map to
-columns in the ``pages`` table.  The ``id`` attribute will be the primary key
-in the table.  The ``name`` attribute will be a text attribute, each value of
+``data`` (all instances of :class:`sqlalchemy.schema.Column`).
+These will map to columns in the ``pages`` table.
+The ``id`` attribute will be the primary key in the table.
+The ``name`` attribute will be a text attribute, each value of
 which needs to be unique within the column.  The ``data`` attribute is a text
 attribute that will hold the body of each page.
 
@@ -80,8 +78,6 @@ following:
 Installing the Project and re-initializing the Database
 -------------------------------------------------------
 
-Redo the steps in :ref:`installing_project_in_dev_mode`.
-
 Because our model has changed, in order to reinitialize the database, we need
 to rerun the ``initialize_tutorial_db`` command to pick up the changes you've made
 to both the models.py file and to the initializedb.py file.
diff --git a/docs/tutorials/wiki2/definingviews.rst b/docs/tutorials/wiki2/definingviews.rst
index 8714927c3..9894bcb08 100644
--- a/docs/tutorials/wiki2/definingviews.rst
+++ b/docs/tutorials/wiki2/definingviews.rst
@@ -6,19 +6,13 @@ A :term:`view callable` in a :app:`Pyramid` application is typically a simple
 Python function that accepts a single parameter named :term:`request`.  A
 view callable is assumed to return a :term:`response` object.
 
-The request object passed to every view that is called as the result of a
-route match has an attribute named ``matchdict`` that contains the elements
-placed into the URL by the ``pattern`` of a ``route`` statement.  For
-instance, if a call to :meth:`pyramid.config.Configurator.add_route` in
-``__init__.py`` had the pattern ``{one}/{two}``, and the URL at
-``http://example.com/foo/bar`` was invoked, matching this pattern, the
-``matchdict`` dictionary attached to the request passed to the view would
-have a ``'one'`` key with the value ``'foo'`` and a ``'two'`` key with the
-value ``'bar'``.
-
-The source code for this tutorial stage can be browsed at
-`http://github.com/Pylons/pyramid/tree/1.3-branch/docs/tutorials/wiki2/src/views/
-<http://github.com/Pylons/pyramid/tree/1.3-branch/docs/tutorials/wiki2/src/views/>`_.
+The request object has a dictionary as an attribute named ``matchdict``. 
+A ``matchdict`` maps the placeholders in the matching URL ``pattern`` to the substrings 
+of the :term:`request` ed URL. For instance, if a call to 
+:meth:`pyramid.config.Configurator.add_route` has the pattern 
+``{one}/{two}``, and a user visits ``http://example.com/foo/bar``, our pattern would be 
+matched and the ``matchdict`` would look like: ``{'one':'foo', 'two':'bar'}``
+
 
 Declaring Dependencies in Our ``setup.py`` File
 ===============================================
@@ -36,7 +30,7 @@ Open ``tutorial/setup.py`` and edit it to look like the following:
 .. literalinclude:: src/views/setup.py
    :linenos:
    :language: python
-   :emphasize-lines: 17
+   :emphasize-lines: 19
 
 (Only the highlighted line needs to be added.)
 
@@ -55,14 +49,14 @@ On UNIX:
 .. code-block:: text
 
    $ cd tutorial
-   $ ../bin/python setup.py develop
+   $ $VENV/bin/python setup.py develop
 
 On Windows:
 
 .. code-block:: text
 
    c:\pyramidtut> cd tutorial
-   c:\pyramidtut\tutorial> ..\Scripts\python setup.py develop
+   c:\pyramidtut\tutorial> %VENV%\Scripts\python setup.py develop
 
 Success executing this command will end with a line to the console something
 like::
@@ -129,7 +123,7 @@ The ``view_page`` view function
 -------------------------------
 
 ``view_page()`` is used to display a single page of our
-wiki.  It renders the :term:`ReStructuredText` body of a page (stored as
+wiki.  It renders the :term:`reStructuredText` body of a page (stored as
 the ``data`` attribute of a ``Page`` model object) as HTML.  Then it substitutes an
 HTML anchor for each *WikiWord* reference in the rendered HTML using a
 compiled regular expression.
@@ -155,10 +149,9 @@ We then generate an edit URL (because it's easier to do here than in the
 template), and we return a dictionary with a number of arguments.  The fact
 that ``view_page()`` returns a dictionary (as opposed to a :term:`response`
 object) is a cue to :app:`Pyramid` that it should try to use a :term:`renderer`
-associated with the view configuration to render a template.  In our case,
-the template which will be rendered will be the ``templates/view.pt``
-template, as indicated in the ``@view_config`` decorator that is applied to
-``view_page()``.
+associated with the view configuration to render a response.  In our case,
+the renderer used will be the ``templates/view.pt`` template, as indicated in 
+the ``@view_config`` decorator that is applied to ``view_page()``.
 
 The ``add_page`` view function
 ------------------------------
@@ -290,7 +283,7 @@ Our templates name a single static asset named ``pylons.css``.  We don't need
 to create this file within our package's ``static`` directory because it was
 provided at the time we created the project. This file is a little too long
 to replicate within the body of this guide, however it is available `online
-<http://github.com/Pylons/pyramid/blob/master/docs/tutorials/wiki2/src/views/tutorial/static/pylons.css>`_.
+<https://github.com/Pylons/pyramid/blob/master/docs/tutorials/wiki2/src/views/tutorial/static/pylons.css>`_.
 
 This CSS file will be accessed via
 e.g. ``http://localhost:6543/static/pylons.css`` by virtue of the call to
diff --git a/docs/tutorials/wiki2/distributing.rst b/docs/tutorials/wiki2/distributing.rst
index 96293603c..3b048a141 100644
--- a/docs/tutorials/wiki2/distributing.rst
+++ b/docs/tutorials/wiki2/distributing.rst
@@ -12,13 +12,13 @@ On UNIX:
 
 .. code-block:: text
 
-   $ ../bin/python setup.py sdist
+   $ $VENV/bin/python setup.py sdist
 
 On Windows:
 
 .. code-block:: text
 
-   c:\pyramidtut> ..\Scripts\python setup.py sdist
+   c:\pyramidtut> %VENV%\Scripts\python setup.py sdist
 
 The output of such a command will be something like:
 
diff --git a/docs/tutorials/wiki2/index.rst b/docs/tutorials/wiki2/index.rst
index bbc2fb96e..0a614cb23 100644
--- a/docs/tutorials/wiki2/index.rst
+++ b/docs/tutorials/wiki2/index.rst
@@ -9,9 +9,9 @@ tutorial is finished, the developer will have created a basic Wiki
 application with authentication.
 
 For cut and paste purposes, the source code for all stages of this
-tutorial can be browsed at
-`https://github.com/Pylons/pyramid/tree/1.3-branch/docs/tutorials/wiki2/src
-<https://github.com/Pylons/pyramid/tree/1.3-branch/docs/tutorials/wiki2/src>`_.
+tutorial can be browsed on GitHub at `docs/tutorials/wiki2/src
+<https://github.com/Pylons/pyramid/tree/master/docs/tutorials/wiki2/src>`_,
+which corresponds to the same location if you have Pyramid sources.
 
 .. toctree::
    :maxdepth: 2
diff --git a/docs/tutorials/wiki2/installation.rst b/docs/tutorials/wiki2/installation.rst
index 9fa01d513..9590e4abe 100644
--- a/docs/tutorials/wiki2/installation.rst
+++ b/docs/tutorials/wiki2/installation.rst
@@ -2,63 +2,138 @@
 Installation
 ============
 
-Preparation
-===========
+Before You Begin
+================
+
+This tutorial assumes that you have already followed the steps in
+:ref:`installing_chapter`, thereby satisfying the following
+requirements.
+
+* Python interpreter is installed on your operating system
+* :term:`setuptools` or :term:`distribute` is installed
+* :term:`virtualenv` is installed
+
+Create and Use a Virtual Python Environment
+-------------------------------------------
+
+Next let's create a `virtualenv` workspace for our project.  We will
+use the `VENV` environment variable instead of absolute path of the
+virtual environment.
+
+**On UNIX:**
+
+.. code-block:: text
+
+   $ export VENV=~/pyramidtut
+   $ virtualenv --no-site-packages $VENV
+   New python executable in /home/foo/env/bin/python
+   Installing setuptools.............done.
+
+**On Windows**:
 
-Follow the steps in :ref:`installing_chapter`, but name the virtualenv
-directory ``pyramidtut``.
+Set the `VENV` environment variable.
 
-Preparation, UNIX
------------------
+.. code-block:: text
+
+   c:\> set VENV=c:\pyramidtut
+
+Versions of Python use different paths, so you will need to adjust the
+path to the command for your Python version.
+
+Python 2.7:
+
+.. code-block:: text
 
-#. Install SQLite3 and its development packages if you don't already
-   have them installed.  Usually this is via your system's package
-   manager.  On a Debian system, this would be:
+   c:\> c:\Python27\Scripts\virtualenv --no-site-packages %VENV%
 
-   .. code-block:: text
+Python 3.2:
 
-      $ sudo apt-get install libsqlite3-dev
+.. code-block:: text
 
-#. Switch to the ``pyramidtut`` directory:
+   c:\> c:\Python32\Scripts\virtualenv --no-site-packages %VENV%
 
-   .. code-block:: text
+Install Pyramid Into the Virtual Python Environment
+---------------------------------------------------
 
-      $ cd pyramidtut
+**On UNIX:**
 
+.. code-block:: text
 
-Preparation, Windows
---------------------
+   $ $VENV/bin/easy_install pyramid
 
-#. Switch to the ``pyramidtut`` directory:
+**On Windows**:
+
+.. code-block:: text
 
-   .. code-block:: text
+   c:\env> %VENV%\Scripts\easy_install pyramid
 
-      c:\> cd pyramidtut
+Install SQLite3 and Its Development Packages
+--------------------------------------------
+
+If you used a package manager to install your Python or if you compiled
+your Python from source, then you must install SQLite3 and its
+development packages.  If you downloaded your Python as an installer
+from python.org, then you already have it installed and can proceed to
+the next section :ref:`sql_making_a_project`..
+
+If you need to install the SQLite3 packages, then, for example, using
+the Debian system and apt-get, the command would be the following:
+
+.. code-block:: text
+
+   $ sudo apt-get install libsqlite3-dev
+
+Change Directory to Your Virtual Python Environment
+---------------------------------------------------
+
+Change directory to the ``pyramidtut`` directory.
+
+**On UNIX**:
+
+.. code-block:: text
+
+   $ cd pyramidtut
+
+**On Windows**:
+
+.. code-block:: text
+
+   c:\> cd pyramidtut
 
 .. _sql_making_a_project:
 
 Making a Project
 ================
 
-Your next step is to create a project.  For this tutorial, we will use the
-:term:`scaffold` named ``alchemy``, which generates an application
-that uses :term:`SQLAlchemy` and :term:`URL dispatch`.  :app:`Pyramid`
-supplies a variety of scaffolds to generate sample projects.
+Your next step is to create a project.  For this tutorial we will use
+the :term:`scaffold` named ``alchemy`` which generates an application
+that uses :term:`SQLAlchemy` and :term:`URL dispatch`.
+
+:app:`Pyramid` supplies a variety of scaffolds to generate sample
+projects. We will use `pcreate`—a script that comes with Pyramid to
+quickly and easily generate scaffolds usually with a single command—to
+create the scaffold for our project.
+
+By passing in `alchemy` into the `pcreate` command, the script creates
+the files needed to use SQLAlchemy. By passing in our application name
+`tutorial`, the script inserts that application name into all the
+required files. For example, `pcreate` creates the
+``initialize_tutorial_db`` in the ``pyramidtut/bin`` directory.
 
 The below instructions assume your current working directory is the
 "virtualenv" named "pyramidtut".
 
-On UNIX:
+**On UNIX**:
 
 .. code-block:: text
 
-   $ bin/pcreate -s alchemy tutorial
+   $ $VENV/bin/pcreate -s alchemy tutorial
 
-On Windows:
+**On Windows**:
 
 .. code-block:: text
 
-   c:\pyramidtut> Scripts\pcreate -s alchemy tutorial
+   c:\pyramidtut> %VENV%\pcreate -s alchemy tutorial
 
 .. note:: If you are using Windows, the ``alchemy``
    scaffold may not deal gracefully with installation into a
@@ -66,11 +141,10 @@ On Windows:
    startup problems, try putting both the virtualenv and the project
    into directories that do not contain spaces in their paths.
 
-
 .. _installing_project_in_dev_mode:
 
-Installing the Project in "Development Mode"
-============================================
+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 using the
@@ -78,22 +152,23 @@ the project as a development egg in your workspace using the
 directory you created in :ref:`sql_making_a_project`, and run the
 ``setup.py develop`` command using the virtualenv Python interpreter.
 
-On UNIX:
+**On UNIX**:
 
 .. code-block:: text
 
    $ cd tutorial
-   $ ../bin/python setup.py develop
+   $ $VENV/bin/python setup.py develop
 
-On Windows:
+**On Windows**:
 
 .. code-block:: text
 
    c:\pyramidtut> cd tutorial
-   c:\pyramidtut\tutorial> ..\Scripts\python setup.py develop
+   c:\pyramidtut\tutorial> %VENV%\Scripts\python setup.py develop
 
-Success executing this command will end with a line to the console something
-like::
+The console will show `setup.py` checking for packages and installing
+missing packages. Success executing this command will show a line like
+the following::
 
    Finished processing dependencies for tutorial==0.0
 
@@ -105,17 +180,17 @@ Running the Tests
 After you've installed the project in development mode, you may run
 the tests for the project.
 
-On UNIX:
+**On UNIX**:
 
 .. code-block:: text
 
-   $ ../bin/python setup.py test -q
+   $ $VENV/bin/python setup.py test -q
 
-On Windows:
+**On Windows**:
 
 .. code-block:: text
 
-   c:\pyramidtut\tutorial> ..\Scripts\python setup.py test -q
+   c:\pyramidtut\tutorial> %VENV%\Scripts\python setup.py test -q
 
 For a successful test run, you should see output that ends like this::
 
@@ -137,32 +212,32 @@ tests.
 To get this functionality working, we'll need to install the ``nose`` and
 ``coverage`` packages into our ``virtualenv``:
 
-On UNIX:
+**On UNIX**:
 
 .. code-block:: text
 
-   $ ../bin/easy_install nose coverage
+   $ $VENV/bin/easy_install nose coverage
 
-On Windows:
+**On Windows**:
 
 .. code-block:: text
 
-   c:\pyramidtut\tutorial> ..\Scripts\easy_install nose coverage
+   c:\pyramidtut\tutorial> %VENV%\Scripts\easy_install nose coverage
 
 Once ``nose`` and ``coverage`` are installed, we can actually run the
 coverage tests.
 
-On UNIX:
+**On UNIX**:
 
 .. code-block:: text
 
-   $ ../bin/nosetests --cover-package=tutorial --cover-erase --with-coverage
+   $ $VENV/bin/nosetests --cover-package=tutorial --cover-erase --with-coverage
 
-On Windows:
+**On Windows**:
 
 .. code-block:: text
 
-   c:\pyramidtut\tutorial> ..\Scripts\nosetests --cover-package=tutorial \
+   c:\pyramidtut\tutorial> %VENV%\Scripts\nosetests --cover-package=tutorial \
          --cover-erase --with-coverage
 
 If successful, you will see output something like this::
@@ -196,17 +271,17 @@ script` to initialize our database.
 Type the following command, make sure you are still in the ``tutorial``
 directory (the directory with a ``development.ini`` in it):
 
-On UNIX:
+**On UNIX**:
 
 .. code-block:: text
 
-   $ ../bin/initialize_tutorial_db development.ini
+   $ $VENV/bin/initialize_tutorial_db development.ini
 
-On Windows:
+**On Windows**:
 
 .. code-block:: text
 
-   c:\pyramidtut\tutorial> ..\Scripts\initialize_tutorial_db development.ini
+   c:\pyramidtut\tutorial> %VENV%\Scripts\initialize_tutorial_db development.ini
 
 The output to your console should be something like this::
 
@@ -244,17 +319,17 @@ Starting the Application
 
 Start the application.
 
-On UNIX:
+**On UNIX**:
 
 .. code-block:: text
 
-   $ ../bin/pserve development.ini --reload
+   $ $VENV/bin/pserve development.ini --reload
 
-On Windows:
+**On Windows**:
 
 .. code-block:: text
 
-   c:\pyramidtut\tutorial> ..\Scripts\pserve development.ini --reload
+   c:\pyramidtut\tutorial> %VENV%\Scripts\pserve development.ini --reload
 
 If successful, you will see something like this on your console::
 
@@ -292,4 +367,3 @@ the following assumptions:
    mechanism to map URLs to code (:term:`traversal`).  However, for the
    purposes of this tutorial, we'll only be using url dispatch and
    SQLAlchemy.
-
diff --git a/docs/tutorials/wiki2/src/authorization/README.txt b/docs/tutorials/wiki2/src/authorization/README.txt
index 141851285..68f430110 100644
--- a/docs/tutorials/wiki2/src/authorization/README.txt
+++ b/docs/tutorials/wiki2/src/authorization/README.txt
@@ -6,9 +6,9 @@ Getting Started
 
 - cd <directory containing this file>
 
-- $venv/bin/python setup.py develop
+- $VENV/bin/python setup.py develop
 
-- $venv/bin/initialize_tutorial_db development.ini
+- $VENV/bin/initialize_tutorial_db development.ini
 
-- $venv/bin/pserve development.ini
+- $VENV/bin/pserve development.ini
 
diff --git a/docs/tutorials/wiki2/src/authorization/setup.py b/docs/tutorials/wiki2/src/authorization/setup.py
index 36668dd33..e8fa8f396 100644
--- a/docs/tutorials/wiki2/src/authorization/setup.py
+++ b/docs/tutorials/wiki2/src/authorization/setup.py
@@ -3,8 +3,10 @@ import os
 from setuptools import setup, find_packages
 
 here = os.path.abspath(os.path.dirname(__file__))
-README = open(os.path.join(here, 'README.txt')).read()
-CHANGES = open(os.path.join(here, 'CHANGES.txt')).read()
+with open(os.path.join(here, 'README.txt')) as f:
+    README = f.read()
+with open(os.path.join(here, 'CHANGES.txt')) as f:
+    CHANGES = f.read()
 
 requires = [
     'pyramid',
diff --git a/docs/tutorials/wiki2/src/basiclayout/README.txt b/docs/tutorials/wiki2/src/basiclayout/README.txt
index 141851285..68f430110 100644
--- a/docs/tutorials/wiki2/src/basiclayout/README.txt
+++ b/docs/tutorials/wiki2/src/basiclayout/README.txt
@@ -6,9 +6,9 @@ Getting Started
 
 - cd <directory containing this file>
 
-- $venv/bin/python setup.py develop
+- $VENV/bin/python setup.py develop
 
-- $venv/bin/initialize_tutorial_db development.ini
+- $VENV/bin/initialize_tutorial_db development.ini
 
-- $venv/bin/pserve development.ini
+- $VENV/bin/pserve development.ini
 
diff --git a/docs/tutorials/wiki2/src/basiclayout/setup.py b/docs/tutorials/wiki2/src/basiclayout/setup.py
index a09bf756a..e7d318128 100644
--- a/docs/tutorials/wiki2/src/basiclayout/setup.py
+++ b/docs/tutorials/wiki2/src/basiclayout/setup.py
@@ -3,8 +3,10 @@ import os
 from setuptools import setup, find_packages
 
 here = os.path.abspath(os.path.dirname(__file__))
-README = open(os.path.join(here, 'README.txt')).read()
-CHANGES = open(os.path.join(here, 'CHANGES.txt')).read()
+with open(os.path.join(here, 'README.txt')) as f:
+    README = f.read()
+with open(os.path.join(here, 'CHANGES.txt')) as f:
+    CHANGES = f.read()
 
 requires = [
     'pyramid',
diff --git a/docs/tutorials/wiki2/src/models/README.txt b/docs/tutorials/wiki2/src/models/README.txt
index 141851285..68f430110 100644
--- a/docs/tutorials/wiki2/src/models/README.txt
+++ b/docs/tutorials/wiki2/src/models/README.txt
@@ -6,9 +6,9 @@ Getting Started
 
 - cd <directory containing this file>
 
-- $venv/bin/python setup.py develop
+- $VENV/bin/python setup.py develop
 
-- $venv/bin/initialize_tutorial_db development.ini
+- $VENV/bin/initialize_tutorial_db development.ini
 
-- $venv/bin/pserve development.ini
+- $VENV/bin/pserve development.ini
 
diff --git a/docs/tutorials/wiki2/src/models/setup.py b/docs/tutorials/wiki2/src/models/setup.py
index a09bf756a..e7d318128 100644
--- a/docs/tutorials/wiki2/src/models/setup.py
+++ b/docs/tutorials/wiki2/src/models/setup.py
@@ -3,8 +3,10 @@ import os
 from setuptools import setup, find_packages
 
 here = os.path.abspath(os.path.dirname(__file__))
-README = open(os.path.join(here, 'README.txt')).read()
-CHANGES = open(os.path.join(here, 'CHANGES.txt')).read()
+with open(os.path.join(here, 'README.txt')) as f:
+    README = f.read()
+with open(os.path.join(here, 'CHANGES.txt')) as f:
+    CHANGES = f.read()
 
 requires = [
     'pyramid',
diff --git a/docs/tutorials/wiki2/src/tests/README.txt b/docs/tutorials/wiki2/src/tests/README.txt
index 141851285..68f430110 100644
--- a/docs/tutorials/wiki2/src/tests/README.txt
+++ b/docs/tutorials/wiki2/src/tests/README.txt
@@ -6,9 +6,9 @@ Getting Started
 
 - cd <directory containing this file>
 
-- $venv/bin/python setup.py develop
+- $VENV/bin/python setup.py develop
 
-- $venv/bin/initialize_tutorial_db development.ini
+- $VENV/bin/initialize_tutorial_db development.ini
 
-- $venv/bin/pserve development.ini
+- $VENV/bin/pserve development.ini
 
diff --git a/docs/tutorials/wiki2/src/tests/setup.py b/docs/tutorials/wiki2/src/tests/setup.py
index 3c2961fcc..c3da36b39 100644
--- a/docs/tutorials/wiki2/src/tests/setup.py
+++ b/docs/tutorials/wiki2/src/tests/setup.py
@@ -3,8 +3,10 @@ import os
 from setuptools import setup, find_packages
 
 here = os.path.abspath(os.path.dirname(__file__))
-README = open(os.path.join(here, 'README.txt')).read()
-CHANGES = open(os.path.join(here, 'CHANGES.txt')).read()
+with open(os.path.join(here, 'README.txt')) as f:
+    README = f.read()
+with open(os.path.join(here, 'CHANGES.txt')) as f:
+    CHANGES = f.read()
 
 requires = [
     'pyramid',
diff --git a/docs/tutorials/wiki2/src/views/README.txt b/docs/tutorials/wiki2/src/views/README.txt
index 141851285..68f430110 100644
--- a/docs/tutorials/wiki2/src/views/README.txt
+++ b/docs/tutorials/wiki2/src/views/README.txt
@@ -6,9 +6,9 @@ Getting Started
 
 - cd <directory containing this file>
 
-- $venv/bin/python setup.py develop
+- $VENV/bin/python setup.py develop
 
-- $venv/bin/initialize_tutorial_db development.ini
+- $VENV/bin/initialize_tutorial_db development.ini
 
-- $venv/bin/pserve development.ini
+- $VENV/bin/pserve development.ini
 
diff --git a/docs/tutorials/wiki2/src/views/setup.py b/docs/tutorials/wiki2/src/views/setup.py
index 36668dd33..e8fa8f396 100644
--- a/docs/tutorials/wiki2/src/views/setup.py
+++ b/docs/tutorials/wiki2/src/views/setup.py
@@ -3,8 +3,10 @@ import os
 from setuptools import setup, find_packages
 
 here = os.path.abspath(os.path.dirname(__file__))
-README = open(os.path.join(here, 'README.txt')).read()
-CHANGES = open(os.path.join(here, 'CHANGES.txt')).read()
+with open(os.path.join(here, 'README.txt')) as f:
+    README = f.read()
+with open(os.path.join(here, 'CHANGES.txt')) as f:
+    CHANGES = f.read()
 
 requires = [
     'pyramid',
diff --git a/docs/tutorials/wiki2/tests.rst b/docs/tutorials/wiki2/tests.rst
index 6a7cbf62d..33b5d35c1 100644
--- a/docs/tutorials/wiki2/tests.rst
+++ b/docs/tutorials/wiki2/tests.rst
@@ -6,9 +6,6 @@ We will now add tests for the models and the views and a few functional
 tests in the ``tests.py``.  Tests ensure that an application works, and
 that it continues to work after changes are made in the future.
 
-The source code for this tutorial stage can be browsed at
-`http://github.com/Pylons/pyramid/tree/1.3-branch/docs/tutorials/wiki2/src/tests/
-<http://github.com/Pylons/pyramid/tree/1.3-branch/docs/tutorials/wiki2/src/tests/>`_.
 
 
 Testing the Models
@@ -57,7 +54,7 @@ Change the ``requires`` list in ``setup.py`` to include ``WebTest``.
 .. literalinclude:: src/tests/setup.py
    :linenos:
    :language: python
-   :lines: 9-20
+   :lines: 11-21
    :emphasize-lines: 10
 
 After we've added a dependency on WebTest in ``setup.py``, we need to rerun
@@ -69,13 +66,13 @@ On UNIX:
 
 .. code-block:: text
 
-   $ ../bin/python setup.py develop
+   $ $VENV/bin/python setup.py develop
 
 On Windows:
 
 .. code-block:: text
 
-   c:\pyramidtut\tutorial> ..\Scripts\python setup.py develop
+   c:\pyramidtut\tutorial> %VENV%\Scripts\python setup.py develop
 
 Once that command has completed successfully, we can run the tests
 themselves:
@@ -84,13 +81,13 @@ On UNIX:
 
 .. code-block:: text
 
-   $ ../bin/python setup.py test -q
+   $ $VENV/bin/python setup.py test -q
 
 On Windows:
 
 .. code-block:: text
 
-   c:\pyramidtut\tutorial> ..\Scripts\python setup.py test -q
+   c:\pyramidtut\tutorial> %VENV%\Scripts\python setup.py test -q
 
 The expected result ends something like: