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

39 files changed, 372 insertions, 176 deletions

diff --git a/docs/_themes b/docs/_themes
-Subproject 26732645619b372764097e5e8086f89871d90c0
+Subproject 3bec9280a6cedb15e97e5899021aa8d723c2538
diff --git a/docs/api/i18n.rst b/docs/api/i18n.rst
index 53e8c8a9b..3b9abbc1d 100644
--- a/docs/api/i18n.rst
+++ b/docs/api/i18n.rst
@@ -7,7 +7,7 @@
 
   .. autoclass:: TranslationString
  
-  .. autoclass:: TranslationStringFactory
+  .. autofunction:: TranslationStringFactory
 
   .. autoclass:: Localizer
      :members:
diff --git a/docs/api/registry.rst b/docs/api/registry.rst
index 7736cf075..bab3e26ba 100644
--- a/docs/api/registry.rst
+++ b/docs/api/registry.rst
@@ -21,7 +21,10 @@
      When a registry is set up (or created) by a :term:`Configurator`, the
      registry will be decorated with an instance named ``introspector``
      implementing the :class:`pyramid.interfaces.IIntrospector` interface.
-     See also :attr:`pyramid.config.Configurator.introspector`.
+
+     .. seealso::
+
+        See also :attr:`pyramid.config.Configurator.introspector`.
 
      When a registry is created "by hand", however, this attribute will not
      exist until set up by a configurator.
diff --git a/docs/api/request.rst b/docs/api/request.rst
index b7604020e..343d0c022 100644
--- a/docs/api/request.rst
+++ b/docs/api/request.rst
@@ -250,8 +250,11 @@
       ``invoke_subrequest`` isn't *actually* a method of the Request object;
       it's a callable added when the Pyramid router is invoked, or when a
       subrequest is invoked.  This means that it's not available for use on a
-      request provided by e.g. the ``pshell`` environment.  For more
-      information, see :ref:`subrequest_chapter`.
+      request provided by e.g. the ``pshell`` environment.
+
+      .. seealso::
+
+          See also :ref:`subrequest_chapter`.
 
    .. automethod:: has_permission
 
@@ -280,7 +283,11 @@
        This property will return the JSON-decoded variant of the request
        body.  If the request body is not well-formed JSON, or there is no
        body associated with this request, this property will raise an
-       exception.  See also :ref:`request_json_body`.
+       exception.
+       
+       .. seealso::
+       
+           See also :ref:`request_json_body`.
 
    .. method:: set_property(callable, name=None, reify=False)
 
diff --git a/docs/designdefense.rst b/docs/designdefense.rst
index 418ceb08f..1ed4f65a4 100644
--- a/docs/designdefense.rst
+++ b/docs/designdefense.rst
@@ -537,7 +537,11 @@ text indexing.  It does not dictate how you arrange your code.
 
 Such opinionated functionality exists in applications and frameworks built
 *on top* of :app:`Pyramid`.  It's intended that higher-level systems emerge
-built using :app:`Pyramid` as a base.  See also :ref:`apps_are_extensible`.
+built using :app:`Pyramid` as a base.
+
+.. seealso::
+
+    See also :ref:`apps_are_extensible`.
 
 Pyramid Provides Too Many "Rails"
 ---------------------------------
diff --git a/docs/glossary.rst b/docs/glossary.rst
index 406b81778..0e340491b 100644
--- a/docs/glossary.rst
+++ b/docs/glossary.rst
@@ -54,8 +54,12 @@ Glossary
      provides an API for addressing "asset files" within a Python
      :term:`package`.  Asset files are static files, template files, etc;
      basically anything non-Python-source that lives in a Python package can
-     be considered a asset file.  See also `PkgResources
-     <http://peak.telecommunity.com/DevCenter/PkgResources>`_
+     be considered a asset file.
+     
+     .. seealso::
+         
+         See also `PkgResources
+         <http://peak.telecommunity.com/DevCenter/PkgResources>`_.
 
    asset
      Any file contained within a Python :term:`package` which is *not*
@@ -242,7 +246,11 @@ Glossary
      be effectively amended with a ``permission`` argument that will
      require that the executing user possess the default permission in
      order to successfully execute the associated :term:`view
-     callable` See also :ref:`setting_a_default_permission`.
+     callable`.
+
+     .. seealso::
+        
+        See also :ref:`setting_a_default_permission`.
 
    ACE
      An *access control entry*.  An access control entry is one element
@@ -380,7 +388,11 @@ Glossary
    route
      A single pattern matched by the :term:`url dispatch` subsystem,
      which generally resolves to a :term:`root factory` (and then
-     ultimately a :term:`view`).  See also :term:`url dispatch`.
+     ultimately a :term:`view`).
+
+     .. seealso::
+
+        See also :term:`url dispatch`.
 
    route configuration
      Route configuration is the act of associating request parameters with a
@@ -580,8 +592,11 @@ Glossary
      A wrapper around a Python function or class which accepts the
      function or class as its first argument and which returns an
      arbitrary object.  :app:`Pyramid` provides several decorators,
-     used for configuration and return value modification purposes.  See
-     also `PEP 318 <http://www.python.org/dev/peps/pep-0318/>`_.
+     used for configuration and return value modification purposes.
+
+     .. seealso::
+     
+        See also `PEP 318 <http://www.python.org/dev/peps/pep-0318/>`_.
 
    configuration declaration
      An individual method call made to a :term:`configuration directive`,
@@ -646,8 +661,11 @@ Glossary
    HTTP Exception
       The set of exception classes defined in :mod:`pyramid.httpexceptions`.
       These can be used to generate responses with various status codes when
-      raised or returned from a :term:`view callable`.  See also
-      :ref:`http_exceptions`.
+      raised or returned from a :term:`view callable`.
+
+      .. seealso::
+
+          See also :ref:`http_exceptions`.
 
    thread local
       A thread-local variable is one which is essentially a global variable
@@ -656,8 +674,11 @@ Glossary
       application may have a different value for this same "global" variable.
       :app:`Pyramid` uses a small number of thread local variables, as
       described in :ref:`threadlocals_chapter`.
-      See also the :class:`stdlib documentation <threading.local>`
-      for more information.
+
+      .. seealso::
+
+          See also the :class:`stdlib documentation <threading.local>`
+          for more information.
 
    multidict
      An ordered dictionary that can have multiple values for each key. Adds
@@ -671,7 +692,11 @@ Glossary
 
    Agendaless Consulting
      A consulting organization formed by Paul Everitt, Tres Seaver,
-     and Chris McDonough.  See also http://agendaless.com .
+     and Chris McDonough.
+
+     .. seealso::
+
+         See also `Agendaless Consulting <http://agendaless.com>`_.
 
    Jython
      A `Python implementation <http://www.jython.org/>`_ written for
@@ -792,15 +817,21 @@ Glossary
      The act of creating software with a user interface that can
      potentially be displayed in more than one language or cultural
      context.  Often shortened to "i18n" (because the word
-     "internationalization" is I, 18 letters, then N).  See also:
-     :term:`Localization`.
+     "internationalization" is I, 18 letters, then N).
+
+     .. seealso::
+
+         See also :term:`Localization`.
 
    Localization
      The process of displaying the user interface of an
      internationalized application in a particular language or
      cultural context.  Often shortened to "l10" (because the word
-     "localization" is L, 10 letters, then N).  See also:
-     :term:`Internationalization`.
+     "localization" is L, 10 letters, then N).
+
+     .. seealso::
+     
+         See also :term:`Internationalization`.
 
    renderer globals
       Values injected as names into a renderer by a
@@ -809,7 +840,10 @@ Glossary
    response callback
       A user-defined callback executed by the :term:`router` at a
       point after a :term:`response` object is successfully created.
-      See :ref:`using_response_callbacks`.
+
+      .. seealso::
+
+          See also :ref:`using_response_callbacks`.
 
    finished callback
       A user-defined callback executed by the :term:`router`
diff --git a/docs/narr/advconfig.rst b/docs/narr/advconfig.rst
index d3431e39e..9ceaaa495 100644
--- a/docs/narr/advconfig.rst
+++ b/docs/narr/advconfig.rst
@@ -158,8 +158,12 @@ use :meth:`pyramid.config.Configurator.include`:
 Using :meth:`~pyramid.config.Configurator.include` instead of calling the
 function directly provides a modicum of automated conflict resolution, with
 the configuration statements you define in the calling code overriding those
-of the included function.  See also :ref:`automatic_conflict_resolution` and
-:ref:`including_configuration`.
+of the included function.
+
+.. seealso::
+
+    See also :ref:`automatic_conflict_resolution` and
+    :ref:`including_configuration`.
 
 Using ``config.commit()``
 +++++++++++++++++++++++++
diff --git a/docs/narr/environment.rst b/docs/narr/environment.rst
index f0c0c18fe..412635f08 100644
--- a/docs/narr/environment.rst
+++ b/docs/narr/environment.rst
@@ -59,8 +59,11 @@ third-party template rendering extensions.
 Reloading Assets
 ----------------
 
-Don't cache any asset file data when this value is true.  See
-also :ref:`overriding_assets_section`.
+Don't cache any asset file data when this value is true.
+
+.. seealso::
+
+    See also :ref:`overriding_assets_section`.
 
 +---------------------------------+-----------------------------+
 | Environment Variable Name       | Config File Setting Name    |
@@ -79,7 +82,11 @@ Debugging Authorization
 -----------------------
 
 Print view authorization failure and success information to stderr
-when this value is true.  See also :ref:`debug_authorization_section`.
+when this value is true.
+
+.. seealso::
+
+    See also :ref:`debug_authorization_section`.
 
 +---------------------------------+-----------------------------------+
 | Environment Variable Name       | Config File Setting Name          |
@@ -94,7 +101,11 @@ Debugging Not Found Errors
 --------------------------
 
 Print view-related ``NotFound`` debug messages to stderr
-when this value is true.  See also :ref:`debug_notfound_section`.
+when this value is true.
+
+.. seealso::
+
+    See also :ref:`debug_notfound_section`.
 
 +---------------------------------+------------------------------+
 | Environment Variable Name       | Config File Setting Name     |
@@ -109,7 +120,11 @@ Debugging Route Matching
 ------------------------
 
 Print debugging messages related to :term:`url dispatch` route matching when
-this value is true.  See also :ref:`debug_routematch_section`.
+this value is true.
+
+.. seealso::
+
+    See also :ref:`debug_routematch_section`.
 
 +---------------------------------+--------------------------------+
 | Environment Variable Name       | Config File Setting Name       |
@@ -128,7 +143,11 @@ Preventing HTTP Caching
 Prevent the ``http_cache`` view configuration argument from having any effect
 globally in this process when this value is true.  No http caching-related
 response headers will be set by the Pyramid ``http_cache`` view configuration
-feature when this is true.  See also :ref:`influencing_http_caching`.
+feature when this is true.
+
+.. seealso::
+
+    See also :ref:`influencing_http_caching`.
 
 +---------------------------------+----------------------------------+
 | Environment Variable Name       | Config File Setting Name         |
@@ -173,8 +192,11 @@ Default Locale Name
 --------------------
 
 The value supplied here is used as the default locale name when a
-:term:`locale negotiator` is not registered.  See also
-:ref:`localization_deployment_settings`.
+:term:`locale negotiator` is not registered.
+
+.. seealso::
+
+    See also :ref:`localization_deployment_settings`.
 
 +---------------------------------+-----------------------------------+
 | Environment Variable Name       | Config File Setting Name          |
diff --git a/docs/narr/events.rst b/docs/narr/events.rst
index 50484761d..09caac898 100644
--- a/docs/narr/events.rst
+++ b/docs/narr/events.rst
@@ -44,7 +44,7 @@ Configuring an Event Listener Imperatively
 You can imperatively configure a subscriber function to be called
 for some event type via the
 :meth:`~pyramid.config.Configurator.add_subscriber`
-method (see also :term:`Configurator`):
+method:
 
 .. code-block:: python
   :linenos:
@@ -63,6 +63,10 @@ The first argument to
 subscriber function (or a :term:`dotted Python name` which refers
 to a subscriber callable); the second argument is the event type.
 
+.. seealso::
+
+    See also :term:`Configurator`.
+
 Configuring an Event Listener Using a Decorator
 -----------------------------------------------
 
diff --git a/docs/narr/hellotraversal.rst b/docs/narr/hellotraversal.rst
index 142c24f54..0a93b8f16 100644
--- a/docs/narr/hellotraversal.rst
+++ b/docs/narr/hellotraversal.rst
@@ -60,10 +60,10 @@ A more complicated application could have many types of resources,
 with different view callables defined for each type, and even multiple
 views for each type.
 
-See Also
----------
+.. seealso::
 
-Full technical details may be found in :doc:`traversal`.
-
-For more about *why* you might use traversal, see :doc:`muchadoabouttraversal`.
+    Full technical details may be found in :doc:`traversal`.
+    
+    For more about *why* you might use traversal, see
+    :doc:`muchadoabouttraversal`.
 
diff --git a/docs/narr/introduction.rst b/docs/narr/introduction.rst
index 8acbab3a0..a37d74c9b 100644
--- a/docs/narr/introduction.rst
+++ b/docs/narr/introduction.rst
@@ -121,7 +121,9 @@ ways.
 
 .. literalinclude:: helloworld.py
 
-See also :ref:`firstapp_chapter`.
+.. seealso::
+
+    See also :ref:`firstapp_chapter`.
 
 Decorator-based configuration
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -271,7 +273,9 @@ Here's a few views defined as methods of a class instead:
        def view_two(self):
            return Response('two')
 
-See also :ref:`view_config_placement`.
+.. seealso::
+
+    See also :ref:`view_config_placement`.
 
 .. _intro_asset_specs:
 
@@ -572,7 +576,10 @@ For example:
       config.include('pyramid_exclog')
       config.include('some.other.guys.package', route_prefix='/someotherguy')
 
-See also :ref:`including_configuration` and :ref:`building_an_extensible_app`
+.. seealso::
+
+    See also :ref:`including_configuration` and
+    :ref:`building_an_extensible_app`.
 
 Flexible authentication and authorization
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -730,7 +737,9 @@ Pyramid defaults to explicit behavior, because it's the most generally
 useful, but provides hooks that allow you to adapt the framework to localized
 aesthetic desires.
 
-See also :ref:`using_iresponse`.
+.. seealso::
+
+    See also :ref:`using_iresponse`.
 
 "Global" response object
 ~~~~~~~~~~~~~~~~~~~~~~~~
@@ -748,7 +757,9 @@ section," you say.  Fine.  Be that way:
        response.content_type = 'text/plain'
        return response
 
-See also :ref:`request_response_attr`.
+.. seealso::
+
+    See also :ref:`request_response_attr`.
 
 Automating repetitive configuration
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -811,7 +822,9 @@ it up and calling :meth:`~pyramid.config.Configurator.add_directive` from
 within a function called when another user uses the
 :meth:`~pyramid.config.Configurator.include` method against your code.
 
-See also :ref:`add_directive`.
+.. seealso::
+
+    See also :ref:`add_directive`.
 
 Programmatic Introspection
 ~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -839,7 +852,9 @@ callable:
         route_intr = introspector.get('routes', route_name)
         return Response(str(route_intr['pattern']))
 
-See also :ref:`using_introspection`.
+.. seealso::
+
+    See also :ref:`using_introspection`.
 
 Python 3 Compatibility
 ~~~~~~~~~~~~~~~~~~~~~~
diff --git a/docs/narr/project.rst b/docs/narr/project.rst
index eb12f67ef..62b91de0e 100644
--- a/docs/narr/project.rst
+++ b/docs/narr/project.rst
@@ -898,15 +898,22 @@ returns the HTML in a :term:`response`.
      a server restart to reload them.  Production applications should use
      ``pyramid.reload_templates = False``.
 
-.. seealso:: See also :ref:`views_which_use_a_renderer` for more information
+.. seealso::
+
+    See also :ref:`views_which_use_a_renderer` for more information
     about how views, renderers, and templates relate and cooperate.
 
-.. seealso:: Pyramid can also dynamically reload changed Python files.  For
-    more on this see :ref:`reloading_code`.
+.. seealso::
+
+    Pyramid can also dynamically reload changed Python files.  See also
+    :ref:`reloading_code`.
+
+.. seealso::
 
-.. seealso:: The :ref:`debug_toolbar` provides interactive access to your
-   application's internals and, should an exception occur, allows interactive
-   access to traceback execution stack frames from the Python interpreter.
+    See also the :ref:`debug_toolbar`, which provides interactive access to
+    your application's internals and, should an exception occur, allows
+    interactive access to traceback execution stack frames from the Python
+    interpreter.
 
 .. index::
    single: static directory
diff --git a/docs/narr/resources.rst b/docs/narr/resources.rst
index f3ff1dc4c..6139154ff 100644
--- a/docs/narr/resources.rst
+++ b/docs/narr/resources.rst
@@ -673,8 +673,11 @@ Calling ``find_interface(b, Thing2)`` will return the ``b`` resource.
 The second argument to find_interface may also be a :term:`interface` instead
 of a class.  If it is an interface, each resource in the lineage is checked
 to see if the resource implements the specificed interface (instead of seeing
-if the resource is of a class).  See also
-:ref:`resources_which_implement_interfaces`.
+if the resource is of a class).
+
+.. seealso::
+
+    See also :ref:`resources_which_implement_interfaces`.
 
 .. index::
    single: resource API functions
diff --git a/docs/narr/security.rst b/docs/narr/security.rst
index 9e6fb6c82..8db23a33b 100644
--- a/docs/narr/security.rst
+++ b/docs/narr/security.rst
@@ -113,9 +113,11 @@ authorization policies, it is an error to configure a Pyramid application
 with an authentication policy but without the authorization policy or vice
 versa.  If you do this, you'll receive an error at application startup time.
 
-See also the :mod:`pyramid.authorization` and
-:mod:`pyramid.authentication` modules for alternate implementations
-of authorization and authentication policies.  
+.. seealso::
+
+    See also the :mod:`pyramid.authorization` and
+    :mod:`pyramid.authentication` modules for alternate implementations of
+    authorization and authentication policies.
 
 .. index::
    single: permissions
@@ -495,8 +497,14 @@ is said to be *location-aware*.  Location-aware objects define an
 ``__parent__`` attribute which points at their parent object.  The
 root object's ``__parent__`` is ``None``.
 
-See :ref:`location_module` for documentations of functions which use
-location-awareness.  See also :ref:`location_aware`.
+.. seealso::
+
+    See also :ref:`location_module` for documentations of functions which use
+    location-awareness.
+
+.. seealso::
+
+    See also :ref:`location_aware`.
 
 .. index::
    single: forbidden view
diff --git a/docs/narr/sessions.rst b/docs/narr/sessions.rst
index fb5035373..8da743a01 100644
--- a/docs/narr/sessions.rst
+++ b/docs/narr/sessions.rst
@@ -158,10 +158,24 @@ Some gotchas:
 Using Alternate Session Factories
 ---------------------------------
 
-At the time of this writing, exactly one project-endorsed alternate session
-factory exists named :term:`pyramid_redis_sessions`.  It can be downloaded from
-PyPI.  It uses the Redis database as a backend.  It is the recommended 
-persistent session solution at the time of this writing.
+The following session factories exist at the time of this writing.
+
+======================= ======= =============================
+Session Factory         Backend   Description
+======================= ======= =============================
+pyramid_redis_sessions_ Redis_  Server-side session library
+                                for Pyramid, using Redis for
+                                storage.
+pyramid_beaker_         Beaker_ Session factory for Pyramid
+                                backed by the Beaker
+                                sessioning system.
+======================= ======= =============================
+
+.. _pyramid_redis_sessions: https://pypi.python.org/pypi/pyramid_redis_sessions
+.. _Redis: http://redis.io/
+
+.. _pyramid_beaker: https://pypi.python.org/pypi/pyramid_beaker
+.. _Beaker: http://beaker.readthedocs.org/en/latest/
 
 .. index::
    single: session factory (custom)
diff --git a/docs/narr/startup.rst b/docs/narr/startup.rst
index 1affa1758..7b4a7ea08 100644
--- a/docs/narr/startup.rst
+++ b/docs/narr/startup.rst
@@ -123,7 +123,7 @@ Here's a high-level time-ordered overview of what happens when you press
    populated by other methods run against the Configurator.  The router is a
    WSGI application.
 
-#. A :class:`~pyramid.events.ApplicationCreated` event is emitted (see
+#. An :class:`~pyramid.events.ApplicationCreated` event is emitted (see
    :ref:`events_chapter` for more information about events).
 
 #. Assuming there were no errors, the ``main`` function in ``myproject``
diff --git a/docs/narr/templates.rst b/docs/narr/templates.rst
index 00fc21634..038dd2594 100644
--- a/docs/narr/templates.rst
+++ b/docs/narr/templates.rst
@@ -320,7 +320,11 @@ template renderer:
    in Chameleon, not in Mako templates.
 
 Similar renderer configuration can be done imperatively.  See
-:ref:`views_which_use_a_renderer`.  See also :ref:`built_in_renderers`.
+:ref:`views_which_use_a_renderer`.
+
+.. seealso::
+
+    See also :ref:`built_in_renderers`.
 
 Although a renderer path is usually just a simple relative pathname, a path
 named as a renderer can be absolute, starting with a slash on UNIX or a drive
diff --git a/docs/narr/testing.rst b/docs/narr/testing.rst
index 5a5bf8fad..e001ad81c 100644
--- a/docs/narr/testing.rst
+++ b/docs/narr/testing.rst
@@ -319,8 +319,10 @@ registering resources at paths, registering event listeners, registering
 views and view permissions, and classes representing "dummy" implementations
 of a request and a resource.
 
-See also the various methods of the :term:`Configurator` documented in
-:ref:`configuration_module` that begin with the ``testing_`` prefix.
+.. seealso::
+
+    See also the various methods of the :term:`Configurator` documented in
+    :ref:`configuration_module` that begin with the ``testing_`` prefix.
 
 .. index::
    single: integration tests
diff --git a/docs/narr/urldispatch.rst b/docs/narr/urldispatch.rst
index 96ee5758e..87a962a9a 100644
--- a/docs/narr/urldispatch.rst
+++ b/docs/narr/urldispatch.rst
@@ -1183,9 +1183,10 @@ still easily do it by wrapping it in classmethod call.
 Same will work with staticmethod, just use ``staticmethod`` instead of
 ``classmethod``.
 
+.. seealso::
 
-See also :class:`pyramid.interfaces.IRoute` for more API documentation about
-route objects.
+    See also :class:`pyramid.interfaces.IRoute` for more API documentation
+    about route objects.
 
 .. index::
    single: route factory
diff --git a/docs/narr/viewconfig.rst b/docs/narr/viewconfig.rst
index 84fde3f01..adc53bd11 100644
--- a/docs/narr/viewconfig.rst
+++ b/docs/narr/viewconfig.rst
@@ -118,8 +118,9 @@ Non-Predicate Arguments
 
 ``renderer``
   Denotes the :term:`renderer` implementation which will be used to construct
-  a :term:`response` from the associated view callable's return value. (see
-  also :ref:`renderers_chapter`).
+  a :term:`response` from the associated view callable's return value.
+  
+  .. seealso:: See also :ref:`renderers_chapter`.
 
   This is either a single string term (e.g. ``json``) or a string implying a
   path or :term:`asset specification` (e.g. ``templates/views.pt``) naming a
diff --git a/docs/quick_tour.rst b/docs/quick_tour.rst
index 2db18c8a7..4ab39bb11 100644
--- a/docs/quick_tour.rst
+++ b/docs/quick_tour.rst
@@ -49,7 +49,7 @@ production support in October 2011.)
     some optional C extensions for performance. With ``easy_install``, Windows
     users can get these extensions without needing a C compiler.
 
-.. seealso:: See Also:
+.. seealso:: See also:
     :ref:`Quick Tutorial section on Requirements <qtut_requirements>`,
     :ref:`installing_unix`,
     :ref:`Before You Install <installing_chapter>`, and
@@ -73,14 +73,14 @@ This simple example is easy to run. Save this as ``app.py`` and run it:
 Next, open `http://localhost:6543/ <http://localhost:6543/>`_ in a
 browser and you will see the ``Hello World!`` message.
 
-New to Python web programming? If so, some lines in module merit
+New to Python web programming? If so, some lines in the module merit
 explanation:
 
 #. *Line 10*. The ``if __name__ == '__main__':`` is Python's way of
    saying "Start here when running from the command line".
 
 #. *Lines 11-13*. Use Pyramid's :term:`configurator` to connect
-   :term:`view` code to particular URL :term:`route`.
+   :term:`view` code to a particular URL :term:`route`.
 
 #. *Lines 6-7*. Implement the view code that generates the
    :term:`response`.
@@ -92,7 +92,7 @@ in Pyramid development. Building an application from loosely-coupled
 parts via :doc:`../narr/configuration` is a central idea in Pyramid,
 one that we will revisit regurlarly in this *Quick Tour*.
 
-.. seealso:: See Also:
+.. seealso:: See also:
    :ref:`Quick Tutorial Hello World <qtut_hello_world>`,
    :ref:`firstapp_chapter`, and
    :ref:`Single File Tasks tutorial <tutorials:single-file-tutorial>`
@@ -125,7 +125,7 @@ the name is included in the body of the response::
 
 Finally, we set the response's content type and return the Response.
 
-.. seealso:: See Also:
+.. seealso:: See also:
     :ref:`Quick Tutorial Request and Response <qtut_request_response>`
     and
     :ref:`webob_chapter`
@@ -148,15 +148,15 @@ So far our examples place everything in one file:
 - the WSGI application launcher
 
 Let's move the views out to their own ``views.py`` module and change
-the ``app.py`` to scan that module, looking for decorators that setup
+the ``app.py`` to scan that module, looking for decorators that set up
 the views. First, our revised ``app.py``:
 
 .. literalinclude:: quick_tour/views/app.py
     :linenos:
 
 We added some more routes, but we also removed the view code.
-Our views, and their registrations (via decorators) are now in a module
-``views.py`` which is scanned via ``config.scan('views')``.
+Our views and their registrations (via decorators) are now in a module
+``views.py``, which is scanned via ``config.scan('views')``.
 
 We now have a ``views.py`` module that is focused on handling requests
 and responses:
@@ -167,7 +167,7 @@ and responses:
 We have 4 views, each leading to the other. If you start at
 ``http://localhost:6543/``, you get a response with a link to the next
 view. The ``hello_view`` (available at the URL ``/howdy``) has a link
-to the ``redirect_view``, which shows issuing a redirect to the final
+to the ``redirect_view``, which issues a redirect to the final
 view.
 
 Earlier we saw ``config.add_view`` as one way to configure a view. This
@@ -178,7 +178,7 @@ configuration`, in which a Python :term:`decorator` is placed on the
 line above the view. Both approaches result in the same final
 configuration, thus usually, it is simply a matter of taste.
 
-.. seealso:: See Also:
+.. seealso:: See also:
    :ref:`Quick Tutorial Views <qtut_views>`,
    :doc:`../narr/views`,
    :doc:`../narr/viewconfig`, and
@@ -226,7 +226,7 @@ view:
 "replacement patterns" (the curly braces) in the route declaration.
 This information can then be used in your view.
 
-.. seealso:: See Also:
+.. seealso:: See also:
    :ref:`Quick Tutorial Routing <qtut_routing>`,
    :doc:`../narr/urldispatch`,
    :ref:`debug_routematch_section`, and
@@ -243,8 +243,23 @@ Pyramid doesn't mandate a particular database system, form library,
 etc. It encourages replaceability. This applies equally to templating,
 which is fortunate: developers have strong views about template
 languages. That said, the Pylons Project officially supports bindings for
-Chameleon, Jinja2 and Mako, so in this step, let's use Chameleon as an
-example:
+Chameleon, Jinja2, and Mako, so in this step, let's use Chameleon.
+
+Let's add ``pyramid_chameleon``, a Pyramid :term:`add-on` which enables
+Chameleon as a :term:`renderer` in our Pyramid applications:
+
+.. code-block:: bash
+
+    $ easy_install pyramid_chameleon
+
+With the package installed, we can include the template bindings into
+our configuration:
+
+.. code-block:: python
+
+    config.include('pyramid_chameleon')
+    
+Now lets change our views.py file:
 
 .. literalinclude:: quick_tour/templating/views.py
     :start-after: Start View 1
@@ -252,7 +267,7 @@ example:
 
 Ahh, that looks better. We have a view that is focused on Python code.
 Our ``@view_config`` decorator specifies a :term:`renderer` that points
-our template file. Our view then simply returns data which is then
+to our template file. Our view then simply returns data which is then
 supplied to our template:
 
 .. literalinclude:: quick_tour/templating/hello_world.pt
@@ -262,7 +277,7 @@ Since our view returned ``dict(name=request.matchdict['name'])``,
 we can use ``name`` as a variable in our template via
 ``${name}``.
 
-.. seealso:: See Also:
+.. seealso:: See also:
     :ref:`Quick Tutorial Templating <qtut_templating>`,
     :doc:`../narr/templates`,
     :ref:`debugging_templates`, and
@@ -288,7 +303,7 @@ our configuration:
 
     config.include('pyramid_jinja2')
 
-The only change in our view...point the renderer at the ``.jinja2`` file:
+The only change in our view is to point the renderer at the ``.jinja2`` file:
 
 .. literalinclude:: quick_tour/jinja2/views.py
     :start-after: Start View 1
@@ -305,7 +320,7 @@ filename extensions. In this case, changing the extension from ``.pt``
 to ``.jinja2`` passed the view response through the ``pyramid_jinja2``
 renderer.
 
-.. seealso:: See Also:
+.. seealso:: See also:
     :ref:`Quick Tutorial Jinja2 <qtut_jinja2>`,
     `Jinja2 homepage <http://jinja.pocoo.org/>`_, and
     :ref:`pyramid_jinja2 Overview <jinja2:overview>`
@@ -341,8 +356,8 @@ template:
 
 This link presumes that our CSS is at a URL starting with ``/static/``.
 What if the site is later moved under ``/somesite/static/``? Or perhaps
-web developer changes the arrangement on disk? Pyramid gives a helper
-that provides flexibility on URL generation:
+a web developer changes the arrangement on disk? Pyramid provides a helper
+to allow flexibility on URL generation:
 
 .. literalinclude:: quick_tour/static_assets/hello_world.pt
     :language: html
@@ -353,7 +368,7 @@ By using ``request.static_url`` to generate the full URL to the static
 assets, you both ensure you stay in sync with the configuration and
 gain refactoring flexibility later.
 
-.. seealso:: See Also:
+.. seealso:: See also:
     :ref:`Quick Tutorial Static Assets <qtut_static_assets>`,
     :doc:`../narr/assets`,
     :ref:`preventing_http_caching`, and
@@ -374,7 +389,7 @@ This wires up a view that returns some data through the JSON
 :term:`renderer`, which calls Python's JSON support to serialize the data
 into JSON and set the appropriate HTTP headers.
 
-.. seealso:: See Also:
+.. seealso:: See also:
     :ref:`Quick Tutorial JSON <qtut_json>`,
     :ref:`views_which_use_a_renderer`,
     :ref:`json_renderer`, and
@@ -431,7 +446,7 @@ have much more to offer:
   ``accept``, ``header``, ``xhr``, ``containment``, and
   ``custom_predicates``
 
-.. seealso:: See Also:
+.. seealso:: See also:
     :ref:`Quick Tutorial View Classes <qtut_view_classes>`,
     :ref:`Quick Tutorial More View Classes <qtut_more_view_classes>`, and
     :ref:`class_as_view`
@@ -439,7 +454,7 @@ have much more to offer:
 Quick Project Startup with Scaffolds
 ====================================
 
-So far we have done all of our *Quick Glance* as a single Python file.
+So far we have done all of our *Quick Tour* as a single Python file.
 No Python packages, no structure. Most Pyramid projects, though,
 aren't developed this way.
 
@@ -464,7 +479,7 @@ let's use that scaffold to make our project:
 
     $ pcreate --scaffold pyramid_jinja2_starter hello_world
 
-We next use the normal Python development to setup our package for
+We next use the normal Python command to set up our package for
 development:
 
 .. code-block:: bash
@@ -482,7 +497,7 @@ configuration. This includes a new way of running your application:
 
 Let's look at ``pserve`` and configuration in more depth.
 
-.. seealso:: See Also:
+.. seealso:: See also:
     :ref:`Quick Tutorial Scaffolds <qtut_scaffolds>`,
     :ref:`project_narr`, and
     :doc:`../narr/scaffolding`
@@ -513,13 +528,13 @@ Most of the work, though, comes from your project's wiring, as
 expressed in the configuration file you supply to ``pserve``. Let's
 take a look at this configuration file.
 
-.. seealso:: See Also:
+.. seealso:: See also:
     :ref:`what_is_this_pserve_thing`
 
 Configuration with ``.ini`` Files
 =================================
 
-Earlier in *Quick Glance* we first met Pyramid's configuration system.
+Earlier in *Quick Tour* we first met Pyramid's configuration system.
 At that point we did all configuration in Python code. For example,
 the port number chosen for our HTTP server was right there in Python
 code. Our scaffold has moved this decision, and more, into the
@@ -541,8 +556,8 @@ into sections:
 
 We have a few decisions made for us in this configuration:
 
-#. *Choice of web server*. The ``use = egg:pyramid#wsgiref`` tell
-   ``pserve`` to the ``wsgiref`` server that is wrapped in the Pyramid
+#. *Choice of web server*. The ``use = egg:pyramid#wsgiref`` tells
+   ``pserve`` to use the ``wsgiref`` server that is wrapped in the Pyramid
    package.
 
 #. *Port number*. ``port = 6543`` tells ``wsgiref`` to listen on port
@@ -559,9 +574,9 @@ We have a few decisions made for us in this configuration:
 
 Additionally, the ``development.ini`` generated by this scaffold wired
 up Python's standard logging. We'll now see in the console, for example,
-a log on every request that comes in, as well traceback information.
+a log on every request that comes in, as well as traceback information.
 
-.. seealso:: See Also:
+.. seealso:: See also:
     :ref:`Quick Tutorial Application Configuration <qtut_ini>`,
     :ref:`environment_chapter` and
     :doc:`../narr/paste`
@@ -570,7 +585,7 @@ a log on every request that comes in, as well traceback information.
 Easier Development with ``debugtoolbar``
 ========================================
 
-As we introduce the basics we also want to show how to be productive in
+As we introduce the basics, we also want to show how to be productive in
 development and debugging. For example, we just discussed template
 reloading and earlier we showed ``--reload`` for application reloading.
 
@@ -616,7 +631,7 @@ you want to disable this toolbar, no need to change code: you can
 remove it from ``pyramid.includes`` in the relevant ``.ini``
 configuration file.
 
-.. seealso:: See Also:
+.. seealso:: See also:
     :ref:`Quick Tutorial
     pyramid_debugtoolbar <qtut_debugtoolbar>` and
     :ref:`pyramid_debugtoolbar <toolbar:overview>`
@@ -670,7 +685,7 @@ Pyramid supplies helpers for test writing, which we use in the
 test setup and teardown. Our one test imports the view,
 makes a dummy request, and sees if the view returns what we expected.
 
-.. seealso:: See Also:
+.. seealso:: See also:
     :ref:`Quick Tutorial Unit Testing <qtut_unit_testing>`,
     :ref:`Quick Tutorial Functional Testing <qtut_functional_testing>`,
     and
@@ -685,12 +700,12 @@ we might need to detect situations when other people use the site. We
 need *logging*.
 
 Fortunately Pyramid uses the normal Python approach to logging. The
-scaffold generated, in your ``development.ini``, a number of lines that
+scaffold generated in your ``development.ini`` a number of lines that
 configure the logging for you to some reasonable defaults. You then see
-messages sent by Pyramid (for example, when a new request comes in.)
+messages sent by Pyramid (for example, when a new request comes in).
 
 Maybe you would like to log messages in your code? In your Python
-module, import and setup the logging:
+module, import and set up the logging:
 
 .. literalinclude:: quick_tour/package/hello_world/views.py
     :start-after: Start Logging 1
@@ -711,13 +726,13 @@ controls that? These sections in the configuration file:
     :start-after: Start Sphinx Include
     :end-before: End Sphinx Include
 
-Our application, a package named ``hello_world``, is setup as a logger
+Our application, a package named ``hello_world``, is set up as a logger
 and configured to log messages at a ``DEBUG`` or higher level. When you
 visit ``http://localhost:6543`` your console will now show::
 
  2013-08-09 10:42:42,968 DEBUG [hello_world.views][MainThread] Some Message
 
-.. seealso:: See Also:
+.. seealso:: See also:
     :ref:`Quick Tutorial Logging <qtut_logging>` and
     :ref:`logging_chapter`
 
@@ -728,9 +743,9 @@ When people use your web application, they frequently perform a task
 that requires semi-permanent data to be saved. For example, a shopping
 cart. This is called a :term:`session`.
 
-Pyramid has basic built-in support for sessions, with add-ons such as
-``pyramid_redis_sessions`` (or your own custom sessioning engine) that provide 
-richer session support. Let's take a look at the
+Pyramid has basic built-in support for sessions.  Third party packages such as
+``pyramid_redis_sessions`` provide richer session support.  Or you can create
+your own custom sessioning engine.  Let's take a look at the
 :doc:`built-in sessioning support <../narr/sessions>`. In our
 ``__init__.py`` we first import the kind of sessioning we want:
 
@@ -765,7 +780,7 @@ Jinja2 template:
     :start-after: Start Sphinx Include 1
     :end-before: End Sphinx Include 1
 
-.. seealso:: See Also:
+.. seealso:: See also:
     :ref:`Quick Tutorial Sessions <qtut_sessions>`,
     :ref:`sessions_chapter`, :ref:`flash_messages`,
     :ref:`session_module`, and :term:`pyramid_redis_sessions`.
@@ -774,7 +789,7 @@ Databases
 =========
 
 Web applications mean data. Data means databases. Frequently SQL
-databases. SQL Databases frequently mean an "ORM"
+databases. SQL databases frequently mean an "ORM"
 (object-relational mapper.) In Python, ORM usually leads to the
 mega-quality *SQLAlchemy*, a Python package that greatly eases working
 with databases.
@@ -813,7 +828,7 @@ of the system, can then easily get at the data thanks to SQLAlchemy:
     :start-after: Start Sphinx Include
     :end-before: End Sphinx Include
 
-.. seealso:: See Also:
+.. seealso:: See also:
     :ref:`Quick Tutorial Databases <qtut_databases>`,
     `SQLAlchemy <http://www.sqlalchemy.org/>`_,
     :ref:`making_a_console_script`,
@@ -876,7 +891,7 @@ Also, the ``deform_bootstrap`` Pyramid add-on restyles the stock Deform
 widgets using attractive CSS from Bootstrap and more powerful widgets
 from Chosen.
 
-.. seealso:: See Also:
+.. seealso:: See also:
     :ref:`Quick Tutorial Forms <qtut_forms>`,
     :ref:`Deform <deform:overview>`,
     :ref:`Colander <colander:overview>`, and
diff --git a/docs/quick_tutorial/authentication.rst b/docs/quick_tutorial/authentication.rst
index 8380a75ed..4b4eb1ba3 100644
--- a/docs/quick_tutorial/authentication.rst
+++ b/docs/quick_tutorial/authentication.rst
@@ -130,5 +130,5 @@ Extra Credit
    onto each request? Use ``import pdb; pdb.set_trace()`` to answer
    this.
 
-.. seealso:: :ref:`security_chapter`,
-   :ref:`AuthTktAuthenticationPolicy <authentication_module>`
+.. seealso:: See also :ref:`security_chapter`,
+   :ref:`AuthTktAuthenticationPolicy <authentication_module>`.
diff --git a/docs/quick_tutorial/debugtoolbar.rst b/docs/quick_tutorial/debugtoolbar.rst
index d25588c49..1c540d8a2 100644
--- a/docs/quick_tutorial/debugtoolbar.rst
+++ b/docs/quick_tutorial/debugtoolbar.rst
@@ -39,7 +39,6 @@ Steps
     $ $VENV/bin/python setup.py develop
     $ $VENV/bin/easy_install pyramid_debugtoolbar
 
-
 #. Our ``debugtoolbar/development.ini`` gets a configuration entry for
    ``pyramid.includes``:
 
@@ -86,4 +85,29 @@ start to experience otherwise inexplicable client-side weirdness, you can shut
 it off by commenting out the ``pyramid_debugtoolbar`` line in
 ``pyramid.includes`` temporarily.
 
-.. seealso:: See Also: :ref:`pyramid_debugtoolbar <toolbar:overview>`
+.. seealso:: See also :ref:`pyramid_debugtoolbar <toolbar:overview>`.
+
+Extra Credit
+============
+
+# Why don't we add ``pyramid_debugtoolbar`` to the list of
+  ``install_requires`` dependencies in ``debugtoolbar/setup.py``?
+
+# Introduce a bug into your application:  Change:
+
+  .. code-block:: python
+
+    def hello_world(request):
+        return Response('<body><h1>Hello World!</h1></body>')
+
+  to:
+
+  .. code-block:: python
+
+    def hello_world(request):
+        return xResponse('<body><h1>Hello World!</h1></body>')
+
+  Save, and visit http://localhost:6543/ again.  Notice the nice
+  traceback display.  On the lowest line, click the "screen" icon to the
+  right, and try typing the variable names ``request`` and ``Response``.
+  What else can you discover?
diff --git a/docs/quick_tutorial/debugtoolbar/tutorial/__init__.py b/docs/quick_tutorial/debugtoolbar/tutorial/__init__.py
index 0993b25be..d784292ee 100644
--- a/docs/quick_tutorial/debugtoolbar/tutorial/__init__.py
+++ b/docs/quick_tutorial/debugtoolbar/tutorial/__init__.py
@@ -3,7 +3,7 @@ from pyramid.response import Response
 
 
 def hello_world(request):
-    return xResponse('<body><h1>Hello World!</h1></body>')
+    return Response('<body><h1>Hello World!</h1></body>')
 
 
 def main(global_config, **settings):
diff --git a/docs/quick_tutorial/forms/tutorial/wikipage_addedit.pt b/docs/quick_tutorial/forms/tutorial/wikipage_addedit.pt
index d1fea0d7f..3292dfd90 100644
--- a/docs/quick_tutorial/forms/tutorial/wikipage_addedit.pt
+++ b/docs/quick_tutorial/forms/tutorial/wikipage_addedit.pt
@@ -4,10 +4,10 @@
     <title>WikiPage: Add/Edit</title>
     <tal:block tal:repeat="reqt view.reqts['css']">
         <link rel="stylesheet" type="text/css"
-              href="${request.static_url('deform:static/' + reqt)}"/>
+              href="${request.static_url(reqt)}"/>
     </tal:block>
     <tal:block tal:repeat="reqt view.reqts['js']">
-        <script src="${request.static_url('deform:static/' + reqt)}"
+        <script src="${request.static_url(reqt)}"
                 type="text/javascript"></script>
     </tal:block>
 </head>
diff --git a/docs/quick_tutorial/hello_world.rst b/docs/quick_tutorial/hello_world.rst
index c7a8eaf5e..86e1319f0 100644
--- a/docs/quick_tutorial/hello_world.rst
+++ b/docs/quick_tutorial/hello_world.rst
@@ -71,11 +71,11 @@ New to Python web programming? If so, some lines in module merit
 explanation:
 
 #. *Line 11*. The ``if __name__ == '__main__':`` is Python's way of
-   saying "Start here when running from the command line".
+   saying "Start here when running from the command line", rather than
+   when this module is imported.
 
 #. *Lines 12-14*. Use Pyramid's :term:`configurator` to connect
-   :term:`view` code to a particular URL
-   :term:`route`.
+   :term:`view` code to a particular URL :term:`route`.
 
 #. *Lines 6-7*. Implement the view code that generates the
    :term:`response`.
@@ -111,4 +111,4 @@ Extra Credit
    then reload your browser. See the exception in the console?
 
 #. The ``GI`` in ``WSGI`` stands for "Gateway Interface". What web
-   standard is this modelled after?
\ No newline at end of file
+   standard is this modelled after?
diff --git a/docs/quick_tutorial/ini.rst b/docs/quick_tutorial/ini.rst
index 618b8e5e8..3402c50e8 100644
--- a/docs/quick_tutorial/ini.rst
+++ b/docs/quick_tutorial/ini.rst
@@ -98,18 +98,16 @@ the Pyramid chapter on
 
 The ``.ini`` file is also used for two other functions:
 
-- *Choice of WSGI server*. ``[server:main]`` wires up the choice of WSGI
-  *server* for your WSGI *application*. In this case, we are using
-  ``wsgiref`` bundled in the Python library.
+- *Configuring the WSGI server*. ``[server:main]`` wires up the choice of
+  which WSGI *server* for your WSGI *application*. In this case, we are using
+  ``wsgiref`` bundled in the Python library.  It also wires up the *port
+  number*:   ``port = 6543`` tells ``wsgiref`` to listen on port 6543.
 
-- *Python logging*. Pyramid uses Python standard logging, which needs a
-  number of configuration values. The ``.ini`` serves this function.
+- *Configuring Python logging*. Pyramid uses Python standard logging, which
+  needs a number of configuration values. The ``.ini`` serves this function.
   This provides the console log output that you see on startup and each
   request.
 
-- *Port number*. ``port = 6543`` tells ``wsgiref`` to listen on port
-  6543.
-
 We moved our startup code from ``app.py`` to the package's
 ``tutorial/__init__.py``. This isn't necessary,
 but it is a common style in Pyramid to take the WSGI app bootstrapping
@@ -131,7 +129,7 @@ Extra Credit
    might you want to do that?
 
 #. The entry point in ``setup.py`` didn't mention ``__init__.py`` when
-   it the ``main`` function. Why not?
+   it declared ``tutorial:main`` function. Why not?
 
 .. seealso::
    :ref:`project_narr`,
diff --git a/docs/quick_tutorial/logging.rst b/docs/quick_tutorial/logging.rst
index 0167e5249..855ded59f 100644
--- a/docs/quick_tutorial/logging.rst
+++ b/docs/quick_tutorial/logging.rst
@@ -76,4 +76,4 @@ visit http://localhost:6543 your console will now show::
 Also, if you have configured your Pyramid application to use the
 ``pyramid_debugtoolbar``, logging statements appear in one of its menus.
 
-.. seealso:: See Also: :ref:`logging_chapter`
+.. seealso:: See also :ref:`logging_chapter`.
diff --git a/docs/quick_tutorial/more_view_classes.rst b/docs/quick_tutorial/more_view_classes.rst
index 21b353b7c..1e5603554 100644
--- a/docs/quick_tutorial/more_view_classes.rst
+++ b/docs/quick_tutorial/more_view_classes.rst
@@ -18,11 +18,10 @@ or a Python class. In this last case, methods on the class can be
 decorated with ``@view_config`` to register the class methods with the
 :term:`configurator` as a view.
 
-So far our views have been simple, free-standing functions. Many times
+At first, our views were simple, free-standing functions. Many times
 your views are related: different ways to look at or work on the same
 data or a REST API that handles multiple operations. Grouping these
-together as a
-:ref:`view class <class_as_view>` makes sense:
+together as a :ref:`view class <class_as_view>` makes sense:
 
 - Group views
 
@@ -30,9 +29,9 @@ together as a
 
 - Share some state and helpers
 
-Pyramid views have
-:ref:`view predicates <view_configuration_parameters>` that
-help determine which view is matched to a request. These predicates
+Pyramid views have :ref:`view predicates <view_configuration_parameters>`
+that determine which view is matched to a request, based on factors
+such as the request method, the form parameters, etc. These predicates
 provide many axes of flexibility.
 
 The following shows a simple example with four operations operations:
diff --git a/docs/quick_tutorial/more_view_classes/tutorial/views.py b/docs/quick_tutorial/more_view_classes/tutorial/views.py
index fdba04ba8..635de0520 100644
--- a/docs/quick_tutorial/more_view_classes/tutorial/views.py
+++ b/docs/quick_tutorial/more_view_classes/tutorial/views.py
@@ -20,7 +20,6 @@ class TutorialViews:
     def home(self):
         return {'page_title': 'Home View'}
 
-
     # Retrieving /howdy/first/last the first time
     @view_config(renderer='hello.pt')
     def hello(self):
@@ -33,7 +32,8 @@ class TutorialViews:
         return {'page_title': 'Edit View', 'new_name': new_name}
 
     # Posting to /home via the "Delete" submit button
-    @view_config(request_param='form.delete', renderer='delete.pt')
+    @view_config(request_method='POST', request_param='form.delete',
+                 renderer='delete.pt')
     def delete(self):
         print ('Deleted')
         return {'page_title': 'Delete View'}
diff --git a/docs/quick_tutorial/package.rst b/docs/quick_tutorial/package.rst
index 90d022b29..8fb052d5b 100644
--- a/docs/quick_tutorial/package.rst
+++ b/docs/quick_tutorial/package.rst
@@ -22,8 +22,7 @@ Explaining it all in this
 tutorial will induce madness. For this tutorial, this is all you need to
 know:
 
-- We will have a directory for each tutorial step as a
-  setuptools *project*
+- We will have a directory for each tutorial step as a setuptools *project*
 
 - This project will contain a ``setup.py`` which injects the features
   of the setuptool's project machinery into the directory
@@ -97,8 +96,8 @@ In this step we have a Python package called ``tutorial``. We use the
 same name in each step of the tutorial, to avoid unnecessary re-typing.
 
 Above this ``tutorial`` directory we have the files that handle the
-packaging of this, well, package. At the moment, all we need is a
-bare-bones ``ini/setup.py``.
+packaging of this project. At the moment, all we need is a
+bare-bones ``setup.py``.
 
 Everything else is the same about our application. We simply made a
 Python package with a ``setup.py`` and installed it in development mode.
diff --git a/docs/quick_tutorial/requirements.rst b/docs/quick_tutorial/requirements.rst
index 234e4aa0d..72bb4a4f8 100644
--- a/docs/quick_tutorial/requirements.rst
+++ b/docs/quick_tutorial/requirements.rst
@@ -226,25 +226,28 @@ during this tutorial:
     # Mac and Linux
     $ $VENV/bin/easy_install nose webtest deform sqlalchemy \
        pyramid_chameleon pyramid_debugtoolbar waitress \
-       pyramid_jinja2 pyramid_tm zope.sqlalchemy
+       pyramid_tm zope.sqlalchemy
 
     # Windows
-    c:\> %VENV%\Scripts\easy_install nose webtest deform sqlalchemy pyramid_chameleon
-
+    c:\> %VENV%\Scripts\easy_install nose webtest deform sqlalchemy pyramid_chameleon pyramid_debugtoolbar waitress pyramid_tm zope.sqlalchemy
 
 
 .. note::
 
     Why ``easy_install`` and not ``pip``? Pyramid encourages use of namespace
-    packages which, until recently, ``pip`` didn't permit. Also, Pyramid has
-    some optional C extensions for performance. With ``easy_install``, Windows
-    users can get these extensions without needing a C compiler.
-
-.. seealso:: See Also: :ref:`installing_unix`. For instructions to set up your
+    packages, for which ``pip``'s support is less-than-optimal. Also, Pyramid's
+    dependencies use some optional C extensions for performance:   with
+    ``easy_install``, Windows users can get these extensions without needing
+    a C compiler (``pip`` does not support installing binary Windows
+    distributions, except for ``wheels``, which are not yet available for
+    all dependencies).
+
+.. seealso:: See also :ref:`installing_unix`. For instructions to set up your
     Python environment for development using Windows or Python 2, see Pyramid's
     :ref:`Before You Install <installing_chapter>`.
 
-    See also Python 3's :mod:`venv module <python3:venv>`, the `setuptools` `installation instructions
+    See also Python 3's :mod:`venv module <python3:venv>`, the `setuptools
+    installation instructions
     <https://pypi.python.org/pypi/setuptools/0.9.8#installation-instructions>`_,
     and `easy_install help <https://pypi.python.org/pypi/setuptools/0.9.8#using-setuptools-and-easyinstall>`_.
 
diff --git a/docs/quick_tutorial/scaffolds.rst b/docs/quick_tutorial/scaffolds.rst
index 8ca2d27df..4f2694100 100644
--- a/docs/quick_tutorial/scaffolds.rst
+++ b/docs/quick_tutorial/scaffolds.rst
@@ -63,11 +63,11 @@ Steps
 
    On startup, ``pserve`` logs some output:
 
-   .. code-block:: bash
+    .. code-block:: bash
 
-     Starting subprocess with file monitor
-     Starting server in PID 72213.
-     Starting HTTP server on http://0.0.0.0:6543
+        Starting subprocess with file monitor
+        Starting server in PID 72213.
+        Starting HTTP server on http://0.0.0.0:6543
 
 #. Open http://localhost:6543/ in your browser.
 
diff --git a/docs/quick_tutorial/templating/setup.py b/docs/quick_tutorial/templating/setup.py
index 2221b72e9..0b71b73e6 100644
--- a/docs/quick_tutorial/templating/setup.py
+++ b/docs/quick_tutorial/templating/setup.py
@@ -2,7 +2,7 @@ from setuptools import setup
 
 requires = [
     'pyramid',
-    'pyramid_chameleon'
+    'pyramid_chameleon',
 ]
 
 setup(name='tutorial',
@@ -11,4 +11,4 @@ setup(name='tutorial',
       [paste.app_factory]
       main = tutorial:main
       """,
-)
\ No newline at end of file
+)
diff --git a/docs/quick_tutorial/tutorial_approach.rst b/docs/quick_tutorial/tutorial_approach.rst
index 52d768306..204d388b0 100644
--- a/docs/quick_tutorial/tutorial_approach.rst
+++ b/docs/quick_tutorial/tutorial_approach.rst
@@ -4,9 +4,9 @@ Tutorial Approach
 
 This tutorial uses conventions to keep the introduction focused and
 concise. Details, references, and deeper discussions are mentioned in
-"See Also" notes.
+"See also" notes.
 
-.. seealso:: This is an example "See Also" note.
+.. seealso:: This is an example "See also" note.
 
 This "Getting Started" tutorial is broken into independent steps,
 starting with the smallest possible "single file WSGI app" example.
@@ -42,4 +42,4 @@ Each of the first-level directories (e.g. ``request_response``) is a
 *Python project* (except, as noted, the ``hello_world`` step.) The
 ``tutorial`` directory is a *Python package*. At the end of each step,
 we copy a previous directory into a new directory to use as a starting
-point.
\ No newline at end of file
+point.
diff --git a/docs/quick_tutorial/unit_testing.rst b/docs/quick_tutorial/unit_testing.rst
index ed33f62d7..f8a33b39d 100644
--- a/docs/quick_tutorial/unit_testing.rst
+++ b/docs/quick_tutorial/unit_testing.rst
@@ -116,4 +116,4 @@ Extra Credit
 #. Why do we import the ``hello_world`` view function *inside* the
    ``test_hello_world`` method instead of at the top of the module?
 
-.. seealso:: See Also: :ref:`testing_chapter`
+.. seealso:: See also :ref:`testing_chapter`
diff --git a/docs/tutorials/wiki2/authorization.rst b/docs/tutorials/wiki2/authorization.rst
index 1e5d0dcbf..2e35574fd 100644
--- a/docs/tutorials/wiki2/authorization.rst
+++ b/docs/tutorials/wiki2/authorization.rst
@@ -207,6 +207,21 @@ routes:
    :linenos:
    :language: python
 
+.. note:: The preceding lines must be added *before* the following
+   ``view_page`` route definition:
+
+   .. literalinclude:: src/authorization/tutorial/__init__.py
+      :lines: 32
+      :linenos:
+      :language: python
+
+   This is because ``view_page``'s route definition uses a catch-all
+   "replacement marker" ``/{pagename}`` (see :ref:`route_pattern_syntax`)
+   which will catch any route that was not already caught by any
+   route listed above it in ``__init__.py``. Hence, for ``login`` and
+   ``logout`` views to have the opportunity of being matched
+   (or "caught"), they must be above ``/{pagename}``.
+
 Add Login and Logout Views
 ~~~~~~~~~~~~~~~~~~~~~~~~~~
 
diff --git a/docs/whatsnew-1.0.rst b/docs/whatsnew-1.0.rst
index 8750863e7..9541f0a28 100644
--- a/docs/whatsnew-1.0.rst
+++ b/docs/whatsnew-1.0.rst
@@ -114,8 +114,11 @@ Scaffold Improvements
   scaffolds now use a default "commit veto" hook when configuring the
   ``repoze.tm2`` transaction manager in ``development.ini``.  This prevents a
   transaction from being committed when the response status code is within
-  the 400 or 500 ranges.  See also
-  http://docs.repoze.org/tm2/#using-a-commit-veto.
+  the 400 or 500 ranges.
+  
+  .. seealso::
+     
+     See also http://docs.repoze.org/tm2/#using-a-commit-veto.
 
 Terminology Changes
 ~~~~~~~~~~~~~~~~~~~
diff --git a/docs/whatsnew-1.1.rst b/docs/whatsnew-1.1.rst
index 086c12ca2..99737b6d8 100644
--- a/docs/whatsnew-1.1.rst
+++ b/docs/whatsnew-1.1.rst
@@ -454,10 +454,13 @@ Deprecations and Behavior Differences
                      renderer='some/renderer.pt')
 
   This deprecation was done to reduce confusion observed in IRC, as well as
-  to (eventually) reduce documentation burden (see also
-  https://github.com/Pylons/pyramid/issues/164).  A deprecation warning is
-  now issued when any view-related parameter is passed to
-  ``add_route``.
+  to (eventually) reduce documentation burden.  A deprecation warning is
+  now issued when any view-related parameter is passed to ``add_route``.
+  
+  .. seealso::
+  
+     See also `issue #164 on GitHub
+     <https://github.com/Pylons/pyramid/issues/164>`_.
 
 - Passing an ``environ`` dictionary to the ``__call__`` method of a
   "traverser" (e.g. an object that implements
@@ -537,8 +540,12 @@ Deprecations and Behavior Differences
   subdirectory, the ``index.html`` of that subdirectory would not be served
   properly.  Instead, a redirect to ``/subdir`` would be issued.  This has
   been fixed, and now visiting a subdirectory that contains an ``index.html``
-  within a static view returns the index.html properly.  See also
-  https://github.com/Pylons/pyramid/issues/67.
+  within a static view returns the index.html properly.
+  
+  .. seealso::
+  
+     See also `issue #67 on GitHub
+     <https://github.com/Pylons/pyramid/issues/67>`_.
 
 - Deprecated the ``pyramid.config.Configurator.set_renderer_globals_factory``
   method and the ``renderer_globals`` Configurator constructor parameter.