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

93 files changed, 714 insertions, 475 deletions

diff --git a/docs/tutorials/wiki/authorization.rst b/docs/tutorials/wiki/authorization.rst
index 24249945a..7c8ba99bf 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
 --------------
@@ -127,7 +124,7 @@ add these import statements:
 Now add those policies to the configuration:
 
 .. literalinclude:: src/authorization/tutorial/__init__.py
-   :lines: 17-22
+   :lines: 18-23
    :linenos:
    :emphasize-lines: 1-3,5-6
    :language: python
@@ -213,7 +210,7 @@ expire an auth ticket cookie.
 Now add the ``login`` and ``logout`` views:
 
 .. literalinclude:: src/authorization/tutorial/views.py
-   :lines: 87-120
+   :lines: 82-120
    :linenos:
    :language: python
 
@@ -306,7 +303,7 @@ when we're done:
 
 .. literalinclude:: src/authorization/tutorial/__init__.py
    :linenos:
-   :emphasize-lines: 4-5,8,17-19,21-22
+   :emphasize-lines: 4-5,8,18-20,22-23
    :language: python
 
 (Only the highlighted lines need to be added.)
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 f6050f391..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,35 +28,35 @@ point happens to be the ``main`` function within the file named
 
 #. *Lines 1-3*.  Perform some dependency imports.
 
-#. *Lines 5-7*  Define a root factory for our Pyramid application.
+#. *Lines 6-8*.  Define a root factory for our Pyramid application.
 
-#. *Line 12*.  We construct a :term:`Configurator` with a :term:`root
+#. *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 13*.  Register a 'static view' which answers requests which start
-   with 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
    ``http://localhost:6543/static/`` and below.  The first argument is the
    "name" ``static``, which indicates that the URL path prefix of the view
-   will be ``/static``.  the The second argument of this tag is the "path",
+   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 14*.  Perform a :term:`scan`.  A scan will find :term:`configuration
-   decoration`, such as view configuration decorators (e.g. ``@view_config``)
+#. *Line 16*.  Perform a :term:`scan`.  A scan will find :term:`configuration
+   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 15*.  Use the
+#. *Line 17*.  Use the
    :meth:`pyramid.config.Configurator.make_wsgi_app` method
    to return a :term:`WSGI` application.
 
@@ -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``:
 
@@ -81,15 +78,15 @@ Here is the source for ``models.py``:
       :linenos:
       :language: py
 
-#. *Lines 3-4*.  The ``MyModel`` :term:`resource` class is implemented here.
-   Instances of this class will be capable of being persisted in :term:`ZODB`
+#. *Lines 4-5*.  The ``MyModel`` :term:`resource` class is implemented here.
+   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.
    By default, have these as ``None`` indicating that this is the
    :term:`root` object.
 
-#. *Lines 6-12*.  ``appmaker`` is used to return the *application
+#. *Lines 8-14*.  ``appmaker`` is used to return the *application
    root* object.  It is called on *every request* to the
    :app:`Pyramid` application.  It also performs bootstrapping by
    *creating* an application root (inside the ZODB root object) if one
@@ -118,7 +115,7 @@ Let's try to understand the components in this module:
 
 #. *Lines 1-2*. Perform some dependency imports.
 
-#. *Line 4*.  Use the :func:`pyramid.view.view_config` :term:`configuration
+#. *Line 5*.  Use the :func:`pyramid.view.view_config` :term:`configuration
    decoration` to perform a :term:`view configuration` registration.  This
    view configuration registration will be activated when the application is
    started.  It will be activated by virtue of it being found as the result
@@ -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.
 
@@ -148,7 +145,7 @@ Let's try to understand the components in this module:
    ``my_view`` function which it decorates represents the "default" view
    callable used when the context is of the type ``MyModel``.
 
-#. *Lines 5-6*.  We define a :term:`view callable` named ``my_view``, which
+#. *Lines 6-7*.  We define a :term:`view callable` named ``my_view``, which
    we decorated in the step above.  This view callable is a *function* we
    write generated by the ``zodb`` scaffold that is given a
    ``request`` and which returns a dictionary.  The ``mytemplate.pt``
@@ -165,10 +162,10 @@ Configuration in ``development.ini``
 The ``development.ini`` (in the tutorial :term:`project` directory, as
 opposed to the tutorial :term:`package` directory) looks like this:
 
-.. literalinclude:: src/views/development.ini
+.. 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 1a5d38b10..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,11 +56,11 @@ 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
-because both ``__name__`` and ``__parent__`` will be set by by a :term:`view`
+because both ``__name__`` and ``__parent__`` will be set by a :term:`view`
 function when a Page is added to our Wiki mapping.
 
 As a last step, we want to change the ``appmaker`` function in our
diff --git a/docs/tutorials/wiki/definingviews.rst b/docs/tutorials/wiki/definingviews.rst
index 529603546..efcc7bf21 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
 ===============================================
@@ -115,7 +112,7 @@ The curried function named ``check`` is used as the first argument to
 each WikiWord match found in the content.  If the wiki (our page's
 ``__parent__``) already contains a page with the matched WikiWord name, the
 ``check`` function generates a view link to be used as the substitution value
-and returns it.  If the wiki does not already contain a page with with the
+and returns it.  If the wiki does not already contain a page with the
 matched WikiWord name, the function generates an "add" link as the
 substitution value and returns it.
 
diff --git a/docs/tutorials/wiki/design.rst b/docs/tutorials/wiki/design.rst
index c94612fb1..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
@@ -53,11 +53,11 @@ Security
 We'll eventually be adding security to our application.  The components we'll
 use to do this are below.
 
-- USERS, a dictionary mapping users names to their
+- USERS, a dictionary mapping usernames to their
   corresponding passwords.
 
-- GROUPS, a dictionary mapping user names to a 
-  list of groups they belong to.
+- GROUPS, a dictionary mapping usernames to a
+  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/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 868c99dee..b545cdba0 100644
--- a/docs/tutorials/wiki/installation.rst
+++ b/docs/tutorials/wiki/installation.rst
@@ -2,52 +2,15 @@
 Installation
 ============
 
-For the most part, the installation process for this tutorial
-duplicates the steps described in :ref:`installing_chapter` and
-:ref:`project_narr`, however it also explains how to install
-additional libraries for tutorial purposes.
-
 Preparation
-========================
+===========
 
-Please take the following steps to prepare for the tutorial.  The
-steps to prepare for the tutorial are slightly different depending on
-whether you're using UNIX or Windows.
+Follow the steps in :ref:`installing_chapter`, but name the virtualenv
+directory ``pyramidtut``.
 
 Preparation, UNIX
 -----------------
 
-#. If you don't already have a Python 2.6 interpreter installed on
-   your system, obtain, install, or find `Python 2.6
-   <http://python.org/download/releases/2.6.6/>`_ for your system.
-
-#. Make sure the Python development headers are installed on your system.  If
-   you've installed Python from source, these will already be installed.  If
-   you're using a system Python, you may have to install a ``python-dev``
-   package (e.g. ``apt-get python-dev``).  The headers are not required for
-   Pyramid itself, just for dependencies of the tutorial.
-
-#. Install the latest `setuptools` into the Python you
-   obtained/installed/found in the step above: download `ez_setup.py
-   <http://peak.telecommunity.com/dist/ez_setup.py>`_ and run it using
-   the ``python`` interpreter of your Python 2.6 installation:
-
-   .. code-block:: text
-
-    $ /path/to/my/Python-2.6/bin/python ez_setup.py
-
-#. Use that Python's `bin/easy_install` to install `virtualenv`:
-
-   .. code-block:: text
-
-    $ /path/to/my/Python-2.6/bin/easy_install virtualenv
-
-#. Use that Python's virtualenv to make a workspace:
-
-   .. code-block:: text
-
-     $ path/to/my/Python-2.6/bin/virtualenv --no-site-packages \
-               pyramidtut
 
 #. Switch to the ``pyramidtut`` directory:
 
@@ -55,18 +18,7 @@ Preparation, UNIX
 
      $ cd pyramidtut
 
-#. (Optional) Consider using ``source bin/activate`` to make your
-   shell environment wired to use the virtualenv.
-
-#. Use ``easy_install`` to get :app:`Pyramid` and its direct
-   dependencies installed:
-
-   .. code-block:: text
-
-     $ bin/easy_install pyramid
-
-#. Use ``easy_install`` to install ``docutils``, ``pyramid_tm``,
-   ``pyramid_zodbconn``, ``pyramid_debugtoolbar``, ``nose`` and ``coverage``:
+#. Install tutorial dependencies:
 
    .. code-block:: text
 
@@ -76,30 +28,6 @@ Preparation, UNIX
 Preparation, Windows
 --------------------
 
-#. Install, or find `Python 2.6
-   <http://python.org/download/releases/2.6.6/>`_ for your system.
-
-#. Install the latest `setuptools` into the Python you
-   obtained/installed/found in the step above: download `ez_setup.py
-   <http://peak.telecommunity.com/dist/ez_setup.py>`_ and run it using
-   the ``python`` interpreter of your Python 2.6 installation using a
-   command prompt:
-
-   .. code-block:: text
-
-    c:\> c:\Python26\python ez_setup.py
-
-#. Use that Python's `bin/easy_install` to install `virtualenv`:
-
-   .. code-block:: text
-
-    c:\> c:\Python26\Scripts\easy_install virtualenv
-
-#. Use that Python's virtualenv to make a workspace:
-
-   .. code-block:: text
-
-     c:\> c:\Python26\Scripts\virtualenv --no-site-packages pyramidtut
 
 #. Switch to the ``pyramidtut`` directory:
 
@@ -107,18 +35,7 @@ Preparation, Windows
 
      c:\> cd pyramidtut
 
-#. (Optional) Consider using ``bin\activate.bat`` to make your shell
-   environment wired to use the virtualenv.
-
-#. Use ``easy_install`` to get :app:`Pyramid` and its direct
-   dependencies installed:
-
-   .. code-block:: text
-
-     c:\pyramidtut> Scripts\easy_install pyramid
-
-#. Use ``easy_install`` to install ``docutils``, ``pyramid_tm``,
-   ``pyramid_zodbconn``, ``pyramid_debugtoolbar``, ``nose`` and ``coverage``:
+#. Install tutorial dependencies:
 
    .. code-block:: text
 
@@ -276,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/development.ini b/docs/tutorials/wiki/src/authorization/development.ini
index 996caa741..72bd22e54 100644
--- a/docs/tutorials/wiki/src/authorization/development.ini
+++ b/docs/tutorials/wiki/src/authorization/development.ini
@@ -1,5 +1,11 @@
+###
+# app configuration
+# http://docs.pylonsproject.org/projects/pyramid/en/latest/narr/environment.html
+###
+
 [app:main]
 use = egg:tutorial
+
 pyramid.reload_templates = true
 pyramid.debug_authorization = false
 pyramid.debug_notfound = false
@@ -13,15 +19,26 @@ pyramid.includes =
 tm.attempts = 3
 zodbconn.uri = file://%(here)s/Data.fs?connection_cache_size=20000
 
+# By default, the toolbar only appears for clients from IP addresses
+# '127.0.0.1' and '::1'.
+# debugtoolbar.hosts = 127.0.0.1 ::1
+
+###
+# wsgi server configuration
+###
+
 [server:main]
 use = egg:waitress#main
 host = 0.0.0.0
 port = 6543
 
-# Begin logging configuration
+###
+# logging configuration
+# http://docs.pylonsproject.org/projects/pyramid/en/latest/narr/logging.html
+###
 
 [loggers]
-keys = root
+keys = root, tutorial
 
 [handlers]
 keys = console
@@ -33,6 +50,11 @@ keys = generic
 level = INFO
 handlers = console
 
+[logger_tutorial]
+level = DEBUG
+handlers =
+qualname = tutorial
+
 [handler_console]
 class = StreamHandler
 args = (sys.stderr,)
@@ -41,5 +63,3 @@ formatter = generic
 
 [formatter_generic]
 format = %(asctime)s %(levelname)-5.5s [%(name)s][%(threadName)s] %(message)s
-
-# End logging configuration
diff --git a/docs/tutorials/wiki/src/authorization/production.ini b/docs/tutorials/wiki/src/authorization/production.ini
index ca8107802..d9bf27c42 100644
--- a/docs/tutorials/wiki/src/authorization/production.ini
+++ b/docs/tutorials/wiki/src/authorization/production.ini
@@ -1,5 +1,11 @@
+###
+# app configuration
+# http://docs.pylonsproject.org/projects/pyramid/en/latest/narr/environment.html
+###
+
 [app:main]
 use = egg:tutorial
+
 pyramid.reload_templates = false
 pyramid.debug_authorization = false
 pyramid.debug_notfound = false
@@ -12,12 +18,19 @@ pyramid.includes =
 tm.attempts = 3
 zodbconn.uri = file://%(here)s/Data.fs?connection_cache_size=20000
 
+###
+# wsgi server configuration
+###
+
 [server:main]
 use = egg:waitress#main
 host = 0.0.0.0
 port = 6543
 
-# Begin logging configuration
+###
+# logging configuration
+# http://docs.pylonsproject.org/projects/pyramid/en/latest/narr/logging.html
+###
 
 [loggers]
 keys = root, tutorial
@@ -45,5 +58,3 @@ formatter = generic
 
 [formatter_generic]
 format = %(asctime)s %(levelname)-5.5s [%(name)s][%(threadName)s] %(message)s
-
-# End logging configuration
diff --git a/docs/tutorials/wiki/src/authorization/setup.py b/docs/tutorials/wiki/src/authorization/setup.py
index 31c51dbcf..3164fd724 100644
--- a/docs/tutorials/wiki/src/authorization/setup.py
+++ b/docs/tutorials/wiki/src/authorization/setup.py
@@ -9,6 +9,7 @@ CHANGES = open(os.path.join(here, 'CHANGES.txt')).read()
 requires = [
     'pyramid',
     'pyramid_zodbconn',
+    'transaction',
     'pyramid_tm',
     'pyramid_debugtoolbar',
     'ZODB3',
@@ -19,11 +20,10 @@ requires = [
 setup(name='tutorial',
       version='0.0',
       description='tutorial',
-      long_description=README + '\n\n' +  CHANGES,
+      long_description=README + '\n\n' + CHANGES,
       classifiers=[
-        "Intended Audience :: Developers",
-        "Framework :: Pylons",
         "Programming Language :: Python",
+        "Framework :: Pyramid",
         "Topic :: Internet :: WWW/HTTP",
         "Topic :: Internet :: WWW/HTTP :: WSGI :: Application",
         ],
@@ -37,9 +37,8 @@ setup(name='tutorial',
       install_requires=requires,
       tests_require=requires,
       test_suite="tutorial",
-      entry_points = """\
+      entry_points="""\
       [paste.app_factory]
       main = tutorial:main
       """,
       )
-
diff --git a/docs/tutorials/wiki/src/authorization/tutorial/__init__.py b/docs/tutorials/wiki/src/authorization/tutorial/__init__.py
index b42e01d03..8ea8f8fa3 100644
--- a/docs/tutorials/wiki/src/authorization/tutorial/__init__.py
+++ b/docs/tutorials/wiki/src/authorization/tutorial/__init__.py
@@ -11,8 +11,9 @@ def root_factory(request):
     conn = get_connection(request)
     return appmaker(conn.root())
 
+
 def main(global_config, **settings):
-    """ This function returns a WSGI application.
+    """ This function returns a Pyramid WSGI application.
     """
     authn_policy = AuthTktAuthenticationPolicy(
         'sosecret', callback=groupfinder, hashalg='sha512')
diff --git a/docs/tutorials/wiki/src/authorization/tutorial/templates/mytemplate.pt b/docs/tutorials/wiki/src/authorization/tutorial/templates/mytemplate.pt
index 3597c679b..84824f605 100644
--- a/docs/tutorials/wiki/src/authorization/tutorial/templates/mytemplate.pt
+++ b/docs/tutorials/wiki/src/authorization/tutorial/templates/mytemplate.pt
@@ -6,9 +6,9 @@
   <meta name="keywords" content="python web application" />
   <meta name="description" content="pyramid web application" />
   <link rel="shortcut icon" href="/static/favicon.ico" />
+  <link rel="stylesheet" href="/static/pylons.css" type="text/css" media="screen" charset="utf-8" />
   <link rel="stylesheet" href="http://static.pylonsproject.org/fonts/nobile/stylesheet.css" media="screen" />
   <link rel="stylesheet" href="http://static.pylonsproject.org/fonts/neuton/stylesheet.css" media="screen" />
-  <link rel="stylesheet" href="/static/pylons.css" type="text/css" media="screen" charset="utf-8" />
   <!--[if lte IE 6]>
   <link rel="stylesheet" href="/static/ie6.css" type="text/css" media="screen" charset="utf-8" />
   <![endif]-->
@@ -41,7 +41,7 @@
           <h2>Pyramid links</h2>
           <ul class="links">
             <li>
-              <a href="http://pylonsproject.org">Pylons Website</a>
+              <a href="http://pylonsproject.org/">Pylons Website</a>
             </li>
             <li>
               <a href="http://docs.pylonsproject.org/projects/pyramid/current/#narrative-documentation">Narrative Documentation</a>
@@ -70,7 +70,7 @@
     </div>
   </div>
   <div id="footer">
-    <div class="footer">&copy; Copyright 2008-2011, Agendaless Consulting.</div>
+    <div class="footer">&copy; Copyright 2008-2012, Agendaless Consulting.</div>
   </div>
 </body>
 </html>
diff --git a/docs/tutorials/wiki/src/authorization/tutorial/tests.py b/docs/tutorials/wiki/src/authorization/tutorial/tests.py
index 77e7cce29..0b9046d47 100644
--- a/docs/tutorials/wiki/src/authorization/tutorial/tests.py
+++ b/docs/tutorials/wiki/src/authorization/tutorial/tests.py
@@ -30,6 +30,7 @@ class WikiModelTests(unittest.TestCase):
         self.assertEqual(wiki.__name__, None)
 
 class AppmakerTests(unittest.TestCase):
+
     def _callFUT(self, zodb_root):
         from .models import appmaker
         return appmaker(zodb_root)
@@ -63,7 +64,7 @@ class ViewPageTests(unittest.TestCase):
         info = self._callFUT(context, request)
         self.assertEqual(info['page'], context)
         self.assertEqual(
-            info['content'], 
+            info['content'],
             '<div class="document">\n'
             '<p>Hello <a href="http://example.com/add_page/CruelWorld">'
             'CruelWorld</a> '
@@ -85,9 +86,9 @@ class AddPageTests(unittest.TestCase):
         request.subpath = ['AnotherPage']
         info = self._callFUT(context, request)
         self.assertEqual(info['page'].data,'')
-        self.assertEqual(info['save_url'],
-                         request.resource_url(
-                             context, 'add_page', 'AnotherPage'))
+        self.assertEqual(
+            info['save_url'],
+            request.resource_url(context, 'add_page', 'AnotherPage'))
 
     def test_it_submitted(self):
         context = testing.DummyResource()
diff --git a/docs/tutorials/wiki/src/authorization/tutorial/views.py b/docs/tutorials/wiki/src/authorization/tutorial/views.py
index 50485d279..77956b1e3 100644
--- a/docs/tutorials/wiki/src/authorization/tutorial/views.py
+++ b/docs/tutorials/wiki/src/authorization/tutorial/views.py
@@ -64,8 +64,8 @@ def add_page(context, request):
     page.__name__ = pagename
     page.__parent__ = context
 
-    return dict(page = page, save_url = save_url,
-                logged_in = authenticated_userid(request))
+    return dict(page=page, save_url=save_url,
+                logged_in=authenticated_userid(request))
 
 @view_config(name='edit_page', context='.models.Page',
              renderer='templates/edit.pt',
@@ -75,9 +75,9 @@ def edit_page(context, request):
         context.data = request.params['body']
         return HTTPFound(location = request.resource_url(context))
 
-    return dict(page = context,
-                save_url = request.resource_url(context, 'edit_page'),
-                logged_in = authenticated_userid(request))
+    return dict(page=context,
+                save_url=request.resource_url(context, 'edit_page'),
+                logged_in=authenticated_userid(request))
 
 @view_config(context='.models.Wiki', name='login',
              renderer='templates/login.pt')
diff --git a/docs/tutorials/wiki/src/basiclayout/development.ini b/docs/tutorials/wiki/src/basiclayout/development.ini
index f637ebaa6..72bd22e54 100644
--- a/docs/tutorials/wiki/src/basiclayout/development.ini
+++ b/docs/tutorials/wiki/src/basiclayout/development.ini
@@ -1,5 +1,11 @@
+###
+# app configuration
+# http://docs.pylonsproject.org/projects/pyramid/en/latest/narr/environment.html
+###
+
 [app:main]
 use = egg:tutorial
+
 pyramid.reload_templates = true
 pyramid.debug_authorization = false
 pyramid.debug_notfound = false
@@ -13,15 +19,26 @@ pyramid.includes =
 tm.attempts = 3
 zodbconn.uri = file://%(here)s/Data.fs?connection_cache_size=20000
 
+# By default, the toolbar only appears for clients from IP addresses
+# '127.0.0.1' and '::1'.
+# debugtoolbar.hosts = 127.0.0.1 ::1
+
+###
+# wsgi server configuration
+###
+
 [server:main]
 use = egg:waitress#main
 host = 0.0.0.0
 port = 6543
 
-# Begin logging configuration
+###
+# logging configuration
+# http://docs.pylonsproject.org/projects/pyramid/en/latest/narr/logging.html
+###
 
 [loggers]
-keys = root
+keys = root, tutorial
 
 [handlers]
 keys = console
@@ -33,6 +50,11 @@ keys = generic
 level = INFO
 handlers = console
 
+[logger_tutorial]
+level = DEBUG
+handlers =
+qualname = tutorial
+
 [handler_console]
 class = StreamHandler
 args = (sys.stderr,)
@@ -40,6 +62,4 @@ level = NOTSET
 formatter = generic
 
 [formatter_generic]
-format = %(asctime)s %(levelname)-5.5s [%(name)s] %(message)s
-
-# End logging configuration
+format = %(asctime)s %(levelname)-5.5s [%(name)s][%(threadName)s] %(message)s
diff --git a/docs/tutorials/wiki/src/basiclayout/production.ini b/docs/tutorials/wiki/src/basiclayout/production.ini
index ca8107802..d9bf27c42 100644
--- a/docs/tutorials/wiki/src/basiclayout/production.ini
+++ b/docs/tutorials/wiki/src/basiclayout/production.ini
@@ -1,5 +1,11 @@
+###
+# app configuration
+# http://docs.pylonsproject.org/projects/pyramid/en/latest/narr/environment.html
+###
+
 [app:main]
 use = egg:tutorial
+
 pyramid.reload_templates = false
 pyramid.debug_authorization = false
 pyramid.debug_notfound = false
@@ -12,12 +18,19 @@ pyramid.includes =
 tm.attempts = 3
 zodbconn.uri = file://%(here)s/Data.fs?connection_cache_size=20000
 
+###
+# wsgi server configuration
+###
+
 [server:main]
 use = egg:waitress#main
 host = 0.0.0.0
 port = 6543
 
-# Begin logging configuration
+###
+# logging configuration
+# http://docs.pylonsproject.org/projects/pyramid/en/latest/narr/logging.html
+###
 
 [loggers]
 keys = root, tutorial
@@ -45,5 +58,3 @@ formatter = generic
 
 [formatter_generic]
 format = %(asctime)s %(levelname)-5.5s [%(name)s][%(threadName)s] %(message)s
-
-# End logging configuration
diff --git a/docs/tutorials/wiki/src/basiclayout/setup.py b/docs/tutorials/wiki/src/basiclayout/setup.py
index 43600e239..4998be902 100644
--- a/docs/tutorials/wiki/src/basiclayout/setup.py
+++ b/docs/tutorials/wiki/src/basiclayout/setup.py
@@ -9,6 +9,7 @@ CHANGES = open(os.path.join(here, 'CHANGES.txt')).read()
 requires = [
     'pyramid',
     'pyramid_zodbconn',
+    'transaction',
     'pyramid_tm',
     'pyramid_debugtoolbar',
     'ZODB3',
@@ -18,10 +19,10 @@ requires = [
 setup(name='tutorial',
       version='0.0',
       description='tutorial',
-      long_description=README + '\n\n' +  CHANGES,
+      long_description=README + '\n\n' + CHANGES,
       classifiers=[
         "Programming Language :: Python",
-        "Framework :: Pylons",
+        "Framework :: Pyramid",
         "Topic :: Internet :: WWW/HTTP",
         "Topic :: Internet :: WWW/HTTP :: WSGI :: Application",
         ],
@@ -32,12 +33,11 @@ setup(name='tutorial',
       packages=find_packages(),
       include_package_data=True,
       zip_safe=False,
-      install_requires = requires,
-      tests_require= requires,
+      install_requires=requires,
+      tests_require=requires,
       test_suite="tutorial",
-      entry_points = """\
+      entry_points="""\
       [paste.app_factory]
       main = tutorial:main
       """,
       )
-
diff --git a/docs/tutorials/wiki/src/basiclayout/tutorial/__init__.py b/docs/tutorials/wiki/src/basiclayout/tutorial/__init__.py
index b63933fc5..c3bb87a62 100644
--- a/docs/tutorials/wiki/src/basiclayout/tutorial/__init__.py
+++ b/docs/tutorials/wiki/src/basiclayout/tutorial/__init__.py
@@ -2,10 +2,12 @@ from pyramid.config import Configurator
 from pyramid_zodbconn import get_connection
 from .models import appmaker
 
+
 def root_factory(request):
     conn = get_connection(request)
     return appmaker(conn.root())
 
+
 def main(global_config, **settings):
     """ This function returns a Pyramid WSGI application.
     """
diff --git a/docs/tutorials/wiki/src/basiclayout/tutorial/models.py b/docs/tutorials/wiki/src/basiclayout/tutorial/models.py
index 8dd0f5a49..a94b36ef4 100644
--- a/docs/tutorials/wiki/src/basiclayout/tutorial/models.py
+++ b/docs/tutorials/wiki/src/basiclayout/tutorial/models.py
@@ -1,8 +1,10 @@
 from persistent.mapping import PersistentMapping
 
+
 class MyModel(PersistentMapping):
     __parent__ = __name__ = None
 
+
 def appmaker(zodb_root):
     if not 'app_root' in zodb_root:
         app_root = MyModel()
diff --git a/docs/tutorials/wiki/src/basiclayout/tutorial/templates/mytemplate.pt b/docs/tutorials/wiki/src/basiclayout/tutorial/templates/mytemplate.pt
index 557e071ed..84824f605 100644
--- a/docs/tutorials/wiki/src/basiclayout/tutorial/templates/mytemplate.pt
+++ b/docs/tutorials/wiki/src/basiclayout/tutorial/templates/mytemplate.pt
@@ -6,9 +6,9 @@
   <meta name="keywords" content="python web application" />
   <meta name="description" content="pyramid web application" />
   <link rel="shortcut icon" href="/static/favicon.ico" />
+  <link rel="stylesheet" href="/static/pylons.css" type="text/css" media="screen" charset="utf-8" />
   <link rel="stylesheet" href="http://static.pylonsproject.org/fonts/nobile/stylesheet.css" media="screen" />
   <link rel="stylesheet" href="http://static.pylonsproject.org/fonts/neuton/stylesheet.css" media="screen" />
-  <link rel="stylesheet" href="/static/pylons.css" type="text/css" media="screen" charset="utf-8" />
   <!--[if lte IE 6]>
   <link rel="stylesheet" href="/static/ie6.css" type="text/css" media="screen" charset="utf-8" />
   <![endif]-->
@@ -70,7 +70,7 @@
     </div>
   </div>
   <div id="footer">
-    <div class="footer">&copy; Copyright 2008-2011, Agendaless Consulting.</div>
+    <div class="footer">&copy; Copyright 2008-2012, Agendaless Consulting.</div>
   </div>
 </body>
 </html>
diff --git a/docs/tutorials/wiki/src/basiclayout/tutorial/tests.py b/docs/tutorials/wiki/src/basiclayout/tutorial/tests.py
index 8d2374be1..7f6523c66 100644
--- a/docs/tutorials/wiki/src/basiclayout/tutorial/tests.py
+++ b/docs/tutorials/wiki/src/basiclayout/tutorial/tests.py
@@ -14,4 +14,3 @@ class ViewTests(unittest.TestCase):
         request = testing.DummyRequest()
         info = my_view(request)
         self.assertEqual(info['project'], 'tutorial')
-
diff --git a/docs/tutorials/wiki/src/basiclayout/tutorial/views.py b/docs/tutorials/wiki/src/basiclayout/tutorial/views.py
index 4265b6bf7..628ce15ed 100644
--- a/docs/tutorials/wiki/src/basiclayout/tutorial/views.py
+++ b/docs/tutorials/wiki/src/basiclayout/tutorial/views.py
@@ -1,6 +1,7 @@
 from pyramid.view import view_config
 from .models import MyModel
 
+
 @view_config(context=MyModel, renderer='templates/mytemplate.pt')
 def my_view(request):
-    return {'project':'tutorial'}
+    return {'project': 'tutorial'}
diff --git a/docs/tutorials/wiki/src/models/development.ini b/docs/tutorials/wiki/src/models/development.ini
index 996caa741..72bd22e54 100644
--- a/docs/tutorials/wiki/src/models/development.ini
+++ b/docs/tutorials/wiki/src/models/development.ini
@@ -1,5 +1,11 @@
+###
+# app configuration
+# http://docs.pylonsproject.org/projects/pyramid/en/latest/narr/environment.html
+###
+
 [app:main]
 use = egg:tutorial
+
 pyramid.reload_templates = true
 pyramid.debug_authorization = false
 pyramid.debug_notfound = false
@@ -13,15 +19,26 @@ pyramid.includes =
 tm.attempts = 3
 zodbconn.uri = file://%(here)s/Data.fs?connection_cache_size=20000
 
+# By default, the toolbar only appears for clients from IP addresses
+# '127.0.0.1' and '::1'.
+# debugtoolbar.hosts = 127.0.0.1 ::1
+
+###
+# wsgi server configuration
+###
+
 [server:main]
 use = egg:waitress#main
 host = 0.0.0.0
 port = 6543
 
-# Begin logging configuration
+###
+# logging configuration
+# http://docs.pylonsproject.org/projects/pyramid/en/latest/narr/logging.html
+###
 
 [loggers]
-keys = root
+keys = root, tutorial
 
 [handlers]
 keys = console
@@ -33,6 +50,11 @@ keys = generic
 level = INFO
 handlers = console
 
+[logger_tutorial]
+level = DEBUG
+handlers =
+qualname = tutorial
+
 [handler_console]
 class = StreamHandler
 args = (sys.stderr,)
@@ -41,5 +63,3 @@ formatter = generic
 
 [formatter_generic]
 format = %(asctime)s %(levelname)-5.5s [%(name)s][%(threadName)s] %(message)s
-
-# End logging configuration
diff --git a/docs/tutorials/wiki/src/models/production.ini b/docs/tutorials/wiki/src/models/production.ini
index ca8107802..d9bf27c42 100644
--- a/docs/tutorials/wiki/src/models/production.ini
+++ b/docs/tutorials/wiki/src/models/production.ini
@@ -1,5 +1,11 @@
+###
+# app configuration
+# http://docs.pylonsproject.org/projects/pyramid/en/latest/narr/environment.html
+###
+
 [app:main]
 use = egg:tutorial
+
 pyramid.reload_templates = false
 pyramid.debug_authorization = false
 pyramid.debug_notfound = false
@@ -12,12 +18,19 @@ pyramid.includes =
 tm.attempts = 3
 zodbconn.uri = file://%(here)s/Data.fs?connection_cache_size=20000
 
+###
+# wsgi server configuration
+###
+
 [server:main]
 use = egg:waitress#main
 host = 0.0.0.0
 port = 6543
 
-# Begin logging configuration
+###
+# logging configuration
+# http://docs.pylonsproject.org/projects/pyramid/en/latest/narr/logging.html
+###
 
 [loggers]
 keys = root, tutorial
@@ -45,5 +58,3 @@ formatter = generic
 
 [formatter_generic]
 format = %(asctime)s %(levelname)-5.5s [%(name)s][%(threadName)s] %(message)s
-
-# End logging configuration
diff --git a/docs/tutorials/wiki/src/models/setup.py b/docs/tutorials/wiki/src/models/setup.py
index 43600e239..4998be902 100644
--- a/docs/tutorials/wiki/src/models/setup.py
+++ b/docs/tutorials/wiki/src/models/setup.py
@@ -9,6 +9,7 @@ CHANGES = open(os.path.join(here, 'CHANGES.txt')).read()
 requires = [
     'pyramid',
     'pyramid_zodbconn',
+    'transaction',
     'pyramid_tm',
     'pyramid_debugtoolbar',
     'ZODB3',
@@ -18,10 +19,10 @@ requires = [
 setup(name='tutorial',
       version='0.0',
       description='tutorial',
-      long_description=README + '\n\n' +  CHANGES,
+      long_description=README + '\n\n' + CHANGES,
       classifiers=[
         "Programming Language :: Python",
-        "Framework :: Pylons",
+        "Framework :: Pyramid",
         "Topic :: Internet :: WWW/HTTP",
         "Topic :: Internet :: WWW/HTTP :: WSGI :: Application",
         ],
@@ -32,12 +33,11 @@ setup(name='tutorial',
       packages=find_packages(),
       include_package_data=True,
       zip_safe=False,
-      install_requires = requires,
-      tests_require= requires,
+      install_requires=requires,
+      tests_require=requires,
       test_suite="tutorial",
-      entry_points = """\
+      entry_points="""\
       [paste.app_factory]
       main = tutorial:main
       """,
       )
-
diff --git a/docs/tutorials/wiki/src/models/tutorial/__init__.py b/docs/tutorials/wiki/src/models/tutorial/__init__.py
index c59f36e7b..c3bb87a62 100644
--- a/docs/tutorials/wiki/src/models/tutorial/__init__.py
+++ b/docs/tutorials/wiki/src/models/tutorial/__init__.py
@@ -2,15 +2,16 @@ from pyramid.config import Configurator
 from pyramid_zodbconn import get_connection
 from .models import appmaker
 
+
 def root_factory(request):
     conn = get_connection(request)
     return appmaker(conn.root())
 
+
 def main(global_config, **settings):
-    """ This function returns a WSGI application.
+    """ This function returns a Pyramid WSGI application.
     """
     config = Configurator(root_factory=root_factory, settings=settings)
     config.add_static_view('static', 'static', cache_max_age=3600)
     config.scan()
     return config.make_wsgi_app()
-
diff --git a/docs/tutorials/wiki/src/models/tutorial/templates/mytemplate.pt b/docs/tutorials/wiki/src/models/tutorial/templates/mytemplate.pt
index 3597c679b..84824f605 100644
--- a/docs/tutorials/wiki/src/models/tutorial/templates/mytemplate.pt
+++ b/docs/tutorials/wiki/src/models/tutorial/templates/mytemplate.pt
@@ -6,9 +6,9 @@
   <meta name="keywords" content="python web application" />
   <meta name="description" content="pyramid web application" />
   <link rel="shortcut icon" href="/static/favicon.ico" />
+  <link rel="stylesheet" href="/static/pylons.css" type="text/css" media="screen" charset="utf-8" />
   <link rel="stylesheet" href="http://static.pylonsproject.org/fonts/nobile/stylesheet.css" media="screen" />
   <link rel="stylesheet" href="http://static.pylonsproject.org/fonts/neuton/stylesheet.css" media="screen" />
-  <link rel="stylesheet" href="/static/pylons.css" type="text/css" media="screen" charset="utf-8" />
   <!--[if lte IE 6]>
   <link rel="stylesheet" href="/static/ie6.css" type="text/css" media="screen" charset="utf-8" />
   <![endif]-->
@@ -41,7 +41,7 @@
           <h2>Pyramid links</h2>
           <ul class="links">
             <li>
-              <a href="http://pylonsproject.org">Pylons Website</a>
+              <a href="http://pylonsproject.org/">Pylons Website</a>
             </li>
             <li>
               <a href="http://docs.pylonsproject.org/projects/pyramid/current/#narrative-documentation">Narrative Documentation</a>
@@ -70,7 +70,7 @@
     </div>
   </div>
   <div id="footer">
-    <div class="footer">&copy; Copyright 2008-2011, Agendaless Consulting.</div>
+    <div class="footer">&copy; Copyright 2008-2012, Agendaless Consulting.</div>
   </div>
 </body>
 </html>
diff --git a/docs/tutorials/wiki/src/models/tutorial/views.py b/docs/tutorials/wiki/src/models/tutorial/views.py
index 7c1f1d228..628ce15ed 100644
--- a/docs/tutorials/wiki/src/models/tutorial/views.py
+++ b/docs/tutorials/wiki/src/models/tutorial/views.py
@@ -1,5 +1,7 @@
 from pyramid.view import view_config
+from .models import MyModel
 
-@view_config(renderer='templates/mytemplate.pt')
+
+@view_config(context=MyModel, renderer='templates/mytemplate.pt')
 def my_view(request):
-    return {'project':'tutorial'}
+    return {'project': 'tutorial'}
diff --git a/docs/tutorials/wiki/src/tests/development.ini b/docs/tutorials/wiki/src/tests/development.ini
index 996caa741..72bd22e54 100644
--- a/docs/tutorials/wiki/src/tests/development.ini
+++ b/docs/tutorials/wiki/src/tests/development.ini
@@ -1,5 +1,11 @@
+###
+# app configuration
+# http://docs.pylonsproject.org/projects/pyramid/en/latest/narr/environment.html
+###
+
 [app:main]
 use = egg:tutorial
+
 pyramid.reload_templates = true
 pyramid.debug_authorization = false
 pyramid.debug_notfound = false
@@ -13,15 +19,26 @@ pyramid.includes =
 tm.attempts = 3
 zodbconn.uri = file://%(here)s/Data.fs?connection_cache_size=20000
 
+# By default, the toolbar only appears for clients from IP addresses
+# '127.0.0.1' and '::1'.
+# debugtoolbar.hosts = 127.0.0.1 ::1
+
+###
+# wsgi server configuration
+###
+
 [server:main]
 use = egg:waitress#main
 host = 0.0.0.0
 port = 6543
 
-# Begin logging configuration
+###
+# logging configuration
+# http://docs.pylonsproject.org/projects/pyramid/en/latest/narr/logging.html
+###
 
 [loggers]
-keys = root
+keys = root, tutorial
 
 [handlers]
 keys = console
@@ -33,6 +50,11 @@ keys = generic
 level = INFO
 handlers = console
 
+[logger_tutorial]
+level = DEBUG
+handlers =
+qualname = tutorial
+
 [handler_console]
 class = StreamHandler
 args = (sys.stderr,)
@@ -41,5 +63,3 @@ formatter = generic
 
 [formatter_generic]
 format = %(asctime)s %(levelname)-5.5s [%(name)s][%(threadName)s] %(message)s
-
-# End logging configuration
diff --git a/docs/tutorials/wiki/src/tests/production.ini b/docs/tutorials/wiki/src/tests/production.ini
index ca8107802..d9bf27c42 100644
--- a/docs/tutorials/wiki/src/tests/production.ini
+++ b/docs/tutorials/wiki/src/tests/production.ini
@@ -1,5 +1,11 @@
+###
+# app configuration
+# http://docs.pylonsproject.org/projects/pyramid/en/latest/narr/environment.html
+###
+
 [app:main]
 use = egg:tutorial
+
 pyramid.reload_templates = false
 pyramid.debug_authorization = false
 pyramid.debug_notfound = false
@@ -12,12 +18,19 @@ pyramid.includes =
 tm.attempts = 3
 zodbconn.uri = file://%(here)s/Data.fs?connection_cache_size=20000
 
+###
+# wsgi server configuration
+###
+
 [server:main]
 use = egg:waitress#main
 host = 0.0.0.0
 port = 6543
 
-# Begin logging configuration
+###
+# logging configuration
+# http://docs.pylonsproject.org/projects/pyramid/en/latest/narr/logging.html
+###
 
 [loggers]
 keys = root, tutorial
@@ -45,5 +58,3 @@ formatter = generic
 
 [formatter_generic]
 format = %(asctime)s %(levelname)-5.5s [%(name)s][%(threadName)s] %(message)s
-
-# End logging configuration
diff --git a/docs/tutorials/wiki/src/tests/setup.py b/docs/tutorials/wiki/src/tests/setup.py
index a7ad7317c..702d34c4c 100644
--- a/docs/tutorials/wiki/src/tests/setup.py
+++ b/docs/tutorials/wiki/src/tests/setup.py
@@ -9,6 +9,7 @@ CHANGES = open(os.path.join(here, 'CHANGES.txt')).read()
 requires = [
     'pyramid',
     'pyramid_zodbconn',
+    'transaction',
     'pyramid_tm',
     'pyramid_debugtoolbar',
     'ZODB3',
@@ -20,11 +21,10 @@ requires = [
 setup(name='tutorial',
       version='0.0',
       description='tutorial',
-      long_description=README + '\n\n' +  CHANGES,
+      long_description=README + '\n\n' + CHANGES,
       classifiers=[
-        "Intended Audience :: Developers",
-        "Framework :: Pylons",
         "Programming Language :: Python",
+        "Framework :: Pyramid",
         "Topic :: Internet :: WWW/HTTP",
         "Topic :: Internet :: WWW/HTTP :: WSGI :: Application",
         ],
@@ -38,9 +38,8 @@ setup(name='tutorial',
       install_requires=requires,
       tests_require=requires,
       test_suite="tutorial",
-      entry_points = """\
+      entry_points="""\
       [paste.app_factory]
       main = tutorial:main
       """,
       )
-
diff --git a/docs/tutorials/wiki/src/tests/tutorial/__init__.py b/docs/tutorials/wiki/src/tests/tutorial/__init__.py
index b42e01d03..8ea8f8fa3 100644
--- a/docs/tutorials/wiki/src/tests/tutorial/__init__.py
+++ b/docs/tutorials/wiki/src/tests/tutorial/__init__.py
@@ -11,8 +11,9 @@ def root_factory(request):
     conn = get_connection(request)
     return appmaker(conn.root())
 
+
 def main(global_config, **settings):
-    """ This function returns a WSGI application.
+    """ This function returns a Pyramid WSGI application.
     """
     authn_policy = AuthTktAuthenticationPolicy(
         'sosecret', callback=groupfinder, hashalg='sha512')
diff --git a/docs/tutorials/wiki/src/tests/tutorial/templates/mytemplate.pt b/docs/tutorials/wiki/src/tests/tutorial/templates/mytemplate.pt
index 3597c679b..84824f605 100644
--- a/docs/tutorials/wiki/src/tests/tutorial/templates/mytemplate.pt
+++ b/docs/tutorials/wiki/src/tests/tutorial/templates/mytemplate.pt
@@ -6,9 +6,9 @@
   <meta name="keywords" content="python web application" />
   <meta name="description" content="pyramid web application" />
   <link rel="shortcut icon" href="/static/favicon.ico" />
+  <link rel="stylesheet" href="/static/pylons.css" type="text/css" media="screen" charset="utf-8" />
   <link rel="stylesheet" href="http://static.pylonsproject.org/fonts/nobile/stylesheet.css" media="screen" />
   <link rel="stylesheet" href="http://static.pylonsproject.org/fonts/neuton/stylesheet.css" media="screen" />
-  <link rel="stylesheet" href="/static/pylons.css" type="text/css" media="screen" charset="utf-8" />
   <!--[if lte IE 6]>
   <link rel="stylesheet" href="/static/ie6.css" type="text/css" media="screen" charset="utf-8" />
   <![endif]-->
@@ -41,7 +41,7 @@
           <h2>Pyramid links</h2>
           <ul class="links">
             <li>
-              <a href="http://pylonsproject.org">Pylons Website</a>
+              <a href="http://pylonsproject.org/">Pylons Website</a>
             </li>
             <li>
               <a href="http://docs.pylonsproject.org/projects/pyramid/current/#narrative-documentation">Narrative Documentation</a>
@@ -70,7 +70,7 @@
     </div>
   </div>
   <div id="footer">
-    <div class="footer">&copy; Copyright 2008-2011, Agendaless Consulting.</div>
+    <div class="footer">&copy; Copyright 2008-2012, Agendaless Consulting.</div>
   </div>
 </body>
 </html>
diff --git a/docs/tutorials/wiki/src/tests/tutorial/tests.py b/docs/tutorials/wiki/src/tests/tutorial/tests.py
index 81f7a1882..c435a4519 100644
--- a/docs/tutorials/wiki/src/tests/tutorial/tests.py
+++ b/docs/tutorials/wiki/src/tests/tutorial/tests.py
@@ -30,6 +30,7 @@ class WikiModelTests(unittest.TestCase):
         self.assertEqual(wiki.__name__, None)
 
 class AppmakerTests(unittest.TestCase):
+
     def _callFUT(self, zodb_root):
         from .models import appmaker
         return appmaker(zodb_root)
@@ -142,7 +143,7 @@ class FunctionalTests(unittest.TestCase):
                      'pyramid.includes': ['pyramid_zodbconn', 'pyramid_tm'] }
 
         app = main({}, **settings)
-        self.db = app.registry.zodb_database
+        self.db = app.registry._zodb_databases['']
         from webtest import TestApp
         self.testapp = TestApp(app)
 
diff --git a/docs/tutorials/wiki/src/tests/tutorial/views.py b/docs/tutorials/wiki/src/tests/tutorial/views.py
index 50485d279..77956b1e3 100644
--- a/docs/tutorials/wiki/src/tests/tutorial/views.py
+++ b/docs/tutorials/wiki/src/tests/tutorial/views.py
@@ -64,8 +64,8 @@ def add_page(context, request):
     page.__name__ = pagename
     page.__parent__ = context
 
-    return dict(page = page, save_url = save_url,
-                logged_in = authenticated_userid(request))
+    return dict(page=page, save_url=save_url,
+                logged_in=authenticated_userid(request))
 
 @view_config(name='edit_page', context='.models.Page',
              renderer='templates/edit.pt',
@@ -75,9 +75,9 @@ def edit_page(context, request):
         context.data = request.params['body']
         return HTTPFound(location = request.resource_url(context))
 
-    return dict(page = context,
-                save_url = request.resource_url(context, 'edit_page'),
-                logged_in = authenticated_userid(request))
+    return dict(page=context,
+                save_url=request.resource_url(context, 'edit_page'),
+                logged_in=authenticated_userid(request))
 
 @view_config(context='.models.Wiki', name='login',
              renderer='templates/login.pt')
diff --git a/docs/tutorials/wiki/src/views/development.ini b/docs/tutorials/wiki/src/views/development.ini
index f637ebaa6..72bd22e54 100644
--- a/docs/tutorials/wiki/src/views/development.ini
+++ b/docs/tutorials/wiki/src/views/development.ini
@@ -1,5 +1,11 @@
+###
+# app configuration
+# http://docs.pylonsproject.org/projects/pyramid/en/latest/narr/environment.html
+###
+
 [app:main]
 use = egg:tutorial
+
 pyramid.reload_templates = true
 pyramid.debug_authorization = false
 pyramid.debug_notfound = false
@@ -13,15 +19,26 @@ pyramid.includes =
 tm.attempts = 3
 zodbconn.uri = file://%(here)s/Data.fs?connection_cache_size=20000
 
+# By default, the toolbar only appears for clients from IP addresses
+# '127.0.0.1' and '::1'.
+# debugtoolbar.hosts = 127.0.0.1 ::1
+
+###
+# wsgi server configuration
+###
+
 [server:main]
 use = egg:waitress#main
 host = 0.0.0.0
 port = 6543
 
-# Begin logging configuration
+###
+# logging configuration
+# http://docs.pylonsproject.org/projects/pyramid/en/latest/narr/logging.html
+###
 
 [loggers]
-keys = root
+keys = root, tutorial
 
 [handlers]
 keys = console
@@ -33,6 +50,11 @@ keys = generic
 level = INFO
 handlers = console
 
+[logger_tutorial]
+level = DEBUG
+handlers =
+qualname = tutorial
+
 [handler_console]
 class = StreamHandler
 args = (sys.stderr,)
@@ -40,6 +62,4 @@ level = NOTSET
 formatter = generic
 
 [formatter_generic]
-format = %(asctime)s %(levelname)-5.5s [%(name)s] %(message)s
-
-# End logging configuration
+format = %(asctime)s %(levelname)-5.5s [%(name)s][%(threadName)s] %(message)s
diff --git a/docs/tutorials/wiki/src/views/production.ini b/docs/tutorials/wiki/src/views/production.ini
index ca8107802..d9bf27c42 100644
--- a/docs/tutorials/wiki/src/views/production.ini
+++ b/docs/tutorials/wiki/src/views/production.ini
@@ -1,5 +1,11 @@
+###
+# app configuration
+# http://docs.pylonsproject.org/projects/pyramid/en/latest/narr/environment.html
+###
+
 [app:main]
 use = egg:tutorial
+
 pyramid.reload_templates = false
 pyramid.debug_authorization = false
 pyramid.debug_notfound = false
@@ -12,12 +18,19 @@ pyramid.includes =
 tm.attempts = 3
 zodbconn.uri = file://%(here)s/Data.fs?connection_cache_size=20000
 
+###
+# wsgi server configuration
+###
+
 [server:main]
 use = egg:waitress#main
 host = 0.0.0.0
 port = 6543
 
-# Begin logging configuration
+###
+# logging configuration
+# http://docs.pylonsproject.org/projects/pyramid/en/latest/narr/logging.html
+###
 
 [loggers]
 keys = root, tutorial
@@ -45,5 +58,3 @@ formatter = generic
 
 [formatter_generic]
 format = %(asctime)s %(levelname)-5.5s [%(name)s][%(threadName)s] %(message)s
-
-# End logging configuration
diff --git a/docs/tutorials/wiki/src/views/setup.py b/docs/tutorials/wiki/src/views/setup.py
index a6be89b2e..3164fd724 100644
--- a/docs/tutorials/wiki/src/views/setup.py
+++ b/docs/tutorials/wiki/src/views/setup.py
@@ -9,6 +9,7 @@ CHANGES = open(os.path.join(here, 'CHANGES.txt')).read()
 requires = [
     'pyramid',
     'pyramid_zodbconn',
+    'transaction',
     'pyramid_tm',
     'pyramid_debugtoolbar',
     'ZODB3',
@@ -19,11 +20,10 @@ requires = [
 setup(name='tutorial',
       version='0.0',
       description='tutorial',
-      long_description=README + '\n\n' +  CHANGES,
+      long_description=README + '\n\n' + CHANGES,
       classifiers=[
-        "Intended Audience :: Developers",
-        "Framework :: Pylons",
         "Programming Language :: Python",
+        "Framework :: Pyramid",
         "Topic :: Internet :: WWW/HTTP",
         "Topic :: Internet :: WWW/HTTP :: WSGI :: Application",
         ],
@@ -37,7 +37,7 @@ setup(name='tutorial',
       install_requires=requires,
       tests_require=requires,
       test_suite="tutorial",
-      entry_points = """\
+      entry_points="""\
       [paste.app_factory]
       main = tutorial:main
       """,
diff --git a/docs/tutorials/wiki/src/views/tutorial/__init__.py b/docs/tutorials/wiki/src/views/tutorial/__init__.py
index 957a0b705..c3bb87a62 100644
--- a/docs/tutorials/wiki/src/views/tutorial/__init__.py
+++ b/docs/tutorials/wiki/src/views/tutorial/__init__.py
@@ -1,15 +1,17 @@
 from pyramid.config import Configurator
 from pyramid_zodbconn import get_connection
-from tutorial.models import appmaker
+from .models import appmaker
+
 
 def root_factory(request):
     conn = get_connection(request)
     return appmaker(conn.root())
 
+
 def main(global_config, **settings):
-    """ This function returns a WSGI application.
+    """ This function returns a Pyramid WSGI application.
     """
     config = Configurator(root_factory=root_factory, settings=settings)
     config.add_static_view('static', 'static', cache_max_age=3600)
-    config.scan('tutorial')
+    config.scan()
     return config.make_wsgi_app()
diff --git a/docs/tutorials/wiki/src/views/tutorial/templates/mytemplate.pt b/docs/tutorials/wiki/src/views/tutorial/templates/mytemplate.pt
index 3597c679b..84824f605 100644
--- a/docs/tutorials/wiki/src/views/tutorial/templates/mytemplate.pt
+++ b/docs/tutorials/wiki/src/views/tutorial/templates/mytemplate.pt
@@ -6,9 +6,9 @@
   <meta name="keywords" content="python web application" />
   <meta name="description" content="pyramid web application" />
   <link rel="shortcut icon" href="/static/favicon.ico" />
+  <link rel="stylesheet" href="/static/pylons.css" type="text/css" media="screen" charset="utf-8" />
   <link rel="stylesheet" href="http://static.pylonsproject.org/fonts/nobile/stylesheet.css" media="screen" />
   <link rel="stylesheet" href="http://static.pylonsproject.org/fonts/neuton/stylesheet.css" media="screen" />
-  <link rel="stylesheet" href="/static/pylons.css" type="text/css" media="screen" charset="utf-8" />
   <!--[if lte IE 6]>
   <link rel="stylesheet" href="/static/ie6.css" type="text/css" media="screen" charset="utf-8" />
   <![endif]-->
@@ -41,7 +41,7 @@
           <h2>Pyramid links</h2>
           <ul class="links">
             <li>
-              <a href="http://pylonsproject.org">Pylons Website</a>
+              <a href="http://pylonsproject.org/">Pylons Website</a>
             </li>
             <li>
               <a href="http://docs.pylonsproject.org/projects/pyramid/current/#narrative-documentation">Narrative Documentation</a>
@@ -70,7 +70,7 @@
     </div>
   </div>
   <div id="footer">
-    <div class="footer">&copy; Copyright 2008-2011, Agendaless Consulting.</div>
+    <div class="footer">&copy; Copyright 2008-2012, Agendaless Consulting.</div>
   </div>
 </body>
 </html>
diff --git a/docs/tutorials/wiki/src/views/tutorial/tests.py b/docs/tutorials/wiki/src/views/tutorial/tests.py
index 9eac2a432..663c9f405 100644
--- a/docs/tutorials/wiki/src/views/tutorial/tests.py
+++ b/docs/tutorials/wiki/src/views/tutorial/tests.py
@@ -5,7 +5,7 @@ from pyramid import testing
 class PageModelTests(unittest.TestCase):
 
     def _getTargetClass(self):
-        from tutorial.models import Page
+        from .models import Page
         return Page
 
     def _makeOne(self, data=u'some data'):
@@ -14,11 +14,11 @@ class PageModelTests(unittest.TestCase):
     def test_constructor(self):
         instance = self._makeOne()
         self.assertEqual(instance.data, u'some data')
-        
+
 class WikiModelTests(unittest.TestCase):
 
     def _getTargetClass(self):
-        from tutorial.models import Wiki
+        from .models import Wiki
         return Wiki
 
     def _makeOne(self):
@@ -30,8 +30,9 @@ class WikiModelTests(unittest.TestCase):
         self.assertEqual(wiki.__name__, None)
 
 class AppmakerTests(unittest.TestCase):
+
     def _callFUT(self, zodb_root):
-        from tutorial.models import appmaker
+        from .models import appmaker
         return appmaker(zodb_root)
 
     def test_it(self):
@@ -42,7 +43,7 @@ class AppmakerTests(unittest.TestCase):
 
 class ViewWikiTests(unittest.TestCase):
     def test_it(self):
-        from tutorial.views import view_wiki
+        from .views import view_wiki
         context = testing.DummyResource()
         request = testing.DummyRequest()
         response = view_wiki(context, request)
@@ -50,7 +51,7 @@ class ViewWikiTests(unittest.TestCase):
 
 class ViewPageTests(unittest.TestCase):
     def _callFUT(self, context, request):
-        from tutorial.views import view_page
+        from .views import view_page
         return view_page(context, request)
 
     def test_it(self):
@@ -63,7 +64,7 @@ class ViewPageTests(unittest.TestCase):
         info = self._callFUT(context, request)
         self.assertEqual(info['page'], context)
         self.assertEqual(
-            info['content'], 
+            info['content'],
             '<div class="document">\n'
             '<p>Hello <a href="http://example.com/add_page/CruelWorld">'
             'CruelWorld</a> '
@@ -72,11 +73,11 @@ class ViewPageTests(unittest.TestCase):
             '</p>\n</div>\n')
         self.assertEqual(info['edit_url'],
                          'http://example.com/thepage/edit_page')
-        
-    
+
+
 class AddPageTests(unittest.TestCase):
     def _callFUT(self, context, request):
-        from tutorial.views import add_page
+        from .views import add_page
         return add_page(context, request)
 
     def test_it_notsubmitted(self):
@@ -88,7 +89,7 @@ class AddPageTests(unittest.TestCase):
         self.assertEqual(
             info['save_url'],
             request.resource_url(context, 'add_page', 'AnotherPage'))
-        
+
     def test_it_submitted(self):
         context = testing.DummyResource()
         request = testing.DummyRequest({'form.submitted':True,
@@ -102,7 +103,7 @@ class AddPageTests(unittest.TestCase):
 
 class EditPageTests(unittest.TestCase):
     def _callFUT(self, context, request):
-        from tutorial.views import edit_page
+        from .views import edit_page
         return edit_page(context, request)
 
     def test_it_notsubmitted(self):
@@ -112,7 +113,7 @@ class EditPageTests(unittest.TestCase):
         self.assertEqual(info['page'], context)
         self.assertEqual(info['save_url'],
                          request.resource_url(context, 'edit_page'))
-        
+
     def test_it_submitted(self):
         context = testing.DummyResource()
         request = testing.DummyRequest({'form.submitted':True,
diff --git a/docs/tutorials/wiki/src/views/tutorial/views.py b/docs/tutorials/wiki/src/views/tutorial/views.py
index b0c15297f..61517c31d 100644
--- a/docs/tutorials/wiki/src/views/tutorial/views.py
+++ b/docs/tutorials/wiki/src/views/tutorial/views.py
@@ -56,5 +56,5 @@ def edit_page(context, request):
         context.data = request.params['body']
         return HTTPFound(location = request.resource_url(context))
 
-    return dict(page = context,
-                save_url = request.resource_url(context, 'edit_page'))
+    return dict(page=context,
+                save_url=request.resource_url(context, 'edit_page'))
diff --git a/docs/tutorials/wiki/tests.rst b/docs/tutorials/wiki/tests.rst
index ebb4d93dc..49bc780e8 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
 ===============
@@ -17,8 +14,8 @@ We write tests for the model classes and the appmaker.  Changing
 ``tests.py``, we'll write a separate test class for each model class, and
 we'll write a test class for the ``appmaker``.
 
-To do so, we'll retain the ``tutorial.tests.ViewTests`` class provided as a
-result of the ``zodb`` project generator.  We'll add three test
+To do so, we'll retain the ``tutorial.tests.ViewTests`` class that was
+generated as part of the ``zodb`` scaffold.  We'll add three test
 classes: one for the ``Page`` model named ``PageModelTests``, one for the
 ``Wiki`` model named ``WikiModelTests``, and one for the appmaker named
 ``AppmakerTests``.
@@ -51,8 +48,8 @@ below:
    :linenos:
    :language: python
 
-Run the Tests
-=============
+Running the Tests
+=================
 
 We can run these tests by using ``setup.py test`` in the same way we did in
 :ref:`running_tests`.  However, first we must edit our ``setup.py`` to
@@ -62,7 +59,8 @@ Change the ``requires`` list in ``setup.py`` to include ``WebTest``.
 .. literalinclude:: src/tests/setup.py
    :linenos:
    :language: python
-   :lines: 9-18
+   :lines: 9-19
+   :emphasize-lines: 10
 
 After we've added a dependency on WebTest in ``setup.py``, we need to rerun
 ``setup.py develop`` to get WebTest installed into our virtualenv.  Assuming
diff --git a/docs/tutorials/wiki2/authorization.rst b/docs/tutorials/wiki2/authorization.rst
index 1ddf8c82d..5ede26920 100644
--- a/docs/tutorials/wiki2/authorization.rst
+++ b/docs/tutorials/wiki2/authorization.rst
@@ -14,7 +14,7 @@ anyone with access to the server to view pages.
 
 We will also add a login page and a logout link on all the
 pages.  The login page will be shown when a user is denied
-access to any of the views that require a permission, instead of
+access to any of the views that require permission, instead of
 a default "403 Forbidden" page.
 
 We will implement the access control with the following steps:
@@ -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
 --------------
@@ -62,7 +59,7 @@ 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'],
+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
@@ -86,7 +83,7 @@ statement at the head:
 Add the following class definition:
 
 .. literalinclude:: src/authorization/tutorial/models.py
-   :lines: 35-39
+   :lines: 36-40
    :linenos:
    :language: python
 
@@ -112,7 +109,7 @@ parameter to our :term:`Configurator` constructor, that points to
 the class we created above:
 
 .. literalinclude:: src/authorization/tutorial/__init__.py
-   :lines: 23-24
+   :lines: 24-25
    :linenos:
    :emphasize-lines: 2
    :language: python
@@ -144,19 +141,19 @@ add these import statements:
 Now add those policies to the configuration:
 
 .. literalinclude:: src/authorization/tutorial/__init__.py
-   :lines: 20-26
+   :lines: 21-27
    :linenos:
    :emphasize-lines: 1-3,6-7
    :language: python
 
 (Only the highlighted lines need to be added.)
 
-We are enabling an ``AuthTktAuthenticationPolicy``, it is based in an
-auth ticket that may be included in the request, and an
-``ACLAuthorizationPolicy`` that uses an ACL to determine the allow or deny
-outcome for a view.
+We are enabling an ``AuthTktAuthenticationPolicy``, which is based in an
+auth ticket that may be included in the request.
+We are also enabling an ``ACLAuthorizationPolicy``, which uses an ACL to
+determine the *allow* or *deny* outcome for a view.
 
-Note that the :class:`pyramid.authentication.AuthTktAuthenticationPolicy`
+Note that the :class:`~pyramid.authentication.AuthTktAuthenticationPolicy`
 constructor accepts two arguments: ``secret`` and ``callback``.  ``secret`` is
 a string representing an encryption key used by the "authentication ticket"
 machinery represented by this policy: it is required.  The ``callback`` is the
@@ -206,7 +203,7 @@ Go back to ``tutorial/tutorial/__init__.py`` and add these two
 routes:
 
 .. literalinclude:: src/authorization/tutorial/__init__.py
-   :lines: 29-30
+   :lines: 30-31
    :linenos:
    :language: python
 
@@ -303,9 +300,8 @@ like this:
 
 (Only the highlighted line needs 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.
+The :meth:`~pyramid.security.authenticated_userid` method will return None
+if the user is not authenticated.
 
 Add a "Logout" link when logged in
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -333,7 +329,7 @@ when we're done:
 
 .. literalinclude:: src/authorization/tutorial/__init__.py
    :linenos:
-   :emphasize-lines: 2-3,7,23-24,20-26,29-30
+   :emphasize-lines: 2-3,7,21-23,25-27,30-31
    :language: python
 
 (Only the highlighted lines need to be added.)
@@ -343,7 +339,7 @@ when we're done:
 
 .. literalinclude:: src/authorization/tutorial/models.py
    :linenos:
-   :emphasize-lines: 1-4,35-39
+   :emphasize-lines: 1-4,36-40
    :language: python
 
 (Only the highlighted lines need to be added.)
diff --git a/docs/tutorials/wiki2/background.rst b/docs/tutorials/wiki2/background.rst
index 9933adc27..1f9582903 100644
--- a/docs/tutorials/wiki2/background.rst
+++ b/docs/tutorials/wiki2/background.rst
@@ -11,9 +11,8 @@ 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.
 
-.. warning::
+.. note::
 
-  This tutorial has been written for Python 2.  It is unlikely to work
-  without modification under Python 3.
+  This tutorial runs on both Python 2 and 3 without modification.
 
 Have fun!
diff --git a/docs/tutorials/wiki2/basiclayout.rst b/docs/tutorials/wiki2/basiclayout.rst
index dbd130c36..68be4ee7c 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``
 ----------------------------------------------
@@ -45,24 +42,23 @@ When you invoke the ``pserve development.ini`` command, the ``main`` function
 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 SQLAlchemy database engine using
+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://``):
 
    .. literalinclude:: src/basiclayout/tutorial/__init__.py
-      :lines: 12
-      :linenos:
+      :lines: 13
       :language: py
 
 ``main`` then initializes our SQLAlchemy session object, passing it the
 engine:
 
    .. literalinclude:: src/basiclayout/tutorial/__init__.py
-      :lines: 13
+      :lines: 14
       :language: py
 
-``main`` subsequently initializes our SQLAlchemy declarative Base object,
+``main`` subsequently initializes our SQLAlchemy declarative ``Base`` object,
 assigning the engine we created to the ``bind`` attribute of it's
 ``metadata`` object.  This allows table definitions done imperatively
 (instead of declaratively, via a class statement) to work.  We won't use any
@@ -71,13 +67,13 @@ forgotten about this tutorial, you won't be left scratching your head when it
 doesn't work.
 
    .. literalinclude:: src/basiclayout/tutorial/__init__.py
-      :lines: 14
+      :lines: 15
       :language: py
 
 The next step of ``main`` is to construct a :term:`Configurator` object:
 
    .. literalinclude:: src/basiclayout/tutorial/__init__.py
-      :lines: 15
+      :lines: 16
       :language: py
 
 ``settings`` is passed to the Configurator as a keyword argument with the
@@ -90,15 +86,15 @@ deployment-related values such as ``pyramid.reload_templates``,
 two arguments: ``static`` (the name), and ``static`` (the path):
 
    .. literalinclude:: src/basiclayout/tutorial/__init__.py
-      :lines: 16
+      :lines: 17
       :language: py
 
 This registers a static resource view which will match any URL that starts
-with the prefix ``/static`` (by virtue of the first argument to add_static
-view).  This will serve up static resources for us from within the ``static``
-directory of our ``tutorial`` package, in this case, via
+with the prefix ``/static`` (by virtue of the first argument to
+``add_static_view``).  This will serve up static resources for us from within
+the ``static`` directory of our ``tutorial`` package, in this case, via
 ``http://localhost:6543/static/`` and below (by virtue of the second argument
-to add_static_view).  With this declaration, we're saying that any URL that
+to ``add_static_view``).  With this declaration, we're saying that any URL that
 starts with ``/static`` should go to the static view; any remainder of its
 path (e.g. the ``/foo`` in ``/static/foo``) will be used to compose a path to
 a static file resource, such as a CSS file.
@@ -108,20 +104,21 @@ via the :meth:`pyramid.config.Configurator.add_route` method that will be
 used when the URL is ``/``:
 
    .. literalinclude:: src/basiclayout/tutorial/__init__.py
-      :lines: 17
+      :lines: 18
       :language: py
 
 Since this route has a ``pattern`` equalling ``/`` it is the route that will
 be matched when the URL ``/`` is visited, e.g. ``http://localhost:6543/``.
 
-``main`` next calls the ``scan`` method of the configurator, which will
-recursively scan our ``tutorial`` package, looking for ``@view_config`` (and
+``main`` next calls the ``scan`` method of the configurator
+(:meth:`pyramid.config.Configurator.scan`), which will recursively scan our
+``tutorial`` package, looking for ``@view_config`` (and
 other special) decorators.  When it finds a ``@view_config`` decorator, a
 view configuration will be registered, which will allow one of our
 application URLs to be mapped to some code.
 
    .. literalinclude:: src/basiclayout/tutorial/__init__.py
-      :lines: 18
+      :lines: 19
       :language: py
 
 Finally, ``main`` is finished configuring things, so it uses the
@@ -129,7 +126,7 @@ Finally, ``main`` is finished configuring things, so it uses the
 :term:`WSGI` application:
 
    .. literalinclude:: src/basiclayout/tutorial/__init__.py
-      :lines: 19
+      :lines: 20
       :language: py
 
 View Declarations via ``views.py``
@@ -171,6 +168,12 @@ application.  Without being processed by ``scan``, the decorator effectively
 does nothing.  ``@view_config`` is inert without being detected via a
 :term:`scan`.
 
+The sample ``my_view()`` created by the scaffold uses a ``try:`` and ``except:``
+clause, to detect if there is a problem accessing the project database and
+provide an alternate error response.  That response will include the text
+shown at the end of the file, which will be displayed in the browser to
+inform the user about possible actions to take to solve the problem.
+
 Content Models with ``models.py``
 ---------------------------------
 
@@ -191,11 +194,10 @@ Let's examine this in detail. First, we need some imports to support later code:
       :linenos:
       :language: py
 
-Next we set up a SQLAlchemy "DBSession" object:
+Next we set up a SQLAlchemy ``DBSession`` object:
 
    .. literalinclude:: src/basiclayout/tutorial/models.py
       :lines: 16
-      :linenos:
       :language: py
 
 ``scoped_session`` and ``sessionmaker`` are standard SQLAlchemy helpers.
@@ -224,8 +226,9 @@ To give a simple example of a  model class, we define one named ``MyModel``:
       :linenos:
       :language: py
 
-Our example model has an ``__init__`` that takes a two arguments (``name``,
-and ``value``).  It stores these values as ``self.name`` and ``self.value``
+Our example model has an ``__init__`` method that takes a 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.
diff --git a/docs/tutorials/wiki2/definingmodels.rst b/docs/tutorials/wiki2/definingmodels.rst
index 1653faf4a..bd1cb00d7 100644
--- a/docs/tutorials/wiki2/definingmodels.rst
+++ b/docs/tutorials/wiki2/definingmodels.rst
@@ -2,20 +2,17 @@
 Defining the Domain Model
 =========================
 
-The first change we'll make to our stock pcreate-generated application will
+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``
 -----------------------------
 
 .. note::
 
-  There is nothing automagically special about the filename ``models.py``.  A
+  There is nothing special about the filename ``models.py``.  A
   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
@@ -27,11 +24,11 @@ following:
 .. literalinclude:: src/models/tutorial/models.py
    :linenos:
    :language: py
-   :emphasize-lines: 19-21,24,26,28
+   :emphasize-lines: 20-22,25,27,29
 
 (The highlighted lines are the ones that need to be changed.)
 
-The first thing we've done is to do is remove the stock ``MyModel`` class
+The first thing we've done is remove the stock ``MyModel`` class
 from the generated ``models.py`` file.  The ``MyModel`` class is only a
 sample and we're not going to use it.
 
@@ -46,8 +43,8 @@ this class inherits from an instance of
 
 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
+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
@@ -73,29 +70,19 @@ following:
 .. literalinclude:: src/models/tutorial/scripts/initializedb.py
    :linenos:
    :language: python
-   :emphasize-lines: 14,34
+   :emphasize-lines: 14,36
 
 (Only the highlighted lines need to be changed.)
 
-Reinitializing the Database
----------------------------
+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.  From the root of the
-``tutorial`` project, directory execute the following commands.
-
-On UNIX:
-
-.. code-block:: text
-
-   $ ../bin/initialize_tutorial_db development.ini
-
-On Windows:
-
-.. code-block:: text
-
-   c:\pyramidtut\tutorial> ..\Scripts\initialize_tutorial_db development.ini
+to both the models.py file and to the initializedb.py file.
+See :ref:`initialize_db_wiki2` for instructions.
 
 Success will look something like this::
 
diff --git a/docs/tutorials/wiki2/definingviews.rst b/docs/tutorials/wiki2/definingviews.rst
index a54996e3c..e83a88198 100644
--- a/docs/tutorials/wiki2/definingviews.rst
+++ b/docs/tutorials/wiki2/definingviews.rst
@@ -16,9 +16,6 @@ instance, if a call to :meth:`pyramid.config.Configurator.add_route` in
 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/>`_.
 
 Declaring Dependencies in Our ``setup.py`` File
 ===============================================
@@ -26,7 +23,7 @@ Declaring Dependencies in Our ``setup.py`` File
 The view code in our application will depend on a package which is not a
 dependency of the original "tutorial" application.  The original "tutorial"
 application was generated by the ``pcreate`` command; it doesn't know
-about our custom application requirements.  
+about our custom application requirements.
 
 We need to add a dependency on the ``docutils`` package to our ``tutorial``
 package's ``setup.py`` file by assigning this dependency to the ``requires`` parameter in ``setup()``.
@@ -123,14 +120,14 @@ the :class:`pyramid.interfaces.IResponse` interface like
 
 It uses the :meth:`pyramid.request.Request.route_url` API to construct a 
 URL to the ``FrontPage`` page (e.g. ``http://localhost:6543/FrontPage``), which 
-is used as the "location" of the HTTPFound response, forming an HTTP redirect.
+is used as the "location" of the ``HTTPFound`` response, forming an HTTP redirect.
 
 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
-the ``data`` attribute of a Page object) as HTML.  Then it substitutes an
+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.
 
@@ -139,12 +136,12 @@ compiled regular expression.
    :linenos:
    :language: python
 
-The curried ``check()`` function is used as the first argument to
+The ``check()`` function is used as the first argument to
 ``wikiwords.sub``, indicating that it should be called to provide a value for
 each WikiWord match found in the content.  If the wiki already contains a
 page with the matched WikiWord name, ``check()`` generates a view
 link to be used as the substitution value and returns it.  If the wiki does
-not already contain a page with with the matched WikiWord name, ``check()``
+not already contain a page with the matched WikiWord name, ``check()``
 generates an "add" link as the substitution value and returns it.
 
 As a result, the ``content`` variable is now a fully formed bit of HTML
@@ -181,6 +178,13 @@ the page we'd like to add.  If our add view is invoked via,
 e.g. ``http://localhost:6543/add_page/SomeName``, the value for
 ``'pagename'`` in the ``matchdict`` will be ``'SomeName'``.
 
+If the view execution *is* a result of a form submission (i.e. the expression
+``'form.submitted' in request.params`` is ``True``), we scrape the page body
+from the form data, create a Page object with this page body and the name
+taken from ``matchdict['pagename']``, and save it into the database using
+``DBSession.add``.  We then redirect back to the ``view_page`` view for the
+newly created page.
+
 If the view execution is *not* a result of a form submission (i.e. the
 expression ``'form.submitted' in request.params`` is ``False``), the view
 callable renders a template.  To do so, it generates a "save url" which the
@@ -191,13 +195,6 @@ in order to satisfy the edit form's desire to have *some* page object
 exposed as ``page``. :app:`Pyramid` will render the template associated
 with this view to a response.
 
-If the view execution *is* a result of a form submission (i.e. the expression
-``'form.submitted' in request.params`` is ``True``), we scrape the page body
-from the form data, create a Page object with this page body and the name
-taken from ``matchdict['pagename']``, and save it into the database using
-``DBSession.add``.  We then redirect back to the ``view_page`` view for the
-newly created page.
-
 The ``edit_page`` view function
 -------------------------------
 
@@ -212,17 +209,17 @@ matching the name of the page the user wants to edit.
    :linenos:
    :language: python
 
-If the view execution is *not* a result of a form submission (i.e. the
-expression ``'form.submitted' in request.params`` is ``False``), the view
-simply renders the edit form, passing the page object and a ``save_url``
-which will be used as the action of the generated form.
-
 If the view execution *is* a result of a form submission (i.e. the expression
 ``'form.submitted' in request.params`` is ``True``), the view grabs the
 ``body`` element of the request parameters and sets it as the ``data``
 attribute of the page object.  It then redirects to the ``view_page`` view
 of the wiki page.
 
+If the view execution is *not* a result of a form submission (i.e. the
+expression ``'form.submitted' in request.params`` is ``False``), the view
+simply renders the edit form, passing the page object and a ``save_url``
+which will be used as the action of the generated form.
+
 Adding Templates
 ================
 
@@ -342,7 +339,7 @@ something like:
 .. literalinclude:: src/views/tutorial/__init__.py
    :linenos:
    :language: python
-   :emphasize-lines: 17-20
+   :emphasize-lines: 18-21
 
 (The highlighted lines are the ones that need to be added or edited.)
 
@@ -358,7 +355,7 @@ each of the following URLs, check that the result is as expected:
   of the FrontPage page object.
 
 - ``http://localhost:6543/FrontPage`` in a browser invokes
-  the ``view_page`` view of the front page page object.
+  the ``view_page`` view of the front page object.
 
 - ``http://localhost:6543/FrontPage/edit_page`` in a browser
   invokes the edit view for the front page object.
@@ -366,7 +363,7 @@ each of the following URLs, check that the result is as expected:
 - ``http://localhost:6543/add_page/SomePageName`` in a
   browser invokes the add view for a page.
 
-- To generate an error, visit ``http://localhost:6543/add_page`` which
+- To generate an error, visit ``http://localhost:6543/foobars/edit_page`` which
   will generate a ``NoResultFound: No row was found for one()`` error.
   You'll see an interactive traceback facility provided 
   by :term:`pyramid_debugtoolbar`.
diff --git a/docs/tutorials/wiki2/design.rst b/docs/tutorials/wiki2/design.rst
index 6e41e00aa..c56d7fecf 100644
--- a/docs/tutorials/wiki2/design.rst
+++ b/docs/tutorials/wiki2/design.rst
@@ -9,7 +9,7 @@ tutorial.
 Overall
 -------
 
-We choose to use ``reStructuredText`` markup in the wiki text.  Translation
+We choose to use :term:`reStructuredText` markup in the wiki text.  Translation
 from reStructuredText to HTML is provided by the widely used ``docutils``
 Python module.  We will add this module in the dependency list on the project
 ``setup.py`` file.
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 6589a1557..9fa01d513 100644
--- a/docs/tutorials/wiki2/installation.rst
+++ b/docs/tutorials/wiki2/installation.rst
@@ -2,30 +2,22 @@
 Installation
 ============
 
-This tutorial assumes that Python and virtualenv are already installed
-and working in your system. If you need help setting this up, you should
-refer to the chapters on :ref:`installing_chapter`.
-
 Preparation
 ===========
 
-Please take the following steps to prepare for the tutorial.  The
-steps are slightly different depending on whether you're using UNIX or
-Windows.
+Follow the steps in :ref:`installing_chapter`, but name the virtualenv
+directory ``pyramidtut``.
 
 Preparation, UNIX
 -----------------
 
 #. Install SQLite3 and its development packages if you don't already
    have them installed.  Usually this is via your system's package
-   manager.  For example, on a Debian Linux system, do ``sudo apt-get
-   install libsqlite3-dev``.
-
-#. Use your Python's virtualenv to make a workspace:
+   manager.  On a Debian system, this would be:
 
    .. code-block:: text
 
-      $ path/to/my/Python-2.6/bin/virtualenv --no-site-packages pyramidtut
+      $ sudo apt-get install libsqlite3-dev
 
 #. Switch to the ``pyramidtut`` directory:
 
@@ -33,35 +25,16 @@ Preparation, UNIX
 
       $ cd pyramidtut
 
-#. Use ``easy_install`` to get :app:`Pyramid` and its direct
-   dependencies installed:
-
-   .. code-block:: text
-
-      $ bin/easy_install pyramid
 
 Preparation, Windows
 --------------------
 
-#. Use your Python's virtualenv to make a workspace:
-
-   .. code-block:: text
-
-      c:\> c:\Python26\Scripts\virtualenv --no-site-packages pyramidtut
-
 #. Switch to the ``pyramidtut`` directory:
 
    .. code-block:: text
 
       c:\> cd pyramidtut
 
-#. Use ``easy_install`` to get :app:`Pyramid` and its direct
-   dependencies installed:
-
-   .. code-block:: text
-
-      c:\pyramidtut> Scripts\easy_install pyramid
-
 .. _sql_making_a_project:
 
 Making a Project
@@ -93,14 +66,17 @@ 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"
 ============================================
 
 In order to do development on the project easily, you must "register"
 the project as a development egg in your workspace using the
-``setup.py develop`` command.  In order to do so, cd to the "tutorial"
+``setup.py develop`` command.  In order to do so, cd to the `tutorial`
 directory you created in :ref:`sql_making_a_project`, and run the
-"setup.py develop" command using virtualenv Python interpreter.
+``setup.py develop`` command using the virtualenv Python interpreter.
 
 On UNIX:
 
@@ -158,8 +134,8 @@ test`` does but provides additional "coverage" information, exposing
 which lines of your project are "covered" (or not covered) by the
 tests.
 
-To get this functionality working, we'll need to install a couple of
-other packages into our ``virtualenv``: ``nose`` and ``coverage``:
+To get this functionality working, we'll need to install the ``nose`` and
+``coverage`` packages into our ``virtualenv``:
 
 On UNIX:
 
@@ -186,7 +162,7 @@ On Windows:
 
 .. code-block:: text
 
-   c:\pyramidtut\tutorial> ..\Scripts\nosetests --cover-package=tutorial ^
+   c:\pyramidtut\tutorial> ..\Scripts\nosetests --cover-package=tutorial \
          --cover-erase --with-coverage
 
 If successful, you will see output something like this::
@@ -208,6 +184,9 @@ If successful, you will see output something like this::
 
 Looks like our package doesn't quite have 100% test coverage.
 
+
+.. _initialize_db_wiki2:
+
 Initializing the Database
 =========================
 
@@ -303,6 +282,9 @@ the following assumptions:
 
 - you are willing to use :term:`url dispatch` to map URLs to code.
 
+- you want to use ``ZopeTransactionExtension`` and ``pyramid_tm`` to scope
+  sessions to requests
+
 .. note::
 
    :app:`Pyramid` supports any persistent storage mechanism (e.g. object
diff --git a/docs/tutorials/wiki2/src/authorization/README.txt b/docs/tutorials/wiki2/src/authorization/README.txt
index 6f851e9b7..141851285 100644
--- a/docs/tutorials/wiki2/src/authorization/README.txt
+++ b/docs/tutorials/wiki2/src/authorization/README.txt
@@ -1 +1,14 @@
 tutorial README
+==================
+
+Getting Started
+---------------
+
+- cd <directory containing this file>
+
+- $venv/bin/python setup.py develop
+
+- $venv/bin/initialize_tutorial_db development.ini
+
+- $venv/bin/pserve development.ini
+
diff --git a/docs/tutorials/wiki2/src/authorization/development.ini b/docs/tutorials/wiki2/src/authorization/development.ini
index eb2f878c5..a9d53b296 100644
--- a/docs/tutorials/wiki2/src/authorization/development.ini
+++ b/docs/tutorials/wiki2/src/authorization/development.ini
@@ -1,3 +1,8 @@
+###
+# app configuration
+# http://docs.pylonsproject.org/projects/pyramid/en/latest/narr/environment.html
+###
+
 [app:main]
 use = egg:tutorial
 
@@ -12,12 +17,23 @@ pyramid.includes =
 
 sqlalchemy.url = sqlite:///%(here)s/tutorial.sqlite
 
+# By default, the toolbar only appears for clients from IP addresses
+# '127.0.0.1' and '::1'.
+# debugtoolbar.hosts = 127.0.0.1 ::1
+
+###
+# wsgi server configuration
+###
+
 [server:main]
 use = egg:waitress#main
 host = 0.0.0.0
 port = 6543
 
-# Begin logging configuration
+###
+# logging configuration
+# http://docs.pylonsproject.org/projects/pyramid/en/latest/narr/logging.html
+###
 
 [loggers]
 keys = root, tutorial, sqlalchemy
@@ -53,5 +69,3 @@ formatter = generic
 
 [formatter_generic]
 format = %(asctime)s %(levelname)-5.5s [%(name)s][%(threadName)s] %(message)s
-
-# End logging configuration
diff --git a/docs/tutorials/wiki2/src/authorization/setup.py b/docs/tutorials/wiki2/src/authorization/setup.py
index 2fd051927..36668dd33 100644
--- a/docs/tutorials/wiki2/src/authorization/setup.py
+++ b/docs/tutorials/wiki2/src/authorization/setup.py
@@ -13,17 +13,17 @@ requires = [
     'pyramid_tm',
     'pyramid_debugtoolbar',
     'zope.sqlalchemy',
-    'docutils',
     'waitress',
+    'docutils',
     ]
 
 setup(name='tutorial',
       version='0.0',
       description='tutorial',
-      long_description=README + '\n\n' +  CHANGES,
+      long_description=README + '\n\n' + CHANGES,
       classifiers=[
         "Programming Language :: Python",
-        "Framework :: Pylons",
+        "Framework :: Pyramid",
         "Topic :: Internet :: WWW/HTTP",
         "Topic :: Internet :: WWW/HTTP :: WSGI :: Application",
         ],
@@ -35,8 +35,8 @@ setup(name='tutorial',
       include_package_data=True,
       zip_safe=False,
       test_suite='tutorial',
-      install_requires = requires,
-      entry_points = """\
+      install_requires=requires,
+      entry_points="""\
       [paste.app_factory]
       main = tutorial:main
       [console_scripts]
diff --git a/docs/tutorials/wiki2/src/authorization/tutorial/__init__.py b/docs/tutorials/wiki2/src/authorization/tutorial/__init__.py
index 76071173a..d08e55bf9 100644
--- a/docs/tutorials/wiki2/src/authorization/tutorial/__init__.py
+++ b/docs/tutorials/wiki2/src/authorization/tutorial/__init__.py
@@ -11,6 +11,7 @@ from .models import (
     Base,
     )
 
+
 def main(global_config, **settings):
     """ This function returns a Pyramid WSGI application.
     """
@@ -33,4 +34,3 @@ def main(global_config, **settings):
     config.add_route('edit_page', '/{pagename}/edit_page')
     config.scan()
     return config.make_wsgi_app()
-
diff --git a/docs/tutorials/wiki2/src/authorization/tutorial/models.py b/docs/tutorials/wiki2/src/authorization/tutorial/models.py
index c3bdcbea5..91e5a0019 100644
--- a/docs/tutorials/wiki2/src/authorization/tutorial/models.py
+++ b/docs/tutorials/wiki2/src/authorization/tutorial/models.py
@@ -21,6 +21,7 @@ from zope.sqlalchemy import ZopeTransactionExtension
 DBSession = scoped_session(sessionmaker(extension=ZopeTransactionExtension()))
 Base = declarative_base()
 
+
 class Page(Base):
     """ The SQLAlchemy declarative model class for a Page object. """
     __tablename__ = 'pages'
diff --git a/docs/tutorials/wiki2/src/authorization/tutorial/scripts/initializedb.py b/docs/tutorials/wiki2/src/authorization/tutorial/scripts/initializedb.py
index 03188e8ad..092e359ce 100644
--- a/docs/tutorials/wiki2/src/authorization/tutorial/scripts/initializedb.py
+++ b/docs/tutorials/wiki2/src/authorization/tutorial/scripts/initializedb.py
@@ -15,12 +15,14 @@ from ..models import (
     Base,
     )
 
+
 def usage(argv):
     cmd = os.path.basename(argv[0])
     print('usage: %s <config_uri>\n'
-          '(example: "%s development.ini")' % (cmd, cmd)) 
+          '(example: "%s development.ini")' % (cmd, cmd))
     sys.exit(1)
 
+
 def main(argv=sys.argv):
     if len(argv) != 2:
         usage(argv)
diff --git a/docs/tutorials/wiki2/src/authorization/tutorial/tests.py b/docs/tutorials/wiki2/src/authorization/tutorial/tests.py
index 31d2dc6d5..5dcee127b 100644
--- a/docs/tutorials/wiki2/src/authorization/tutorial/tests.py
+++ b/docs/tutorials/wiki2/src/authorization/tutorial/tests.py
@@ -1,5 +1,6 @@
 import unittest
 import transaction
+
 from pyramid import testing
 
 def _initTestingDB():
diff --git a/docs/tutorials/wiki2/src/basiclayout/README.txt b/docs/tutorials/wiki2/src/basiclayout/README.txt
index 6f851e9b7..141851285 100644
--- a/docs/tutorials/wiki2/src/basiclayout/README.txt
+++ b/docs/tutorials/wiki2/src/basiclayout/README.txt
@@ -1 +1,14 @@
 tutorial README
+==================
+
+Getting Started
+---------------
+
+- cd <directory containing this file>
+
+- $venv/bin/python setup.py develop
+
+- $venv/bin/initialize_tutorial_db development.ini
+
+- $venv/bin/pserve development.ini
+
diff --git a/docs/tutorials/wiki2/src/basiclayout/development.ini b/docs/tutorials/wiki2/src/basiclayout/development.ini
index eb2f878c5..a9d53b296 100644
--- a/docs/tutorials/wiki2/src/basiclayout/development.ini
+++ b/docs/tutorials/wiki2/src/basiclayout/development.ini
@@ -1,3 +1,8 @@
+###
+# app configuration
+# http://docs.pylonsproject.org/projects/pyramid/en/latest/narr/environment.html
+###
+
 [app:main]
 use = egg:tutorial
 
@@ -12,12 +17,23 @@ pyramid.includes =
 
 sqlalchemy.url = sqlite:///%(here)s/tutorial.sqlite
 
+# By default, the toolbar only appears for clients from IP addresses
+# '127.0.0.1' and '::1'.
+# debugtoolbar.hosts = 127.0.0.1 ::1
+
+###
+# wsgi server configuration
+###
+
 [server:main]
 use = egg:waitress#main
 host = 0.0.0.0
 port = 6543
 
-# Begin logging configuration
+###
+# logging configuration
+# http://docs.pylonsproject.org/projects/pyramid/en/latest/narr/logging.html
+###
 
 [loggers]
 keys = root, tutorial, sqlalchemy
@@ -53,5 +69,3 @@ formatter = generic
 
 [formatter_generic]
 format = %(asctime)s %(levelname)-5.5s [%(name)s][%(threadName)s] %(message)s
-
-# End logging configuration
diff --git a/docs/tutorials/wiki2/src/basiclayout/production.ini b/docs/tutorials/wiki2/src/basiclayout/production.ini
index 4684d2f7a..fa94c1b3e 100644
--- a/docs/tutorials/wiki2/src/basiclayout/production.ini
+++ b/docs/tutorials/wiki2/src/basiclayout/production.ini
@@ -1,3 +1,8 @@
+###
+# app configuration
+# http://docs.pylonsproject.org/projects/pyramid/en/latest/narr/environment.html
+###
+
 [app:main]
 use = egg:tutorial
 
@@ -16,7 +21,10 @@ use = egg:waitress#main
 host = 0.0.0.0
 port = 6543
 
-# Begin logging configuration
+###
+# logging configuration
+# http://docs.pylonsproject.org/projects/pyramid/en/latest/narr/logging.html
+###
 
 [loggers]
 keys = root, tutorial, sqlalchemy
@@ -52,5 +60,3 @@ formatter = generic
 
 [formatter_generic]
 format = %(asctime)s %(levelname)-5.5s [%(name)s][%(threadName)s] %(message)s
-
-# End logging configuration
diff --git a/docs/tutorials/wiki2/src/basiclayout/setup.py b/docs/tutorials/wiki2/src/basiclayout/setup.py
index 050de7299..a09bf756a 100644
--- a/docs/tutorials/wiki2/src/basiclayout/setup.py
+++ b/docs/tutorials/wiki2/src/basiclayout/setup.py
@@ -19,10 +19,10 @@ requires = [
 setup(name='tutorial',
       version='0.0',
       description='tutorial',
-      long_description=README + '\n\n' +  CHANGES,
+      long_description=README + '\n\n' + CHANGES,
       classifiers=[
         "Programming Language :: Python",
-        "Framework :: Pylons",
+        "Framework :: Pyramid",
         "Topic :: Internet :: WWW/HTTP",
         "Topic :: Internet :: WWW/HTTP :: WSGI :: Application",
         ],
@@ -34,12 +34,11 @@ setup(name='tutorial',
       include_package_data=True,
       zip_safe=False,
       test_suite='tutorial',
-      install_requires = requires,
-      entry_points = """\
+      install_requires=requires,
+      entry_points="""\
       [paste.app_factory]
       main = tutorial:main
       [console_scripts]
       initialize_tutorial_db = tutorial.scripts.initializedb:main
       """,
       )
-
diff --git a/docs/tutorials/wiki2/src/basiclayout/tutorial/__init__.py b/docs/tutorials/wiki2/src/basiclayout/tutorial/__init__.py
index e39f619ed..aac7c5e69 100644
--- a/docs/tutorials/wiki2/src/basiclayout/tutorial/__init__.py
+++ b/docs/tutorials/wiki2/src/basiclayout/tutorial/__init__.py
@@ -6,6 +6,7 @@ from .models import (
     Base,
     )
 
+
 def main(global_config, **settings):
     """ This function returns a Pyramid WSGI application.
     """
@@ -17,4 +18,3 @@ def main(global_config, **settings):
     config.add_route('home', '/')
     config.scan()
     return config.make_wsgi_app()
-
diff --git a/docs/tutorials/wiki2/src/basiclayout/tutorial/models.py b/docs/tutorials/wiki2/src/basiclayout/tutorial/models.py
index b6ac15429..aeeb9df64 100644
--- a/docs/tutorials/wiki2/src/basiclayout/tutorial/models.py
+++ b/docs/tutorials/wiki2/src/basiclayout/tutorial/models.py
@@ -16,6 +16,7 @@ from zope.sqlalchemy import ZopeTransactionExtension
 DBSession = scoped_session(sessionmaker(extension=ZopeTransactionExtension()))
 Base = declarative_base()
 
+
 class MyModel(Base):
     __tablename__ = 'models'
     id = Column(Integer, primary_key=True)
@@ -25,4 +26,3 @@ class MyModel(Base):
     def __init__(self, name, value):
         self.name = name
         self.value = value
-
diff --git a/docs/tutorials/wiki2/src/basiclayout/tutorial/scripts/initializedb.py b/docs/tutorials/wiki2/src/basiclayout/tutorial/scripts/initializedb.py
index 0e828465f..66feb3008 100644
--- a/docs/tutorials/wiki2/src/basiclayout/tutorial/scripts/initializedb.py
+++ b/docs/tutorials/wiki2/src/basiclayout/tutorial/scripts/initializedb.py
@@ -15,12 +15,14 @@ from ..models import (
     Base,
     )
 
+
 def usage(argv):
     cmd = os.path.basename(argv[0])
     print('usage: %s <config_uri>\n'
-          '(example: "%s development.ini")' % (cmd, cmd)) 
+          '(example: "%s development.ini")' % (cmd, cmd))
     sys.exit(1)
 
+
 def main(argv=sys.argv):
     if len(argv) != 2:
         usage(argv)
diff --git a/docs/tutorials/wiki2/src/basiclayout/tutorial/templates/mytemplate.pt b/docs/tutorials/wiki2/src/basiclayout/tutorial/templates/mytemplate.pt
index fbfa9870b..15ea6614f 100644
--- a/docs/tutorials/wiki2/src/basiclayout/tutorial/templates/mytemplate.pt
+++ b/docs/tutorials/wiki2/src/basiclayout/tutorial/templates/mytemplate.pt
@@ -70,7 +70,7 @@
     </div>
   </div>
   <div id="footer">
-    <div class="footer">&copy; Copyright 2008-2011, Agendaless Consulting.</div>
+    <div class="footer">&copy; Copyright 2008-2012, Agendaless Consulting.</div>
   </div>
 </body>
 </html>
diff --git a/docs/tutorials/wiki2/src/basiclayout/tutorial/tests.py b/docs/tutorials/wiki2/src/basiclayout/tutorial/tests.py
index 653d061e4..57a775e0a 100644
--- a/docs/tutorials/wiki2/src/basiclayout/tutorial/tests.py
+++ b/docs/tutorials/wiki2/src/basiclayout/tutorial/tests.py
@@ -5,6 +5,7 @@ from pyramid import testing
 
 from .models import DBSession
 
+
 class TestMyView(unittest.TestCase):
     def setUp(self):
         self.config = testing.setUp()
diff --git a/docs/tutorials/wiki2/src/basiclayout/tutorial/views.py b/docs/tutorials/wiki2/src/basiclayout/tutorial/views.py
index 3e6abf2c2..4cfcae4af 100644
--- a/docs/tutorials/wiki2/src/basiclayout/tutorial/views.py
+++ b/docs/tutorials/wiki2/src/basiclayout/tutorial/views.py
@@ -1,11 +1,35 @@
+from pyramid.response import Response
 from pyramid.view import view_config
 
+from sqlalchemy.exc import DBAPIError
+
 from .models import (
     DBSession,
     MyModel,
     )
 
+
 @view_config(route_name='home', renderer='templates/mytemplate.pt')
 def my_view(request):
-    one = DBSession.query(MyModel).filter(MyModel.name=='one').first()
-    return {'one':one, 'project':'tutorial'}
+    try:
+        one = DBSession.query(MyModel).filter(MyModel.name == 'one').first()
+    except DBAPIError:
+        return Response(conn_err_msg, content_type='text/plain', status_int=500)
+    return {'one': one, 'project': 'tutorial'}
+
+conn_err_msg = """\
+Pyramid is having a problem using your SQL database.  The problem
+might be caused by one of the following things:
+
+1.  You may need to run the "initialize_tutorial_db" script
+    to initialize your database tables.  Check your virtual 
+    environment's "bin" directory for this script and try to run it.
+
+2.  Your database server may not be running.  Check that the
+    database server referred to by the "sqlalchemy.url" setting in
+    your "development.ini" file is running.
+
+After you fix the problem, please restart the Pyramid application to
+try it again.
+"""
+
diff --git a/docs/tutorials/wiki2/src/models/README.txt b/docs/tutorials/wiki2/src/models/README.txt
index 6f851e9b7..141851285 100644
--- a/docs/tutorials/wiki2/src/models/README.txt
+++ b/docs/tutorials/wiki2/src/models/README.txt
@@ -1 +1,14 @@
 tutorial README
+==================
+
+Getting Started
+---------------
+
+- cd <directory containing this file>
+
+- $venv/bin/python setup.py develop
+
+- $venv/bin/initialize_tutorial_db development.ini
+
+- $venv/bin/pserve development.ini
+
diff --git a/docs/tutorials/wiki2/src/models/development.ini b/docs/tutorials/wiki2/src/models/development.ini
index eb2f878c5..a9d53b296 100644
--- a/docs/tutorials/wiki2/src/models/development.ini
+++ b/docs/tutorials/wiki2/src/models/development.ini
@@ -1,3 +1,8 @@
+###
+# app configuration
+# http://docs.pylonsproject.org/projects/pyramid/en/latest/narr/environment.html
+###
+
 [app:main]
 use = egg:tutorial
 
@@ -12,12 +17,23 @@ pyramid.includes =
 
 sqlalchemy.url = sqlite:///%(here)s/tutorial.sqlite
 
+# By default, the toolbar only appears for clients from IP addresses
+# '127.0.0.1' and '::1'.
+# debugtoolbar.hosts = 127.0.0.1 ::1
+
+###
+# wsgi server configuration
+###
+
 [server:main]
 use = egg:waitress#main
 host = 0.0.0.0
 port = 6543
 
-# Begin logging configuration
+###
+# logging configuration
+# http://docs.pylonsproject.org/projects/pyramid/en/latest/narr/logging.html
+###
 
 [loggers]
 keys = root, tutorial, sqlalchemy
@@ -53,5 +69,3 @@ formatter = generic
 
 [formatter_generic]
 format = %(asctime)s %(levelname)-5.5s [%(name)s][%(threadName)s] %(message)s
-
-# End logging configuration
diff --git a/docs/tutorials/wiki2/src/models/setup.py b/docs/tutorials/wiki2/src/models/setup.py
index 050de7299..a09bf756a 100644
--- a/docs/tutorials/wiki2/src/models/setup.py
+++ b/docs/tutorials/wiki2/src/models/setup.py
@@ -19,10 +19,10 @@ requires = [
 setup(name='tutorial',
       version='0.0',
       description='tutorial',
-      long_description=README + '\n\n' +  CHANGES,
+      long_description=README + '\n\n' + CHANGES,
       classifiers=[
         "Programming Language :: Python",
-        "Framework :: Pylons",
+        "Framework :: Pyramid",
         "Topic :: Internet :: WWW/HTTP",
         "Topic :: Internet :: WWW/HTTP :: WSGI :: Application",
         ],
@@ -34,12 +34,11 @@ setup(name='tutorial',
       include_package_data=True,
       zip_safe=False,
       test_suite='tutorial',
-      install_requires = requires,
-      entry_points = """\
+      install_requires=requires,
+      entry_points="""\
       [paste.app_factory]
       main = tutorial:main
       [console_scripts]
       initialize_tutorial_db = tutorial.scripts.initializedb:main
       """,
       )
-
diff --git a/docs/tutorials/wiki2/src/models/tutorial/__init__.py b/docs/tutorials/wiki2/src/models/tutorial/__init__.py
index e39f619ed..aac7c5e69 100644
--- a/docs/tutorials/wiki2/src/models/tutorial/__init__.py
+++ b/docs/tutorials/wiki2/src/models/tutorial/__init__.py
@@ -6,6 +6,7 @@ from .models import (
     Base,
     )
 
+
 def main(global_config, **settings):
     """ This function returns a Pyramid WSGI application.
     """
@@ -17,4 +18,3 @@ def main(global_config, **settings):
     config.add_route('home', '/')
     config.scan()
     return config.make_wsgi_app()
-
diff --git a/docs/tutorials/wiki2/src/models/tutorial/models.py b/docs/tutorials/wiki2/src/models/tutorial/models.py
index 499396c5b..9a078d757 100644
--- a/docs/tutorials/wiki2/src/models/tutorial/models.py
+++ b/docs/tutorials/wiki2/src/models/tutorial/models.py
@@ -16,6 +16,7 @@ from zope.sqlalchemy import ZopeTransactionExtension
 DBSession = scoped_session(sessionmaker(extension=ZopeTransactionExtension()))
 Base = declarative_base()
 
+
 class Page(Base):
     """ The SQLAlchemy declarative model class for a Page object. """
     __tablename__ = 'pages'
@@ -26,4 +27,3 @@ class Page(Base):
     def __init__(self, name, data):
         self.name = name
         self.data = data
-
diff --git a/docs/tutorials/wiki2/src/models/tutorial/scripts/initializedb.py b/docs/tutorials/wiki2/src/models/tutorial/scripts/initializedb.py
index 03188e8ad..092e359ce 100644
--- a/docs/tutorials/wiki2/src/models/tutorial/scripts/initializedb.py
+++ b/docs/tutorials/wiki2/src/models/tutorial/scripts/initializedb.py
@@ -15,12 +15,14 @@ from ..models import (
     Base,
     )
 
+
 def usage(argv):
     cmd = os.path.basename(argv[0])
     print('usage: %s <config_uri>\n'
-          '(example: "%s development.ini")' % (cmd, cmd)) 
+          '(example: "%s development.ini")' % (cmd, cmd))
     sys.exit(1)
 
+
 def main(argv=sys.argv):
     if len(argv) != 2:
         usage(argv)
diff --git a/docs/tutorials/wiki2/src/models/tutorial/tests.py b/docs/tutorials/wiki2/src/models/tutorial/tests.py
index 653d061e4..57a775e0a 100644
--- a/docs/tutorials/wiki2/src/models/tutorial/tests.py
+++ b/docs/tutorials/wiki2/src/models/tutorial/tests.py
@@ -5,6 +5,7 @@ from pyramid import testing
 
 from .models import DBSession
 
+
 class TestMyView(unittest.TestCase):
     def setUp(self):
         self.config = testing.setUp()
diff --git a/docs/tutorials/wiki2/src/models/tutorial/views.py b/docs/tutorials/wiki2/src/models/tutorial/views.py
index 3e6abf2c2..4cfcae4af 100644
--- a/docs/tutorials/wiki2/src/models/tutorial/views.py
+++ b/docs/tutorials/wiki2/src/models/tutorial/views.py
@@ -1,11 +1,35 @@
+from pyramid.response import Response
 from pyramid.view import view_config
 
+from sqlalchemy.exc import DBAPIError
+
 from .models import (
     DBSession,
     MyModel,
     )
 
+
 @view_config(route_name='home', renderer='templates/mytemplate.pt')
 def my_view(request):
-    one = DBSession.query(MyModel).filter(MyModel.name=='one').first()
-    return {'one':one, 'project':'tutorial'}
+    try:
+        one = DBSession.query(MyModel).filter(MyModel.name == 'one').first()
+    except DBAPIError:
+        return Response(conn_err_msg, content_type='text/plain', status_int=500)
+    return {'one': one, 'project': 'tutorial'}
+
+conn_err_msg = """\
+Pyramid is having a problem using your SQL database.  The problem
+might be caused by one of the following things:
+
+1.  You may need to run the "initialize_tutorial_db" script
+    to initialize your database tables.  Check your virtual 
+    environment's "bin" directory for this script and try to run it.
+
+2.  Your database server may not be running.  Check that the
+    database server referred to by the "sqlalchemy.url" setting in
+    your "development.ini" file is running.
+
+After you fix the problem, please restart the Pyramid application to
+try it again.
+"""
+
diff --git a/docs/tutorials/wiki2/src/tests/README.txt b/docs/tutorials/wiki2/src/tests/README.txt
index 6f851e9b7..141851285 100644
--- a/docs/tutorials/wiki2/src/tests/README.txt
+++ b/docs/tutorials/wiki2/src/tests/README.txt
@@ -1 +1,14 @@
 tutorial README
+==================
+
+Getting Started
+---------------
+
+- cd <directory containing this file>
+
+- $venv/bin/python setup.py develop
+
+- $venv/bin/initialize_tutorial_db development.ini
+
+- $venv/bin/pserve development.ini
+
diff --git a/docs/tutorials/wiki2/src/tests/development.ini b/docs/tutorials/wiki2/src/tests/development.ini
index eb2f878c5..a9d53b296 100644
--- a/docs/tutorials/wiki2/src/tests/development.ini
+++ b/docs/tutorials/wiki2/src/tests/development.ini
@@ -1,3 +1,8 @@
+###
+# app configuration
+# http://docs.pylonsproject.org/projects/pyramid/en/latest/narr/environment.html
+###
+
 [app:main]
 use = egg:tutorial
 
@@ -12,12 +17,23 @@ pyramid.includes =
 
 sqlalchemy.url = sqlite:///%(here)s/tutorial.sqlite
 
+# By default, the toolbar only appears for clients from IP addresses
+# '127.0.0.1' and '::1'.
+# debugtoolbar.hosts = 127.0.0.1 ::1
+
+###
+# wsgi server configuration
+###
+
 [server:main]
 use = egg:waitress#main
 host = 0.0.0.0
 port = 6543
 
-# Begin logging configuration
+###
+# logging configuration
+# http://docs.pylonsproject.org/projects/pyramid/en/latest/narr/logging.html
+###
 
 [loggers]
 keys = root, tutorial, sqlalchemy
@@ -53,5 +69,3 @@ formatter = generic
 
 [formatter_generic]
 format = %(asctime)s %(levelname)-5.5s [%(name)s][%(threadName)s] %(message)s
-
-# End logging configuration
diff --git a/docs/tutorials/wiki2/src/tests/setup.py b/docs/tutorials/wiki2/src/tests/setup.py
index 0f58d8a18..3c2961fcc 100644
--- a/docs/tutorials/wiki2/src/tests/setup.py
+++ b/docs/tutorials/wiki2/src/tests/setup.py
@@ -21,10 +21,10 @@ requires = [
 setup(name='tutorial',
       version='0.0',
       description='tutorial',
-      long_description=README + '\n\n' +  CHANGES,
+      long_description=README + '\n\n' + CHANGES,
       classifiers=[
         "Programming Language :: Python",
-        "Framework :: Pylons",
+        "Framework :: Pyramid",
         "Topic :: Internet :: WWW/HTTP",
         "Topic :: Internet :: WWW/HTTP :: WSGI :: Application",
         ],
@@ -36,8 +36,8 @@ setup(name='tutorial',
       include_package_data=True,
       zip_safe=False,
       test_suite='tutorial',
-      install_requires = requires,
-      entry_points = """\
+      install_requires=requires,
+      entry_points="""\
       [paste.app_factory]
       main = tutorial:main
       [console_scripts]
diff --git a/docs/tutorials/wiki2/src/tests/tutorial/__init__.py b/docs/tutorials/wiki2/src/tests/tutorial/__init__.py
index 76071173a..d08e55bf9 100644
--- a/docs/tutorials/wiki2/src/tests/tutorial/__init__.py
+++ b/docs/tutorials/wiki2/src/tests/tutorial/__init__.py
@@ -11,6 +11,7 @@ from .models import (
     Base,
     )
 
+
 def main(global_config, **settings):
     """ This function returns a Pyramid WSGI application.
     """
@@ -33,4 +34,3 @@ def main(global_config, **settings):
     config.add_route('edit_page', '/{pagename}/edit_page')
     config.scan()
     return config.make_wsgi_app()
-
diff --git a/docs/tutorials/wiki2/src/tests/tutorial/models.py b/docs/tutorials/wiki2/src/tests/tutorial/models.py
index c3bdcbea5..91e5a0019 100644
--- a/docs/tutorials/wiki2/src/tests/tutorial/models.py
+++ b/docs/tutorials/wiki2/src/tests/tutorial/models.py
@@ -21,6 +21,7 @@ from zope.sqlalchemy import ZopeTransactionExtension
 DBSession = scoped_session(sessionmaker(extension=ZopeTransactionExtension()))
 Base = declarative_base()
 
+
 class Page(Base):
     """ The SQLAlchemy declarative model class for a Page object. """
     __tablename__ = 'pages'
diff --git a/docs/tutorials/wiki2/src/tests/tutorial/scripts/initializedb.py b/docs/tutorials/wiki2/src/tests/tutorial/scripts/initializedb.py
index 03188e8ad..092e359ce 100644
--- a/docs/tutorials/wiki2/src/tests/tutorial/scripts/initializedb.py
+++ b/docs/tutorials/wiki2/src/tests/tutorial/scripts/initializedb.py
@@ -15,12 +15,14 @@ from ..models import (
     Base,
     )
 
+
 def usage(argv):
     cmd = os.path.basename(argv[0])
     print('usage: %s <config_uri>\n'
-          '(example: "%s development.ini")' % (cmd, cmd)) 
+          '(example: "%s development.ini")' % (cmd, cmd))
     sys.exit(1)
 
+
 def main(argv=sys.argv):
     if len(argv) != 2:
         usage(argv)
diff --git a/docs/tutorials/wiki2/src/tests/tutorial/tests.py b/docs/tutorials/wiki2/src/tests/tutorial/tests.py
index 659862a09..3e96d0a82 100644
--- a/docs/tutorials/wiki2/src/tests/tutorial/tests.py
+++ b/docs/tutorials/wiki2/src/tests/tutorial/tests.py
@@ -1,7 +1,9 @@
 import unittest
 import transaction
+
 from pyramid import testing
 
+
 def _initTestingDB():
     from sqlalchemy import create_engine
     from tutorial.models import (
@@ -17,6 +19,7 @@ def _initTestingDB():
         DBSession.add(model)
     return DBSession
 
+
 def _registerRoutes(config):
     config.add_route('view_page', '{pagename}')
     config.add_route('edit_page', '{pagename}/edit_page')
@@ -43,6 +46,7 @@ class PageModelTests(unittest.TestCase):
         self.assertEqual(instance.name, 'SomeName')
         self.assertEqual(instance.data, 'some data')
 
+
 class ViewWikiTests(unittest.TestCase):
     def setUp(self):
         self.config = testing.setUp()
@@ -60,6 +64,7 @@ class ViewWikiTests(unittest.TestCase):
         response = self._callFUT(request)
         self.assertEqual(response.location, 'http://example.com/FrontPage')
 
+
 class ViewPageTests(unittest.TestCase):
     def setUp(self):
         self.session = _initTestingDB()
@@ -93,6 +98,7 @@ class ViewPageTests(unittest.TestCase):
         self.assertEqual(info['edit_url'],
             'http://example.com/IDoExist/edit_page')
 
+
 class AddPageTests(unittest.TestCase):
     def setUp(self):
         self.session = _initTestingDB()
@@ -125,6 +131,7 @@ class AddPageTests(unittest.TestCase):
         page = self.session.query(Page).filter_by(name='AnotherPage').one()
         self.assertEqual(page.data, 'Hello yo!')
 
+
 class EditPageTests(unittest.TestCase):
     def setUp(self):
         self.session = _initTestingDB()
@@ -162,6 +169,7 @@ class EditPageTests(unittest.TestCase):
         self.assertEqual(response.location, 'http://example.com/abc')
         self.assertEqual(page.data, 'Hello yo!')
 
+
 class FunctionalTests(unittest.TestCase):
 
     viewer_login = '/login?login=viewer&password=viewer' \
diff --git a/docs/tutorials/wiki2/src/tests/tutorial/views.py b/docs/tutorials/wiki2/src/tests/tutorial/views.py
index 42ac0eb7f..0d085b0e2 100644
--- a/docs/tutorials/wiki2/src/tests/tutorial/views.py
+++ b/docs/tutorials/wiki2/src/tests/tutorial/views.py
@@ -37,14 +37,13 @@ def view_wiki(request):
              permission='view')
 def view_page(request):
     pagename = request.matchdict['pagename']
-    session = DBSession()
-    page = session.query(Page).filter_by(name=pagename).first()
+    page = DBSession.query(Page).filter_by(name=pagename).first()
     if page is None:
         return HTTPNotFound('No such page')
 
     def check(match):
         word = match.group(1)
-        exists = session.query(Page).filter_by(name=word).all()
+        exists = DBSession.query(Page).filter_by(name=word).all()
         if exists:
             view_url = request.route_url('view_page', pagename=word)
             return '<a href="%s">%s</a>' % (view_url, word)
@@ -63,10 +62,9 @@ def view_page(request):
 def add_page(request):
     pagename = request.matchdict['pagename']
     if 'form.submitted' in request.params:
-        session = DBSession()
         body = request.params['body']
         page = Page(pagename, body)
-        session.add(page)
+        DBSession.add(page)
         return HTTPFound(location = request.route_url('view_page',
                                                       pagename=pagename))
     save_url = request.route_url('add_page', pagename=pagename)
@@ -78,11 +76,10 @@ def add_page(request):
              permission='edit')
 def edit_page(request):
     pagename = request.matchdict['pagename']
-    session = DBSession()
-    page = session.query(Page).filter_by(name=pagename).one()
+    page = DBSession.query(Page).filter_by(name=pagename).one()
     if 'form.submitted' in request.params:
         page.data = request.params['body']
-        session.add(page)
+        DBSession.add(page)
         return HTTPFound(location = request.route_url('view_page',
                                                       pagename=pagename))
     return dict(
diff --git a/docs/tutorials/wiki2/src/views/README.txt b/docs/tutorials/wiki2/src/views/README.txt
index 6f851e9b7..141851285 100644
--- a/docs/tutorials/wiki2/src/views/README.txt
+++ b/docs/tutorials/wiki2/src/views/README.txt
@@ -1 +1,14 @@
 tutorial README
+==================
+
+Getting Started
+---------------
+
+- cd <directory containing this file>
+
+- $venv/bin/python setup.py develop
+
+- $venv/bin/initialize_tutorial_db development.ini
+
+- $venv/bin/pserve development.ini
+
diff --git a/docs/tutorials/wiki2/src/views/development.ini b/docs/tutorials/wiki2/src/views/development.ini
index eb2f878c5..a9d53b296 100644
--- a/docs/tutorials/wiki2/src/views/development.ini
+++ b/docs/tutorials/wiki2/src/views/development.ini
@@ -1,3 +1,8 @@
+###
+# app configuration
+# http://docs.pylonsproject.org/projects/pyramid/en/latest/narr/environment.html
+###
+
 [app:main]
 use = egg:tutorial
 
@@ -12,12 +17,23 @@ pyramid.includes =
 
 sqlalchemy.url = sqlite:///%(here)s/tutorial.sqlite
 
+# By default, the toolbar only appears for clients from IP addresses
+# '127.0.0.1' and '::1'.
+# debugtoolbar.hosts = 127.0.0.1 ::1
+
+###
+# wsgi server configuration
+###
+
 [server:main]
 use = egg:waitress#main
 host = 0.0.0.0
 port = 6543
 
-# Begin logging configuration
+###
+# logging configuration
+# http://docs.pylonsproject.org/projects/pyramid/en/latest/narr/logging.html
+###
 
 [loggers]
 keys = root, tutorial, sqlalchemy
@@ -53,5 +69,3 @@ formatter = generic
 
 [formatter_generic]
 format = %(asctime)s %(levelname)-5.5s [%(name)s][%(threadName)s] %(message)s
-
-# End logging configuration
diff --git a/docs/tutorials/wiki2/src/views/setup.py b/docs/tutorials/wiki2/src/views/setup.py
index 34b578e21..36668dd33 100644
--- a/docs/tutorials/wiki2/src/views/setup.py
+++ b/docs/tutorials/wiki2/src/views/setup.py
@@ -20,10 +20,10 @@ requires = [
 setup(name='tutorial',
       version='0.0',
       description='tutorial',
-      long_description=README + '\n\n' +  CHANGES,
+      long_description=README + '\n\n' + CHANGES,
       classifiers=[
         "Programming Language :: Python",
-        "Framework :: Pylons",
+        "Framework :: Pyramid",
         "Topic :: Internet :: WWW/HTTP",
         "Topic :: Internet :: WWW/HTTP :: WSGI :: Application",
         ],
@@ -35,12 +35,11 @@ setup(name='tutorial',
       include_package_data=True,
       zip_safe=False,
       test_suite='tutorial',
-      install_requires = requires,
-      entry_points = """\
+      install_requires=requires,
+      entry_points="""\
       [paste.app_factory]
       main = tutorial:main
       [console_scripts]
       initialize_tutorial_db = tutorial.scripts.initializedb:main
       """,
       )
-
diff --git a/docs/tutorials/wiki2/src/views/tutorial/__init__.py b/docs/tutorials/wiki2/src/views/tutorial/__init__.py
index 810e92f75..c95bfdbf8 100644
--- a/docs/tutorials/wiki2/src/views/tutorial/__init__.py
+++ b/docs/tutorials/wiki2/src/views/tutorial/__init__.py
@@ -6,6 +6,7 @@ from .models import (
     Base,
     )
 
+
 def main(global_config, **settings):
     """ This function returns a Pyramid WSGI application.
     """
diff --git a/docs/tutorials/wiki2/src/views/tutorial/models.py b/docs/tutorials/wiki2/src/views/tutorial/models.py
index 499396c5b..9a078d757 100644
--- a/docs/tutorials/wiki2/src/views/tutorial/models.py
+++ b/docs/tutorials/wiki2/src/views/tutorial/models.py
@@ -16,6 +16,7 @@ from zope.sqlalchemy import ZopeTransactionExtension
 DBSession = scoped_session(sessionmaker(extension=ZopeTransactionExtension()))
 Base = declarative_base()
 
+
 class Page(Base):
     """ The SQLAlchemy declarative model class for a Page object. """
     __tablename__ = 'pages'
@@ -26,4 +27,3 @@ class Page(Base):
     def __init__(self, name, data):
         self.name = name
         self.data = data
-
diff --git a/docs/tutorials/wiki2/src/views/tutorial/scripts/initializedb.py b/docs/tutorials/wiki2/src/views/tutorial/scripts/initializedb.py
index 03188e8ad..092e359ce 100644
--- a/docs/tutorials/wiki2/src/views/tutorial/scripts/initializedb.py
+++ b/docs/tutorials/wiki2/src/views/tutorial/scripts/initializedb.py
@@ -15,12 +15,14 @@ from ..models import (
     Base,
     )
 
+
 def usage(argv):
     cmd = os.path.basename(argv[0])
     print('usage: %s <config_uri>\n'
-          '(example: "%s development.ini")' % (cmd, cmd)) 
+          '(example: "%s development.ini")' % (cmd, cmd))
     sys.exit(1)
 
+
 def main(argv=sys.argv):
     if len(argv) != 2:
         usage(argv)
diff --git a/docs/tutorials/wiki2/src/views/tutorial/tests.py b/docs/tutorials/wiki2/src/views/tutorial/tests.py
index 31d2dc6d5..5dcee127b 100644
--- a/docs/tutorials/wiki2/src/views/tutorial/tests.py
+++ b/docs/tutorials/wiki2/src/views/tutorial/tests.py
@@ -1,5 +1,6 @@
 import unittest
 import transaction
+
 from pyramid import testing
 
 def _initTestingDB():
diff --git a/docs/tutorials/wiki2/tests.rst b/docs/tutorials/wiki2/tests.rst
index 6a7cbf62d..83df86b27 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