14 files changed, 108 insertions, 58 deletions
diff --git a/docs/narr/events.rst b/docs/narr/events.rst
index 2accb3dbe..50484761d 100644
--- a/docs/narr/events.rst
+++ b/docs/narr/events.rst
@@ -172,7 +172,7 @@ track of the information that subscribers will need. Here are some
 example custom event classes:
 
 .. code-block:: python
-   :linenos:
+    :linenos:
 
     class DocCreated(object):
         def __init__(self, doc, request):
@@ -196,7 +196,7 @@ also use custom events with :ref:`subscriber predicates
 event with a decorator:
 
 .. code-block:: python
-   :linenos:
+    :linenos:
 
     from pyramid.events import subscriber
     from .events import DocCreated
@@ -215,7 +215,7 @@ To fire your custom events use the
 accessed as ``request.registry.notify``. For example:
 
 .. code-block:: python
-   :linenos:
+    :linenos:
 
     from .events import DocCreated
 
diff --git a/docs/narr/extending.rst b/docs/narr/extending.rst
index a60a49fea..8462a9da7 100644
--- a/docs/narr/extending.rst
+++ b/docs/narr/extending.rst
@@ -234,7 +234,7 @@ For example, if the original application has the following
 ``configure_views`` configuration method:
 
 .. code-block:: python
-   :linenos:
+    :linenos:
 
     def configure_views(config):
         config.add_view('theoriginalapp.views.theview', name='theview')
diff --git a/docs/narr/hooks.rst b/docs/narr/hooks.rst
index 0c450fad7..f2542f1d7 100644
--- a/docs/narr/hooks.rst
+++ b/docs/narr/hooks.rst
@@ -363,7 +363,7 @@ and modify the set of :term:`renderer globals` before they are passed to a
 that can be used for this purpose.  For example:
 
 .. code-block:: python
-   :linenos:
+    :linenos:
 
     from pyramid.events import subscriber
     from pyramid.events import BeforeRender
@@ -963,8 +963,8 @@ For full details, please read the `Venusian documentation
 
 .. _registering_tweens:
 
-Registering "Tweens"
---------------------
+Registering Tweens
+------------------
 
 .. versionadded:: 1.2
    Tweens
@@ -976,26 +976,80 @@ feature that may be used by Pyramid framework extensions, to provide, for
 example, Pyramid-specific view timing support bookkeeping code that examines
 exceptions before they are returned to the upstream WSGI application.  Tweens
 behave a bit like :term:`WSGI` :term:`middleware` but they have the benefit of
-running in a context in which they have access to the Pyramid
-:term:`application registry` as well as the Pyramid rendering machinery.
+running in a context in which they have access to the Pyramid :term:`request`,
+:term:`response` and :term:`application registry` as well as the Pyramid
+rendering machinery.
 
-Creating a Tween Factory
-~~~~~~~~~~~~~~~~~~~~~~~~
+Creating a Tween
+~~~~~~~~~~~~~~~~
 
-To make use of tweens, you must construct a "tween factory".  A tween factory
+To create a tween, you must write a "tween factory".  A tween factory
 must be a globally importable callable which accepts two arguments:
 ``handler`` and ``registry``.  ``handler`` will be the either the main
 Pyramid request handling function or another tween.  ``registry`` will be the
 Pyramid :term:`application registry` represented by this Configurator.  A
-tween factory must return a tween when it is called.
+tween factory must return the tween (a callable object) when it is called.
 
-A tween is a callable which accepts a :term:`request` object and returns
-a :term:`response` object.
+A tween is called with a single argument, ``request``, which is the
+:term:`request` created by Pyramid's router when it receives a WSGI request.
+A tween should return a :term:`response`, usually the one generated by the
+downstream Pyramid application.
 
-Here's an example of a tween factory:
+You can write the tween factory as a simple closure-returning function:
 
 .. code-block:: python
-   :linenos:
+    :linenos:
+
+    def simple_tween_factory(handler, registry):
+        # one-time configuration code goes here
+
+        def simple_tween(request):
+            # code to be executed for each request before
+            # the actual application code goes here
+
+            response = handler(request)
+
+            # code to be executed for each request after
+            # the actual application code goes here
+
+            return response
+
+        return simple_tween
+
+Alternatively, the tween factory can be a class with the ``__call__`` magic
+method:
+
+.. code-block:: python
+    :linenos:
+
+    class simple_tween_factory(object):
+        def __init__(handler, registry):
+            self.handler = handler
+            self.registry = registry
+
+            # one-time configuration code goes here
+
+        def __call__(self, request):
+            # code to be executed for each request before
+            # the actual application code goes here
+
+            response = self.handler(request)
+
+            # code to be executed for each request after
+            # the actual application code goes here
+
+            return response
+
+The closure style performs slightly better and enables you to conditionally
+omit the tween from the request processing pipeline (see the following timing
+tween example), whereas the class style makes it easier to have shared mutable
+state, and it allows subclassing.
+
+Here's a complete example of a tween that logs the time spent processing each
+request:
+
+.. code-block:: python
+    :linenos:
 
     # in a module named myapp.tweens
 
@@ -1022,12 +1076,6 @@ Here's an example of a tween factory:
         # handler
         return handler
 
-If you remember, a tween is an object which accepts a :term:`request` object
-and which returns a :term:`response` argument.  The ``request`` argument to a
-tween will be the request created by Pyramid's router when it receives a WSGI
-request.  The response object will be generated by the downstream Pyramid
-application and it should be returned by the tween.
-
 In the above example, the tween factory defines a ``timing_tween`` tween and
 returns it if ``asbool(registry.settings.get('do_timing'))`` is true.  It
 otherwise simply returns the handler it was given.  The ``registry.settings``
@@ -1053,7 +1101,7 @@ Here's an example of registering a tween factory as an "implicit" tween in a
 Pyramid application:
 
 .. code-block:: python
-   :linenos:
+    :linenos:
 
     from pyramid.config import Configurator
     config = Configurator()
@@ -1087,7 +1135,7 @@ chain (the tween generated by the very last tween factory added) as its
 request handler function.  For example:
 
 .. code-block:: python
-   :linenos:
+    :linenos:
 
     from pyramid.config import Configurator
 
@@ -1132,8 +1180,10 @@ Allowable values for ``under`` or ``over`` (or both) are:
   fallbacks if the desired tween is not included, as well as compatibility
   with multiple other tweens.
 
-Effectively, ``under`` means "closer to the main Pyramid application than",
-``over`` means "closer to the request ingress than".
+Effectively, ``over`` means "closer to the request ingress than" and
+``under`` means "closer to the main Pyramid application than".
+You can think of an onion with outer layers over the inner layers,
+the application being under all the layers at the center.
 
 For example, the following call to
 :meth:`~pyramid.config.Configurator.add_tween` will attempt to place the
@@ -1329,7 +1379,7 @@ route predicate factory is most often a class with a constructor
 method. For example:
 
 .. code-block:: python
-   :linenos:
+    :linenos:
 
     class ContentTypePredicate(object):
         def __init__(self, val, config):
@@ -1392,7 +1442,7 @@ with a subscriber that subscribes to the :class:`pyramid.events.NewRequest`
 event type.
 
 .. code-block:: python
-   :linenos:
+    :linenos:
 
     class RequestPathStartsWith(object):
         def __init__(self, val, config):
@@ -1421,7 +1471,7 @@ previously registered ``request_path_startswith`` predicate in a call to
 :meth:`~pyramid.config.Configurator.add_subscriber`:
 
 .. code-block:: python
-   :linenos:
+    :linenos:
 
     # define a subscriber in your code
 
@@ -1437,7 +1487,7 @@ Here's the same subscriber/predicate/event-type combination used via
 :class:`~pyramid.events.subscriber`.
 
 .. code-block:: python
-   :linenos:
+    :linenos:
 
     from pyramid.events import subscriber
 
diff --git a/docs/narr/hybrid.rst b/docs/narr/hybrid.rst
index a29ccb2ac..4a3258d35 100644
--- a/docs/narr/hybrid.rst
+++ b/docs/narr/hybrid.rst
@@ -63,7 +63,7 @@ An application that uses only traversal will have view configuration
 declarations that look like this:
 
 .. code-block:: python
-   :linenos:
+    :linenos:
 
     # config is an instance of pyramid.config.Configurator
 
diff --git a/docs/narr/i18n.rst b/docs/narr/i18n.rst
index b62c16ff0..c9b782c08 100644
--- a/docs/narr/i18n.rst
+++ b/docs/narr/i18n.rst
@@ -309,7 +309,7 @@ In particular, add the ``Babel`` and ``lingua`` distributions to the
 application's ``setup.py`` file:
 
 .. code-block:: python
-   :linenos:
+    :linenos:
 
     setup(name="mypackage",
           # ...
@@ -370,7 +370,7 @@ file of a ``pcreate`` -generated :app:`Pyramid` application has stanzas in it
 that look something like the following:
 
 .. code-block:: ini
-   :linenos:
+    :linenos:
 
     [compile_catalog]
     directory = myproject/locale
@@ -398,7 +398,7 @@ that you'd like the domain of your translations to be ``mydomain``
 instead, change the ``setup.cfg`` file stanzas to look like so:
 
 .. code-block:: ini
-   :linenos:
+    :linenos:
 
     [compile_catalog]
     directory = myproject/locale
@@ -1041,7 +1041,7 @@ if no locale can be determined.
 Here's an implementation of a simple locale negotiator:
 
 .. code-block:: python
-   :linenos:
+    :linenos:
 
     def my_locale_negotiator(request):
         locale_name = request.params.get('my_locale')
diff --git a/docs/narr/introduction.rst b/docs/narr/introduction.rst
index a9c5fdfbd..8acbab3a0 100644
--- a/docs/narr/introduction.rst
+++ b/docs/narr/introduction.rst
@@ -336,7 +336,7 @@ For example, instead of returning a ``Response`` object from a
 ``render_to_response`` call:
 
 .. code-block:: python
-   :linenos:
+    :linenos:
 
     from pyramid.renderers import render_to_response
 
@@ -347,7 +347,7 @@ For example, instead of returning a ``Response`` object from a
 You can return a Python dictionary:
 
 .. code-block:: python
-   :linenos:
+    :linenos:
 
     from pyramid.view import view_config
 
@@ -827,7 +827,7 @@ Here's an example of using Pyramid's introspector from within a view
 callable:
 
 .. code-block:: python
-   :linenos:
+    :linenos:
 
     from pyramid.view import view_config
     from pyramid.response import Response
diff --git a/docs/narr/introspector.rst b/docs/narr/introspector.rst
index 3c0a6744f..a7bde4cf7 100644
--- a/docs/narr/introspector.rst
+++ b/docs/narr/introspector.rst
@@ -24,7 +24,7 @@ Here's an example of using Pyramid's introspector from within a view
 callable:
 
 .. code-block:: python
-   :linenos:
+    :linenos:
 
     from pyramid.view import view_config
     from pyramid.response import Response
@@ -100,7 +100,7 @@ its ``__getitem__``, ``get``, ``keys``, ``values``, or ``items`` methods.
 For example:
 
 .. code-block:: python
-   :linenos:
+    :linenos:
 
     route_intr = introspector.get('routes', 'edit_user')
     pattern = route_intr['pattern']
diff --git a/docs/narr/logging.rst b/docs/narr/logging.rst
index b3bfb8a1e..75428d513 100644
--- a/docs/narr/logging.rst
+++ b/docs/narr/logging.rst
@@ -179,7 +179,7 @@ file, simply create a logger object using the ``__name__`` builtin and call
 methods on it.
 
 .. code-block:: python 
-   :linenos:
+    :linenos:
 
     import logging 
     log = logging.getLogger(__name__) 
diff --git a/docs/narr/resources.rst b/docs/narr/resources.rst
index 34d75f2cc..f3ff1dc4c 100644
--- a/docs/narr/resources.rst
+++ b/docs/narr/resources.rst
@@ -83,7 +83,7 @@ works against resource instances.
 Here's a sample resource tree, represented by a variable named ``root``:
 
 .. code-block:: python
-   :linenos:
+    :linenos:
 
     class Resource(dict):
         pass
diff --git a/docs/narr/scaffolding.rst b/docs/narr/scaffolding.rst
index 534b2caf4..f924d0d62 100644
--- a/docs/narr/scaffolding.rst
+++ b/docs/narr/scaffolding.rst
@@ -39,9 +39,9 @@ named ``__init__.py`` with something like the following:
 
    from pyramid.scaffolds import PyramidTemplate
 
-     class CoolExtensionTemplate(PyramidTemplate):
-         _template_dir = 'coolextension_scaffold'
-         summary = 'My cool extension'
+   class CoolExtensionTemplate(PyramidTemplate):
+       _template_dir = 'coolextension_scaffold'
+       summary = 'My cool extension'
 
 Once this is done, within the ``scaffolds`` directory, create a template
 directory.  Our example used a template directory named
@@ -89,7 +89,7 @@ For example:
             [pyramid.scaffold]
             coolextension=coolextension.scaffolds:CoolExtensionTemplate
           """
-         )
+        )
 
 Run your distribution's ``setup.py develop`` or ``setup.py install``
 command. After that, you should be able to see your scaffolding template
@@ -112,7 +112,7 @@ want to have extension scaffolds that can work across Pyramid 1.0.X, 1.1.X,
 defining your scaffold template:
 
 .. code-block:: python
-   :linenos:
+     :linenos:
 
      try: # pyramid 1.0.X
          # "pyramid.paster.paste_script..." doesn't exist past 1.0.X
diff --git a/docs/narr/upgrading.rst b/docs/narr/upgrading.rst
index 64343ca3e..eb3194a65 100644
--- a/docs/narr/upgrading.rst
+++ b/docs/narr/upgrading.rst
@@ -137,7 +137,7 @@ In the above case, it's line #3 in the ``myproj.views`` module (``from
 pyramid.view import static``) that is causing the problem:
 
 .. code-block:: python
-   :linenos:
+    :linenos:
 
     from pyramid.view import view_config
 
@@ -148,7 +148,7 @@ The deprecation warning tells me how to fix it, so I can change the code to
 do things the newer way:
 
 .. code-block:: python
-   :linenos:
+    :linenos:
 
     from pyramid.view import view_config
 
diff --git a/docs/narr/urldispatch.rst b/docs/narr/urldispatch.rst
index 61849c3c0..96ee5758e 100644
--- a/docs/narr/urldispatch.rst
+++ b/docs/narr/urldispatch.rst
@@ -492,7 +492,7 @@ The simplest route declaration which configures a route match to *directly*
 result in a particular view callable being invoked:
 
 .. code-block:: python
-   :linenos:
+    :linenos:
 
     config.add_route('idea', 'site/{id}')
     config.add_view('mypackage.views.site_view', route_name='idea')
@@ -901,7 +901,7 @@ Details of the route matching decision for a particular request to the
 which you started the application from.  For example:
 
 .. code-block:: text
-   :linenos:
+    :linenos:
 
     $ PYRAMID_DEBUG_ROUTEMATCH=true $VENV/bin/pserve development.ini
     Starting server in PID 13586.
@@ -1060,7 +1060,7 @@ A custom route predicate may also *modify* the ``match`` dictionary.  For
 instance, a predicate might do some type conversion of values:
 
 .. code-block:: python
-   :linenos:
+    :linenos:
 
     def integers(*segment_names):
         def predicate(info, request):
@@ -1086,7 +1086,7 @@ To avoid the try/except uncertainty, the route pattern can contain regular
 expressions specifying requirements for that marker. For instance:
 
 .. code-block:: python
-   :linenos:
+    :linenos:
 
     def integers(*segment_names):
         def predicate(info, request):
@@ -1128,7 +1128,7 @@ name.  The ``pattern`` attribute is the route pattern.  An example of using
 the route in a set of route predicates:
 
 .. code-block:: python
-   :linenos:
+    :linenos:
 
     def twenty_ten(info, request):
         if info['route'].name in ('ymd', 'ym', 'y'):
diff --git a/docs/narr/vhosting.rst b/docs/narr/vhosting.rst
index d37518052..53f6888b3 100644
--- a/docs/narr/vhosting.rst
+++ b/docs/narr/vhosting.rst
@@ -109,7 +109,7 @@ An example of an Apache ``mod_proxy`` configuration that will host the
 is below:
 
 .. code-block:: apache
-   :linenos:
+    :linenos:
 
     NameVirtualHost *:80
 
@@ -130,7 +130,7 @@ For a :app:`Pyramid` application running under :term:`mod_wsgi`,
 the same can be achieved using ``SetEnv``:
 
 .. code-block:: apache
-   :linenos:
+    :linenos:
 
     <Location />
       SetEnv HTTP_X_VHM_ROOT /cms
diff --git a/docs/narr/views.rst b/docs/narr/views.rst
index b2dd549ce..a746eb043 100644
--- a/docs/narr/views.rst
+++ b/docs/narr/views.rst
@@ -536,7 +536,7 @@ The following types work as view callables in this style:
    e.g.:
 
    .. code-block:: python
-      :linenos:
+       :linenos:
 
        from pyramid.response import Response