Merge branch 'master' into twophase

26 files changed, 235 insertions, 141 deletions

diff --git a/docs/narr/MyProject/setup.cfg b/docs/narr/MyProject/setup.cfg
index de38b5616..332e80a60 100644
--- a/docs/narr/MyProject/setup.cfg
+++ b/docs/narr/MyProject/setup.cfg
@@ -1,9 +1,9 @@
 [nosetests]
-match=^test
-nocapture=1
-cover-package=myproject
-with-coverage=1
-cover-erase=1
+match = ^test
+nocapture = 1
+cover-package = myproject
+with-coverage = 1
+cover-erase = 1
 
 [compile_catalog]
 directory = myproject/locale
diff --git a/docs/narr/configuration.rst b/docs/narr/configuration.rst
index ae02a5a6c..ea3a6c866 100644
--- a/docs/narr/configuration.rst
+++ b/docs/narr/configuration.rst
@@ -142,6 +142,7 @@ method, effectively:
 
 .. ignore-next-block
 .. code-block:: python
+   :linenos:
 
    config.add_view(hello)
 
diff --git a/docs/narr/declarative.rst b/docs/narr/declarative.rst
index b9dbcab7d..eeaed318f 100644
--- a/docs/narr/declarative.rst
+++ b/docs/narr/declarative.rst
@@ -65,8 +65,8 @@ previously created ``helloworld.py``:
      <include package="pyramid.includes" />
 
      <view
-        view="helloworld.hello_world"
-        />
+       view="helloworld.hello_world"
+      />
 
    </configure>
 
@@ -120,8 +120,8 @@ filesystem.  Let's take a look at that ``configure.zcml`` file again:
       <include package="pyramid.includes" />
 
       <view
-         view="helloworld.hello_world"
-         />
+        view="helloworld.hello_world"
+       />
 
    </configure>
 
@@ -181,11 +181,11 @@ start.  For example, the following ZCML file has two conflicting
 
       <view
         view="helloworld.hello_world"
-        />
+       />
 
       <view
         view="helloworld.hello_world"
-        />
+       />
 
     </configure>
 
@@ -241,13 +241,13 @@ the previously created ``helloworld.py``:
      <include package="pyramid.includes" />
 
      <view
-        view="helloworld.hello_world"
-        />
+       view="helloworld.hello_world"
+      />
 
      <view
        name="goodbye"
        view="helloworld.goodbye_world"
-       />
+      />
 
    </configure>
 
@@ -255,7 +255,7 @@ This pair of files forms an application functionally equivalent to the
 application we created earlier in :ref:`helloworld_imperative`.  We can run
 it the same way.
 
-.. code-block:: bash
+.. code-block:: text
 
    $ python helloworld.py
    serving on 0.0.0.0:8080 view at http://127.0.0.1:8080
@@ -308,13 +308,13 @@ which sits next to ``helloworld.py``.  Let's take a look at the
       <include package="pyramid.includes" />
 
       <view
-         view="helloworld.hello_world"
-         />
+        view="helloworld.hello_world"
+       />
 
       <view
-         name="goodbye"
-         view="helloworld.goodbye_world"
-         />
+        name="goodbye"
+        view="helloworld.goodbye_world"
+       />
 
    </configure>
 
@@ -352,6 +352,7 @@ The ``configure.zcml`` ZCML file contains this bit of XML within the
 ``<configure>`` root tag:
 
 .. code-block:: xml
+   :linenos:
 
    <include package="pyramid.includes" />
 
@@ -399,12 +400,12 @@ The ``configure.zcml`` ZCML file contains these bits of XML *after* the
 
    <view
      view="helloworld.hello_world"
-     />
+    />
 
    <view
      name="goodbye"
      view="helloworld.goodbye_world"
-     />
+    />
 
 These ``<view>`` declaration tags direct :app:`Pyramid` to create
 two :term:`view configuration` registrations.  The first ``<view>``
@@ -451,12 +452,12 @@ completely equivalent:
 
      <view
        view="helloworld.hello_world"
-       />
+      />
 
      <view
        name="goodbye"
        view="helloworld.goodbye_world"
-       />
+      />
 
 .. topic:: Goodbye Before Hello
 
@@ -466,11 +467,11 @@ completely equivalent:
      <view
        name="goodbye"
        view="helloworld.goodbye_world"
-       />
+      />
 
      <view
        view="helloworld.hello_world"
-       />
+      />
 
 We've now configured a :app:`Pyramid` helloworld application
 declaratively.  More information about this mode of configuration is
@@ -556,10 +557,10 @@ example of a view declaration in ZCML is as follows:
    :linenos:
 
    <view
-       context=".models.Hello"
-       view=".views.hello_world"
-       name="hello.html"
-       />
+     context=".models.Hello"
+     view=".views.hello_world"
+     name="hello.html"
+    />
 
 The above maps the ``.views.hello_world`` view callable function to
 the following set of :term:`context finding` results:
@@ -589,9 +590,9 @@ type:
    :linenos:
 
    <view
-       context=".models.Hello"
-       view=".views.hello_world"
-       />
+     context=".models.Hello"
+     view=".views.hello_world"
+    />
 
 A *default view callable* simply has no ``name`` attribute.  For the
 above registration, when a :term:`context` is found that is of the
@@ -607,10 +608,10 @@ string as its ``name`` attribute:
    :linenos:
 
    <view
-       context=".models.Hello"
-       view=".views.hello_world"
-       name=""
-       />
+     context=".models.Hello"
+     view=".views.hello_world"
+     name=""
+    />
 
 You may also declare that a view callable is good for any context type
 by using the special ``*`` character as the value of the ``context``
@@ -620,10 +621,10 @@ attribute:
    :linenos:
 
    <view
-       context="*"
-       view=".views.hello_world"
-       name="hello.html"
-       />
+     context="*"
+     view=".views.hello_world"
+     name="hello.html"
+    />
 
 This indicates that when :app:`Pyramid` identifies that the
 :term:`view name` is ``hello.html`` and the context is of any type,
@@ -654,9 +655,9 @@ declaration` causes a route to be added to the application.
    :linenos:
 
    <route
-       name="myroute"
-       pattern="/prefix/{one}/{two}"
-       view=".views.myview"
+     name="myroute"
+     pattern="/prefix/{one}/{two}"
+     view=".views.myview"
     />
 
 .. note::
@@ -705,9 +706,9 @@ absolute path.
    :linenos:
 
    <static
-      name="static"
-      path="/var/www/static"
-      />
+     name="static"
+     path="/var/www/static"
+    />
 
 Here's an example of a ``static`` directive that will serve files up
 under the ``/static`` URL from the ``a/b/c/static`` directory of the
@@ -718,9 +719,9 @@ Python package named ``some_package`` using a fully qualified
    :linenos:
 
    <static
-      name="static"
-      path="some_package:a/b/c/static"
-      />
+     name="static"
+     path="some_package:a/b/c/static"
+    />
 
 Here's an example of a ``static`` directive that will serve files up
 under the ``/static`` URL from the ``static`` directory of the Python
@@ -731,9 +732,9 @@ package-relative path.
    :linenos:
 
    <static
-      name="static"
-      path="static"
-      />
+     name="static"
+     path="static"
+    />
 
 Whether you use for ``path`` a fully qualified resource specification,
 an absolute path, or a package-relative path, When you place your
@@ -764,9 +765,9 @@ argument which is ``http://example.com/images``:
    :linenos:
 
    <static
-      name="http://example.com/images"
-      path="mypackage:images"
-      />
+     name="http://example.com/images"
+     path="mypackage:images"
+    />
 
 Because the ``static`` ZCML directive is provided with a ``name`` argument
 that is the URL prefix ``http://example.com/images``, subsequent calls to
@@ -808,7 +809,7 @@ this:
      <!-- views and other directives before this... -->
 
      <authtktauthenticationpolicy
-          secret="iamsosecret"/>
+       secret="iamsosecret"/>
 
      <aclauthorizationpolicy/>
 
@@ -852,16 +853,16 @@ An example of its usage, with all attributes fully expanded:
    :linenos:
 
    <authtktauthenticationpolicy
-    secret="goshiamsosecret"
-    callback=".somemodule.somefunc"
-    cookie_name="mycookiename"
-    secure="false"
-    include_ip="false"
-    timeout="86400"
-    reissue_time="600"
-    max_age="31536000"
-    path="/"
-    http_only="false"
+     secret="goshiamsosecret"
+     callback=".somemodule.somefunc"
+     cookie_name="mycookiename"
+     secure="false"
+     include_ip="false"
+     timeout="86400"
+     reissue_time="600"
+     max_age="31536000"
+     path="/"
+     http_only="false"
     />
 
 See :ref:`authtktauthenticationpolicy_directive` for details about
@@ -880,8 +881,8 @@ An example of its usage, with all attributes fully expanded:
    :linenos:
 
    <remoteuserauthenticationpolicy
-    environ_key="REMOTE_USER"
-    callback=".somemodule.somefunc"
+     environ_key="REMOTE_USER"
+     callback=".somemodule.somefunc"
     />
 
 See :ref:`remoteuserauthenticationpolicy_directive` for detailed
@@ -900,8 +901,8 @@ An example of its usage, with all attributes fully expanded:
    :linenos:
 
    <repozewho1authenticationpolicy
-    identifier_name="auth_tkt"
-    callback=".somemodule.somefunc"
+     identifier_name="auth_tkt"
+     callback=".somemodule.somefunc"
     />
 
 See :ref:`repozewho1authenticationpolicy_directive` for detailed
@@ -953,7 +954,8 @@ For example, to add a renderer which renders views which have a
 
    <renderer
      name=".jinja2"
-     factory="my.package.MyJinja2Renderer"/>
+     factory="my.package.MyJinja2Renderer"
+    />
 
 The ``factory`` attribute is a :term:`dotted Python name` that must
 point to an implementation of a :term:`renderer factory`.
@@ -972,7 +974,8 @@ See :ref:`adding_a_renderer` for more information for the definition of a
 
    <renderer
      name="amf"
-     factory="my.package.MyAMFRenderer"/>
+     factory="my.package.MyAMFRenderer"
+    />
 
 Adding the above ZCML to your application will allow you to use the
 ``my.package.MyAMFRenderer`` renderer factory implementation in view
@@ -983,8 +986,9 @@ attribute of a :term:`view configuration`:
    :linenos:
 
    <view
-    view="mypackage.views.my_view"
-    renderer="amf"/>
+     view="mypackage.views.my_view"
+     renderer="amf"
+    />
 
 Here's an example of the registration of a more complicated renderer
 factory, which expects to be passed a filesystem path:
@@ -994,7 +998,8 @@ factory, which expects to be passed a filesystem path:
 
    <renderer
      name=".jinja2"
-     factory="my.package.MyJinja2Renderer"/>
+     factory="my.package.MyJinja2Renderer"
+    />
 
 Adding the above ZCML to your application will allow you to use the
 ``my.package.MyJinja2Renderer`` renderer factory implementation in
@@ -1006,8 +1011,9 @@ configuration`:
    :linenos:
 
    <view
-    view="mypackage.views.my_view"
-    renderer="templates/mytemplate.jinja2"/>
+     view="mypackage.views.my_view"
+     renderer="templates/mytemplate.jinja2"
+    />
 
 When a :term:`view configuration` which has a ``name`` attribute that does
 contain a dot, such as ``templates/mytemplate.jinja2`` above is encountered at
@@ -1038,8 +1044,9 @@ renderer factory, use:
    :linenos:
 
    <renderer
-      name=".zpt"
-      factory="pyramid.chameleon_zpt.renderer_factory"/>
+     name=".zpt"
+     factory="pyramid.chameleon_zpt.renderer_factory"
+    />
 
 After you do this, :app:`Pyramid` will treat templates ending in
 both the ``.pt`` and ``.zpt`` filename extensions as Chameleon ZPT
@@ -1053,8 +1060,9 @@ a variation on the following in your application's ZCML:
    :linenos:
 
    <renderer
-      name=".pt"
-      factory="my.package.pt_renderer"/>
+     name=".pt"
+     factory="my.package.pt_renderer"
+    />
 
 After you do this, the :term:`renderer factory` in
 ``my.package.pt_renderer`` will be used to render templates which end
@@ -1068,8 +1076,9 @@ variation on the following in your application's ZCML:
    :linenos:
 
    <renderer
-      name=".txt"
-      factory="my.package.text_renderer"/>
+     name=".txt"
+     factory="my.package.text_renderer"
+    />
 
 After you do this, the :term:`renderer factory` in
 ``my.package.text_renderer`` will be used to render templates which
@@ -1084,7 +1093,8 @@ tag):
    :linenos:
 
    <renderer
-      factory="pyramid.renderers.json_renderer_factory"/>
+     factory="pyramid.renderers.json_renderer_factory"
+    />
 
 See also :ref:`renderer_directive` and
 :meth:`pyramid.configuration.Configurator.add_renderer`.
@@ -1123,7 +1133,8 @@ You can add a custom locale negotiator via ZCML by using the
    :linenos:
 
     <localenegotiator 
-       negotiator="my_application.my_module.my_locale_negotiator"/>
+      negotiator="my_application.my_module.my_locale_negotiator"
+     />
 
 See also :ref:`custom_locale_negotiator` and
 :ref:`localenegotiator_directive`.
@@ -1145,8 +1156,8 @@ which we assume lives in a ``subscribers.py`` module within your application:
    :linenos:
 
    <subscriber
-      for="pyramid.events.NewRequest"
-      handler=".subscribers.mysubscriber"
+     for="pyramid.events.NewRequest"
+     handler=".subscribers.mysubscriber"
     />
 
 See also :ref:`subscriber_directive` and :ref:`events_chapter`.
diff --git a/docs/narr/environment.rst b/docs/narr/environment.rst
index c3fe401ec..44e75542c 100644
--- a/docs/narr/environment.rst
+++ b/docs/narr/environment.rst
@@ -38,7 +38,10 @@ application-specific configuration settings.
 Reloading Templates
 -------------------
 
-When this value is true, reload templates without a restart.
+When this value is true, reload templates without a restart, so you can see
+changes to templates take effect immediately during development.  This flag
+is meaningful to Chameleon and Mako templates, as well as most third-party
+template rendering extensions.
 
 +---------------------------------+-----------------------------+
 | Environment Variable Name       | Config File Setting Name    |
@@ -278,6 +281,7 @@ Setting Name" column would go in the ``[app:main]`` section.  Here's
 an example of such a section:
 
 .. code-block:: ini
+  :linenos:
 
   [app:main]
   use = egg:MyProject#app
@@ -288,7 +292,7 @@ You can also use environment variables to accomplish the same purpose
 for settings documented as such.  For example, you might start your
 :app:`Pyramid` application using the following command line:
 
-.. code-block:: python
+.. code-block:: text
 
   $ BFG_DEBUG_AUTHORIZATION=1 BFG_RELOAD_TEMPLATES=1 bin/paster serve \
          MyProject.ini
diff --git a/docs/narr/extending.rst b/docs/narr/extending.rst
index 49de50722..902fb001d 100644
--- a/docs/narr/extending.rst
+++ b/docs/narr/extending.rst
@@ -190,9 +190,10 @@ the original application with slight tweaks.  For example:
 .. code-block:: xml
    :linenos:
 
-    <view context="theoriginalapplication.models.SomeModel"
-          name="theview"
-          view=".views.a_view_that_does_something_slightly_different"
+    <view 
+      context="theoriginalapplication.models.SomeModel"
+      name="theview"
+      view=".views.a_view_that_does_something_slightly_different"
      />
 
 A similar pattern can be used to *extend* the application with
diff --git a/docs/narr/firstapp.rst b/docs/narr/firstapp.rst
index 9d3cad13c..c49e788b0 100644
--- a/docs/narr/firstapp.rst
+++ b/docs/narr/firstapp.rst
@@ -47,7 +47,7 @@ When this code is inserted into a Python script named ``helloworld.py`` and
 executed by a Python interpreter which has the :app:`Pyramid` software
 installed, an HTTP server is started on TCP port 8080:
 
-.. code-block:: bash
+.. code-block:: text
 
    $ python helloworld.py
    serving on 0.0.0.0:8080 view at http://127.0.0.1:8080
@@ -263,6 +263,7 @@ WSGI Application Creation
 
 .. ignore-next-block
 .. code-block:: python
+   :linenos:
 
    app = config.make_wsgi_app()
 
@@ -294,6 +295,7 @@ WSGI Application Serving
 
 .. ignore-next-block
 .. code-block:: python
+   :linenos:
 
    serve(app, host='0.0.0.0')
 
diff --git a/docs/narr/handlers.rst b/docs/narr/handlers.rst
index d82f42bdb..0dce6afe4 100644
--- a/docs/narr/handlers.rst
+++ b/docs/narr/handlers.rst
@@ -37,6 +37,7 @@ will call that view callable.
 Here's an example view handler class:
 
 .. code-block:: python
+    :linenos:
     
     from pyramid.response import Response
    
@@ -58,6 +59,7 @@ An accompanying call to the
 be performed in order to register it with the system:
 
 .. code-block:: python
+    :linenos:
 
     config.add_handler('hello', '/hello/{action}', handler=Hello)
 
@@ -74,6 +76,7 @@ Alternatively, the action can be declared specifically for a URL to go to a
 specific ``action`` name:
 
 .. code-block:: python
+    :linenos:
     
     config.add_handler('hello_index', '/hello/index', 
                        handler=Hello, action='index')
@@ -97,6 +100,7 @@ directly through to :meth:`pyramid.configuration.Configurator.add_route`.
 For example:
 
 .. code-block:: python
+    :linenos:
     
     config.add_handler('hello', '/hello/{action}',
                        handler='mypackage.handlers:MyHandler')
@@ -110,6 +114,7 @@ specify the same handler, to register specific route names for different
 handler/action combinations. For example:
 
 .. code-block:: python
+    :linenos:
     
     config.add_handler('hello_index', '/hello/index', 
                        handler=Hello, action='index')
@@ -139,6 +144,7 @@ Every method in the handler class that has a name meeting the
 disabled by setting the ``__autoexpose__`` attribute to ``None``:
 
 .. code-block:: python
+    :linenos:
 
     from pyramid.view import action
    
@@ -179,6 +185,7 @@ name that is different from the method name by passing in a ``name`` argument.
 Example:
 
 .. code-block:: python
+    :linenos:
     
     from pyramid.view import action
    
@@ -205,6 +212,7 @@ URL's can result in different template renderings with the same data.
 Example:
 
 .. code-block:: python
+    :linenos:
     
     from pyramid.view import action
    
diff --git a/docs/narr/hooks.rst b/docs/narr/hooks.rst
index 2bb66e559..ada96f897 100644
--- a/docs/narr/hooks.rst
+++ b/docs/narr/hooks.rst
@@ -54,7 +54,8 @@ class as the ``context`` of the view configuration.
 
       <view
         view="helloworld.views.notfound_view"
-        context="pyramid.exceptions.NotFound"/>
+        context="pyramid.exceptions.NotFound"
+       />
 
    Replace ``helloworld.views.notfound_view`` with the Python dotted name
    to the notfound view you want to use.
@@ -142,7 +143,8 @@ class as the ``context`` of the view configuration.
 
       <view
         view="helloworld.views.notfound_view"
-        context="pyramid.exceptions.Forbidden"/>
+        context="pyramid.exceptions.Forbidden"
+       />
 
    Replace ``helloworld.views.forbidden_view`` with the Python
    dotted name to the forbidden view you want to use.
@@ -203,7 +205,7 @@ change the default traverser:
       factory="myapp.traversal.Traverser"
       provides="pyramid.interfaces.ITraverser"
       for="*"
-      />
+     />
 
 In the example above, ``myapp.traversal.Traverser`` is assumed to be
 a class that implements the following interface:
@@ -254,7 +256,7 @@ traverser would be used.  For example:
       factory="myapp.traversal.Traverser"
       provides="pyramid.interfaces.ITraverser"
       for="myapp.models.MyRoot"
-      />
+     />
 
 If the above stanza was added to a ``configure.zcml`` file,
 :app:`Pyramid` would use the ``myapp.traversal.Traverser`` only
@@ -287,7 +289,7 @@ of :term:`context` by adding an adapter stanza for
       factory="myapp.traversal.URLGenerator"
       provides="pyramid.interfaces.IContextURL"
       for="myapp.models.MyRoot *"
-      />
+     />
 
 In the above example, the ``myapp.traversal.URLGenerator`` class will
 be used to provide services to :func:`pyramid.url.model_url` any
diff --git a/docs/narr/hybrid.rst b/docs/narr/hybrid.rst
index e704463c7..df8d72ef4 100644
--- a/docs/narr/hybrid.rst
+++ b/docs/narr/hybrid.rst
@@ -262,7 +262,7 @@ to do.
   :class:`pyramid.configuration.Configurator` constructor instead
   of associating it with a particular route inside the route's
   configuration.  Every hybrid route configuration that is matched but
-  which does *not* name a ``factory``` attribute will use the use
+  which does *not* name a ``factory`` attribute will use the use
   global ``root_factory`` function to generate a root object.
 
 When the route configuration named ``home`` above is matched during a
diff --git a/docs/narr/i18n.rst b/docs/narr/i18n.rst
index 9e2071872..603b08cef 100644
--- a/docs/narr/i18n.rst
+++ b/docs/narr/i18n.rst
@@ -104,7 +104,9 @@ right translator file on the filesystem which contains translations
 for a given domain.  In this case, if it were trying to translate
 our msgid to German, it might try to find a translation from a
 :term:`gettext` file within a :term:`translation directory` like this
-one::
+one:
+
+.. code-block:: text
 
    locale/de/LC_MESSAGES/form.mo
 
@@ -268,7 +270,7 @@ If the :term:`virtualenv` into which you've installed your
 :app:`Pyramid` application lives in ``/my/virtualenv``, you can
 install Babel like so:
 
-.. code-block:: bash
+.. code-block:: text
 
    $ cd /my/virtualenv
    $ bin/easy_install Babel
@@ -280,7 +282,7 @@ If the :term:`virtualenv` into which you've installed your
 :app:`Pyramid` application lives in ``C:\my\virtualenv``, you can
 install Babel like so:
 
-.. code-block:: bash
+.. code-block:: text
 
    C> cd \my\virtualenv
    C> bin\easy_install Babel
@@ -307,9 +309,9 @@ In particular, add the ``Babel`` distribution to the
    :linenos:
 
     setup(name="mypackage",
-          ...
+          # ...
           install_requires = [
-                ....
+                # ...
                 'Babel',
                 ],
           message_extractors = { '.': [
@@ -336,8 +338,7 @@ message catalog template from the code and :term:`Chameleon` templates
 which reside in your :app:`Pyramid` application.  You run a
 ``setup.py`` command to extract the messages:
 
-.. code-block:: bash
-   :linenos:
+.. code-block:: text
 
    $ cd /place/where/myapplication/setup.py/lives
    $ mkdir -p myapplication/locale
@@ -424,7 +425,9 @@ in the ``.pot`` file, you need to generate at least one ``.po`` file.
 A ``.po`` file represents translations of a particular set of messages
 to a particular locale.  Initialize a ``.po`` file for a specific
 locale from a pre-generated ``.pot`` template by using the ``setup.py
-init_catalog`` command::
+init_catalog`` command:
+
+.. code-block:: text
 
    $ cd /place/where/myapplication/setup.py/lives
    $ python setup.py init_catalog -l es
@@ -455,7 +458,7 @@ changed messages can also be translated or re-translated.
 First, regenerate the ``.pot`` file as per :ref:`extracting_messages`.
 Then use the ``setup.py update_catalog`` command.
 
-.. code-block:: bash
+.. code-block:: text
 
    $ cd /place/where/myapplication/setup.py/lives
    $ python setup.py update_catalog
@@ -469,7 +472,9 @@ Compiling a Message Catalog File
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 Finally, to prepare an application for performing actual runtime
-translations, compile ``.po`` files to ``.mo`` files::
+translations, compile ``.po`` files to ``.mo`` files:
+
+.. code-block:: text
 
    $ cd /place/where/myapplication/setup.py/lives
    $ python setup.py compile_catalog
@@ -812,16 +817,18 @@ mechanism:
 Allow a deployer to modify your application's PasteDeploy .ini file:
 
 .. code-block:: ini
+   :linenos:
 
    [app:main]
    use = egg:MyProject#app
-   ...
+   # ...
    available_languages = fr de en ru
 
 Then as a part of the code of a custom :term:`locale negotiator`:
 
-.. code-block:: py
-
+.. code-block:: python
+   :linenos:
+    
    from pyramid.threadlocal import get_current_registry
    settings = get_current_registry().settings
    languages = settings['available_languages'].split()
@@ -877,7 +884,7 @@ application startup.  For example:
    config.begin()
    config.add_translation_dirs('my.application:locale/', 
                                'another.application:locale/')
-   ...
+   # ...
    config.end()
 
 A message catalog in a translation directory added via
diff --git a/docs/narr/install.rst b/docs/narr/install.rst
index c753b7298..db1cfaf9d 100644
--- a/docs/narr/install.rst
+++ b/docs/narr/install.rst
@@ -334,7 +334,7 @@ The ``pyramid_jinja2`` distribution provides templating for
 :app:`Pyramid` using the :term:`Jinja2` templating system.  You may
 install it like so using the ``easy_install`` command for Jython:
 
-.. code-block:: python
+.. code-block:: text
 
    $ easy_install pyramid_jinja2
 
@@ -342,7 +342,7 @@ Once this is done, you can use this command to get started with a
 :app:`Pyramid` sample application that uses the Jinja2 templating
 engine:
 
-.. code-block:: python
+.. code-block:: text
 
    $ paster create -t pyramid_jinja2_starter
 
diff --git a/docs/narr/modelgraphtraverser.png b/docs/narr/modelgraphtraverser.png
index 053bb9913..037d12b18 100644
--- a/docs/narr/modelgraphtraverser.png
+++ b/docs/narr/modelgraphtraverser.png
diff --git a/docs/narr/models.rst b/docs/narr/models.rst
index f8488cc80..20f443571 100644
--- a/docs/narr/models.rst
+++ b/docs/narr/models.rst
@@ -272,6 +272,7 @@ The ``__parent__`` of the root object should be ``None`` and its
 ``__name__`` should be the empty string.  For instance:
 
 .. code-block:: python
+   :linenos:
 
    class MyRootObject(object):
        __name__ = ''
diff --git a/docs/narr/project.rst b/docs/narr/project.rst
index 8901c1a4e..b2b0931b6 100644
--- a/docs/narr/project.rst
+++ b/docs/narr/project.rst
@@ -271,7 +271,7 @@ points to *your application* as opposed to any other section within the
 If so, you can use the following command to invoke a debug shell using
 the name ``MyProject`` as a section name:
 
-.. code-block::  text
+.. code-block:: text
 
    [chrism@vitaminf shellenv]$ ../bin/paster pshell development.ini MyProject
    Python 2.4.5 (#1, Aug 29 2008, 12:27:37) 
@@ -288,7 +288,7 @@ happen, even if you have IPython installed, you can pass the
 ``--disable-ipython`` flag to the ``pshell`` command to use a standard
 Python interpreter shell unconditionally.
 
-.. code-block::  text
+.. code-block:: text
 
    [chrism@vitaminf shellenv]$ ../bin/paster pshell --disable-ipython \
                                 development.ini MyProject
@@ -303,7 +303,7 @@ Python interpreter shell unconditionally.
    than an ``app``.  For example, if you have the following ``.ini`` file
    content:
 
-   .. code-block:: ini
+   .. code-block:: guess
       :linenos:
 
       [app:MyProject]
@@ -315,8 +315,9 @@ Python interpreter shell unconditionally.
       default_locale_name = en
 
       [pipeline:main]
-      pipeline = egg:WebError#evalerror
-                 MyProject
+      pipeline = 
+          egg:WebError#evalerror
+          MyProject
 
    Use ``MyProject`` instead of ``main`` as the section name argument to
    ``pshell`` against the above ``.ini`` file (e.g. ``paster pshell
@@ -432,7 +433,9 @@ name except for case).  All :app:`Pyramid` ``paster`` -generated projects
 share a similar structure.
 
 The ``MyProject`` project we've generated has the following directory
-structure::
+structure:
+
+.. code-block:: text
 
   MyProject/
   |-- CHANGES.txt
@@ -493,6 +496,7 @@ serve``, as well as the deployment settings provided to that application.
 The generated ``development.ini`` file looks like so:
 
 .. literalinclude:: MyProject/development.ini
+   :language: guess
    :linenos:
 
 This file contains several "sections" including ``[app:MyProject]``,
@@ -618,6 +622,7 @@ distributing your application.
 Our generated ``setup.py`` looks like this:
 
 .. literalinclude:: MyProject/setup.py
+   :language: python
    :linenos:
 
 The ``setup.py`` file calls the setuptools ``setup`` function, which
@@ -655,7 +660,7 @@ file when distributing your application to other people, or when
 versioning your application for your own use.  For fun, you can try
 this command now:
 
-.. code-block:: python
+.. code-block:: text
 
    $ python setup.py sdist
 
@@ -686,6 +691,7 @@ contains various settings related to testing and internationalization:
 Our generated ``setup.cfg`` looks like this:
 
 .. literalinclude:: MyProject/setup.cfg
+   :language: guess
    :linenos:
 
 The values in the default setup file allow various commonly-used
@@ -733,6 +739,7 @@ This is the file named ``__init__.py``.  The presence of an ``__init__.py``
 also informs Python that the directory which contains it is a *package*.
 
 .. literalinclude:: MyProject/myproject/__init__.py
+   :language: python
    :linenos:
 
 #. Line 1 imports the :term:`Configurator` class from
@@ -779,6 +786,7 @@ code which accepts a :term:`request` and which returns a
 :term:`response`.
 
 .. literalinclude:: MyProject/myproject/views.py
+   :language: python
    :linenos:
 
 This bit of code was registered as the view callable within ``__init__.py``
@@ -825,6 +833,7 @@ and provide APIs which mutate and return this data.  We write a class
 named ``MyModel`` that provides the behavior.
 
 .. literalinclude:: MyProject/myproject/models.py
+   :language: python
    :linenos:
 
 #. Lines 1-2 define the MyModel class.
@@ -871,6 +880,7 @@ by view functions themselves.  See :ref:`templates_used_directly` and
 The ``tests.py`` module includes unit tests for your application.
 
 .. literalinclude:: MyProject/myproject/tests.py
+   :language: python
    :linenos:
 
 This sample ``tests.py`` file has a single unit test defined within
@@ -920,6 +930,7 @@ Then change the __init__.py of your myproject project (*not* the
 parent directory).  For example, from something like:
 
 .. code-block:: python
+    :linenos:
 
     config.add_view('myproject.views.my_view',
                     renderer='myproject:templates/mytemplate.pt')
@@ -927,6 +938,7 @@ parent directory).  For example, from something like:
 To this:
 
 .. code-block:: python
+    :linenos:
 
     config.add_view('myproject.views.blogs.my_view',
                     renderer='myproject:templates/mytemplate.pt')
@@ -936,6 +948,7 @@ views or handler classes/functions within those files via the dotted name
 passed as the first argument to ``add_view``.  For example:
 
 .. code-block:: python
+    :linenos:
 
     config.add_view('myproject.views.anothermodule.my_view',
                     renderer='myproject:templates/anothertemplate.pt')
diff --git a/docs/narr/resources.rst b/docs/narr/resources.rst
index e98c34595..3ff8af90b 100644
--- a/docs/narr/resources.rst
+++ b/docs/narr/resources.rst
@@ -259,7 +259,7 @@ override a single resource.  For example:
     <resource
       to_override="some.package:templates/mytemplate.pt"
       override_with="another.package:othertemplates/anothertemplate.pt"
-    />
+     />
 
 The string value passed to both ``to_override`` and ``override_with``
 attached to a resource directive is called a "specification".  The
diff --git a/docs/narr/router.png b/docs/narr/router.png
index 229fb5cd5..606495f13 100644
--- a/docs/narr/router.png
+++ b/docs/narr/router.png
diff --git a/docs/narr/security.rst b/docs/narr/security.rst
index 8cf459880..2c696772a 100644
--- a/docs/narr/security.rst
+++ b/docs/narr/security.rst
@@ -436,6 +436,7 @@ authorization policy is in effect might look like so:
 the following:
 
 .. code-block:: python
+   :linenos:
 
    from pyramid.security import ALL_PERMISSIONS
    __acl__ = [ (Deny, Everyone, ALL_PERMISSIONS) ]
@@ -497,7 +498,9 @@ Debugging View Authorization Failures
 If your application in your judgment is allowing or denying view
 access inappropriately, start your application under a shell using the
 ``BFG_DEBUG_AUTHORIZATION`` environment variable set to ``1``.  For
-example::
+example:
+
+.. code-block:: text
 
   $ BFG_DEBUG_AUTHORIZATION=1 bin/paster serve myproject.ini
 
@@ -508,7 +511,10 @@ authentication information.
 
 This behavior can also be turned on in the application ``.ini`` file
 by setting the ``debug_authorization`` key to ``true`` within the
-application's configuration section, e.g.::
+application's configuration section, e.g.:
+
+.. code-block:: ini
+  :linenos:
 
   [app:main]
   use = egg:MyProject#app
@@ -551,6 +557,7 @@ authenticate.  Doing so is a matter of creating an instance of something
 that implements the following interface:
 
 .. code-block:: python
+   :linenos:
 
    class AuthenticationPolicy(object):
        """ An object representing a Pyramid authentication policy. """
@@ -606,6 +613,7 @@ matter of creating an instance of an object that implements the
 following interface:
 
 .. code-block:: python
+    :linenos:
 
     class IAuthorizationPolicy(object):
         """ An object representing a Pyramid authorization policy. """
diff --git a/docs/narr/startup.rst b/docs/narr/startup.rst
index 427acc319..9103bf20f 100644
--- a/docs/narr/startup.rst
+++ b/docs/narr/startup.rst
@@ -68,6 +68,7 @@ press ``return`` after running ``paster serve development.ini``.
    ``__init__.py`` module:
 
    .. literalinclude:: MyProject/myproject/__init__.py
+      :language: python
       :linenos:
 
    Note that the constructor function accepts a ``global_config``
@@ -83,6 +84,7 @@ press ``return`` after running ``paster serve development.ini``.
    Our generated ``development.ini`` file looks like so:
 
    .. literalinclude:: MyProject/development.ini
+      :language: guess
       :linenos:
 
    In this case, the ``myproject.run:app`` function referred to by the entry
diff --git a/docs/narr/static.rst b/docs/narr/static.rst
index a01cbbabf..beb12c586 100644
--- a/docs/narr/static.rst
+++ b/docs/narr/static.rst
@@ -185,6 +185,7 @@ resources which begin with ``mypackage:images`` will be prefixed with
 ``http://example.com/images``:
 
 .. code-block:: python
+   :linenos:
 
    static_url('mypackage:images/logo.png', request)
    # -> http://example.com/images/logo.png
diff --git a/docs/narr/templates.rst b/docs/narr/templates.rst
index f7929b44e..c1c2fe31e 100644
--- a/docs/narr/templates.rst
+++ b/docs/narr/templates.rst
@@ -543,7 +543,9 @@ you can create templates that are entirely composed of text except for
 
 Here's an example usage of a Chameleon text template.  Create a file
 on disk named ``mytemplate.txt`` in your project's ``templates``
-directory with the following contents::
+directory with the following contents:
+
+.. code-block:: text
 
    Hello, ${name}!
 
@@ -590,8 +592,7 @@ should cause it to ignore these files.  Here's the contents of the
 author's ``svn propedit svn:ignore .`` in each of my ``templates``
 directories.
 
-.. code-block:: bash
-   :linenos:
+.. code-block:: text
 
    *.pt.py
    *.txt.py
@@ -620,13 +621,18 @@ environment variable setting or a configuration file setting.
 
 To use an environment variable, start your application under a shell
 using the ``BFG_DEBUG_TEMPLATES`` operating system environment
-variable set to ``1``, For example::
+variable set to ``1``, For example:
+
+.. code-block:: text
 
   $ BFG_DEBUG_TEMPLATES=1 bin/paster serve myproject.ini
 
 To use a setting in the application ``.ini`` file for the same
 purpose, set the ``debug_templates`` key to ``true`` within the
-application's configuration section, e.g.::
+application's configuration section, e.g.:
+
+.. code-block:: ini
+  :linenos:
 
   [app:main]
   use = egg:MyProject#app
@@ -634,7 +640,9 @@ application's configuration section, e.g.::
 
 With template debugging off, a :exc:`NameError` exception resulting
 from rendering a template with an undefined variable
-(e.g. ``${wrong}``) might end like this::
+(e.g. ``${wrong}``) might end like this:
+
+.. code-block:: text
 
   File "...", in __getitem__
     raise NameError(key)
@@ -642,7 +650,9 @@ from rendering a template with an undefined variable
 
 Note that the exception has no information about which template was
 being rendered when the error occured.  But with template debugging
-on, an exception resulting from the same problem might end like so::
+on, an exception resulting from the same problem might end like so:
+
+.. code-block:: text
 
     RuntimeError: Caught exception rendering template.
      - Expression: ``wrong``
@@ -774,13 +784,18 @@ environment variable setting or a configuration file setting.
 
 To use an environment variable, start your application under a shell
 using the ``BFG_RELOAD_TEMPLATES`` operating system environment
-variable set to ``1``, For example::
+variable set to ``1``, For example:
+
+.. code-block:: text
 
   $ BFG_RELOAD_TEMPLATES=1 bin/paster serve myproject.ini
 
 To use a setting in the application ``.ini`` file for the same
 purpose, set the ``reload_templates`` key to ``true`` within the
-application's configuration section, e.g.::
+application's configuration section, e.g.:
+
+.. code-block:: ini
+  :linenos:
 
   [app:main]
   use = egg:MyProject#app
diff --git a/docs/narr/traversal.rst b/docs/narr/traversal.rst
index 56594ed5a..40c7503de 100644
--- a/docs/narr/traversal.rst
+++ b/docs/narr/traversal.rst
@@ -403,7 +403,9 @@ Let's pretend the user asks for
 ``http://example.com/foo/bar/baz/biz/buz.txt``. The request's
 ``PATH_INFO`` in that case is ``/foo/bar/baz/biz/buz.txt``.  Let's
 further pretend that when this request comes in that we're traversing
-the following object graph::
+the following object graph:
+
+.. code-block:: text
 
   /--
      |
@@ -448,7 +450,9 @@ Let's say that view lookup finds no matching view type.  In this
 circumstance, the :app:`Pyramid` :term:`router` returns the result
 of the :term:`not found view` and the request ends.
 
-However, for this graph::
+However, for this graph:
+
+.. code-block:: text
 
   /--
      |
diff --git a/docs/narr/urldispatch.rst b/docs/narr/urldispatch.rst
index df7d592f9..e439c71cd 100644
--- a/docs/narr/urldispatch.rst
+++ b/docs/narr/urldispatch.rst
@@ -350,7 +350,9 @@ also capture the remainder of the URL, for example:
     foo/{baz}/{bar}{fizzle:.*}
 
 The above pattern will match these URLs, generating the following
-matchdicts::
+matchdicts:
+
+.. code-block:: text
 
    foo/1/2/           -> {'baz':'1', 'bar':'2', 'fizzle':()}
    foo/abc/def/a/b/c  -> {'baz':'abc', 'bar':'def', 'fizzle': 'a/b/c')}
@@ -836,8 +838,8 @@ strings.  The values will be Unicode objects.
 
 .. note::
 
-   If no route URL pattern matches, no ``matchdict`` is attached to
-   the request.
+   If no route URL pattern matches, the ``matchdict`` object attached to the
+   request will be ``None``.
 
 .. index::
    single: matched_route
@@ -855,6 +857,11 @@ an attribute of the :term:`request` object.  Thus,
 request.  The most useful attribute of the route object is ``name``,
 which is the name of the route that matched.
 
+.. note::
+
+   If no route URL pattern matches, the ``matched_route`` object attached to
+   the request will be ``None``.
+
 Routing Examples
 ----------------
 
@@ -1141,6 +1148,7 @@ custom notfound view as the first argument to its constructor.  For
 instance:
 
 .. code-block:: python
+     :linenos:
 
      from pyramid.exceptions import NotFound
      from pyramid.view import AppendSlashNotFoundViewFactory
diff --git a/docs/narr/vhosting.rst b/docs/narr/vhosting.rst
index 0f0fd0d4d..d1fd1b382 100644
--- a/docs/narr/vhosting.rst
+++ b/docs/narr/vhosting.rst
@@ -40,6 +40,7 @@ Here's an example of a PasteDeploy configuration snippet that includes
 a ``urlmap`` composite.
 
 .. code-block:: ini
+  :linenos:
 
   [app:mypyramidapp]
   use = egg:mypyramidapp#app
diff --git a/docs/narr/views.rst b/docs/narr/views.rst
index c82dd2cb2..04d90fda8 100644
--- a/docs/narr/views.rst
+++ b/docs/narr/views.rst
@@ -469,7 +469,7 @@ You can configure a view to use the JSON renderer by naming ``json`` as the
    :linenos:
 
    config.add_view('myproject.views.hello_world', 
-                    name='hello'
+                    name='hello',
                     context='myproject.models.Hello',
                     renderer='json')
     
@@ -1459,6 +1459,7 @@ configuration stanza:
 
 .. ignore-next-block
 .. code-block:: python
+   :linenos:
 
    config.add_view('.views.my_view', name='my_view', request_method='POST', 
                    context=MyModel, permission='read')
@@ -1488,6 +1489,7 @@ view configuration.  To make :app:`Pyramid` process your
 ``scan`` method of a :class:`pyramid.configuration.Configurator`:
 
 .. code-block:: python
+   :linenos:
 
    # config is assumed to be an instance of the
    # pyramid.configuration.Configurator class
diff --git a/docs/narr/webob.rst b/docs/narr/webob.rst
index 17827fac9..92de9d409 100644
--- a/docs/narr/webob.rst
+++ b/docs/narr/webob.rst
@@ -288,6 +288,7 @@ Generally any attribute of the response can be passed in as a keyword
 argument to the class; e.g.:
 
 .. code-block:: python
+  :linenos:
 
   from pyramid.response import Response
   response = Response(body='hello world!', content_type='text/plain')
@@ -316,6 +317,7 @@ the same way.  A typical example is:
 
 .. ignore-next-block
 .. code-block:: python
+    :linenos:
 
     from pyramid.httpexceptions import HTTPNotFound
     from pyramid.httpexceptions import HTTPMovedPermanently
diff --git a/docs/narr/zca.rst b/docs/narr/zca.rst
index cf05f39ed..7c7617a3d 100644
--- a/docs/narr/zca.rst
+++ b/docs/narr/zca.rst
@@ -115,6 +115,7 @@ registry, the following bit of code is equivalent to
 ``zope.component.getUtility(IFoo)``:
 
 .. code-block:: python
+   :linenos:
 
    registry.getUtility(IFoo)