Merge branch 'master' into twophase

44 files changed, 305 insertions, 208 deletions

diff --git a/docs/Makefile b/docs/Makefile
index b74c55bd5..3d706d17e 100644
--- a/docs/Makefile
+++ b/docs/Makefile
@@ -59,8 +59,8 @@ latex:
 	$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) _build/latex
 	cp _static/*.png _build/latex
 	./convert_images.sh
-	cp _static/exclaim.png _build/latex
-	cp _static/info.png _build/latex
+	cp _static/latex-warning.png _build/latex
+	cp _static/latex-note.png _build/latex
 	@echo
 	@echo "Build finished; the LaTeX files are in _build/latex."
 	@echo "Run \`make all-pdf' or \`make all-ps' in that directory to" \
diff --git a/docs/_static/exclaim.png b/docs/_static/exclaim.png
deleted file mode 100644
index 6707bc362..000000000
--- a/docs/_static/exclaim.png
+++ /dev/null
diff --git a/docs/_static/exclaim_color.png b/docs/_static/exclaim_color.png
deleted file mode 100644
index dffff8784..000000000
--- a/docs/_static/exclaim_color.png
+++ /dev/null
diff --git a/docs/_static/info.png b/docs/_static/info.png
deleted file mode 100644
index 95d00a973..000000000
--- a/docs/_static/info.png
+++ /dev/null
diff --git a/docs/_static/info_color.png b/docs/_static/info_color.png
deleted file mode 100644
index bcaf288bd..000000000
--- a/docs/_static/info_color.png
+++ /dev/null
diff --git a/docs/_static/latex-note.png b/docs/_static/latex-note.png
new file mode 100644
index 000000000..7e1647837
--- /dev/null
+++ b/docs/_static/latex-note.png
diff --git a/docs/_static/latex-warning.png b/docs/_static/latex-warning.png
new file mode 100644
index 000000000..747b24529
--- /dev/null
+++ b/docs/_static/latex-warning.png
diff --git a/docs/_static/onebit_36.png b/docs/_static/onebit_36.png
deleted file mode 100755
index 70889fc16..000000000
--- a/docs/_static/onebit_36.png
+++ /dev/null
diff --git a/docs/_static/onebit_38.png b/docs/_static/onebit_38.png
deleted file mode 100755
index 4dcf07651..000000000
--- a/docs/_static/onebit_38.png
+++ /dev/null
diff --git a/docs/_static/pylons.png b/docs/_static/pylons.png
deleted file mode 100644
index 53f83e4d0..000000000
--- a/docs/_static/pylons.png
+++ /dev/null
diff --git a/docs/_static/pylons_small.png b/docs/_static/pylons_small.png
deleted file mode 100644
index 53f83e4d0..000000000
--- a/docs/_static/pylons_small.png
+++ /dev/null
diff --git a/docs/_static/pyramid_epub.css b/docs/_static/pyramid_epub.css
deleted file mode 100644
index 261500d82..000000000
--- a/docs/_static/pyramid_epub.css
+++ /dev/null
@@ -1,22 +0,0 @@
-@import url('default.css');
-/* body { */
-/*     background-color: #006339; */
-/* } */
- 
-/* div.document { */
-/*     background-color: #dad3bd; */
-/* } */
-
-/* div.sphinxsidebar h3, h4, h5, a { */
-/*     color: #127c56 !important; */
-/* } */
-
-/* div.related { */
-/*     color: #dad3bd !important; */
-/*     background-color: #00744a; */
-/* } */
- 
-/* div.related a { */
-/*     color: #dad3bd !important; */
-/* } */
-
diff --git a/docs/conf.py b/docs/conf.py
index 653f7ab15..6ef9ff67b 100644
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -109,6 +109,11 @@ add_module_names = False
 
 # The name of the Pygments (syntax highlighting) style to use.
 #pygments_style = book and 'bw' or 'tango'
+if book:
+    pygments_style = 'bw'
+
+# The default language to highlight source code in.
+#highlight_language = 'guess'
 
 # Options for HTML output
 # -----------------------
@@ -116,7 +121,7 @@ add_module_names = False
 # Add and use Pylons theme
 sys.path.append(os.path.abspath('_themes'))
 html_theme_path = ['_themes']
-html_theme = 'pylons'
+html_theme = 'pyramid'
 
 # The style sheet to use for HTML and HTML Help pages. A file of that name
 # must exist either in Sphinx' static/ path, or in one of the custom paths
@@ -128,21 +133,21 @@ html_theme = 'pylons'
 html_title = 'The Pyramid Web Application Development Framework v%s' % release
 
 # A shorter title for the navigation bar.  Default is the same as html_title.
-html_short_title = 'Home'
+#html_short_title = 'Home'
 
 # The name of an image file (within the static path) to place at the top of
 # the sidebar.
-html_logo = '_static/pyramid.png'
+#html_logo = '_static/pyramid.png'
 
 # The name of an image file (within the static path) to use as favicon of the
 # docs.  This file should be a Windows icon file (.ico) being 16x16 or 32x32
 # pixels large.
-#html_favicon = '_static/favicon.ico'
+#html_favicon = '_static/pyramid.ico'
 
 # Add any paths that contain custom static files (such as style sheets) here,
 # relative to this directory. They are copied after the builtin static files,
 # so a file named "default.css" will overwrite the builtin "default.css".
-html_static_path = ['_static']
+#html_static_path = ['_static']
 
 # If not '', a 'Last updated on:' timestamp is inserted at every page bottom,
 # using the given strftime format.
@@ -201,7 +206,7 @@ latex_documents = [
 
 # The name of an image file (relative to this directory) to place at the top of
 # the title page.
-latex_logo = '_static/pylons_small.png'
+#latex_logo = '_static/pylons_small.png'
 
 # For "manual" documents, if this is true, then toplevel headings are parts,
 # not chapters.
@@ -302,8 +307,8 @@ _PREAMBLE = r"""
 \renewenvironment{notice}[2]{%
   \origbeginnotice{#1}{}% equivalent to original \begin{notice}{#1}{#2}
   % load graphics
-  \ifthenelse{\equal{#1}{warning}}{\includegraphics{exclaim.png}}{}
-  \ifthenelse{\equal{#1}{note}}{\includegraphics{info.png}}{}
+  \ifthenelse{\equal{#1}{warning}}{\includegraphics{latex-warning.png}}{}
+  \ifthenelse{\equal{#1}{note}}{\includegraphics{latex-note.png}}{}
   % etc.
 }{%
   \origendnotice% equivalent to original \end{notice}
diff --git a/docs/conventions.rst b/docs/conventions.rst
index a764a372a..a17af7230 100644
--- a/docs/conventions.rst
+++ b/docs/conventions.rst
@@ -22,12 +22,12 @@ concept are presented in the following style:
 
 We present Python method names using the following style:
 
-  :meth:`Python.method_name`
+  :meth:`pyramid.configuration.Configurator.add_view`
 
 We present Python class names, module names, attributes and global
 variables using the following style:
 
-  :class:`Python.class_module_or_attribute.name`
+  :class:`pyramid.configuration.Configurator.registry`
 
 References to glossary terms are presented using the following style:
 
@@ -42,7 +42,7 @@ style:
 
   :ref:`traversal_chapter`
 
-Python code blocks are presented in the following style:
+Code and configuration file blocks are presented in the following style:
 
   .. code-block:: python
      :linenos:
@@ -50,15 +50,6 @@ Python code blocks are presented in the following style:
      def foo(abc):
          pass
 
-Blocks of XML markup are presented in the following style:
-
-  .. code-block:: xml
-     :linenos:
-
-     <root>
-       <!-- ... more XML .. -->
-     </root>
-
 When a command that should be typed on one line is too long to fit on
 a page, the backslash ``\`` is used to indicate that the following
 printed line should actually be part of the command:
diff --git a/docs/convert_images.sh b/docs/convert_images.sh
index 3bd22c01b..29539c6b5 100755
--- a/docs/convert_images.sh
+++ b/docs/convert_images.sh
@@ -1,4 +1,4 @@
-TEXDIR=.build/latex
+TEXDIR=_build/latex
 
 if test ! -z $BOOK; then
   for img in $TEXDIR/*.png;
diff --git a/docs/designdefense.rst b/docs/designdefense.rst
index e3a816269..1409403c4 100644
--- a/docs/designdefense.rst
+++ b/docs/designdefense.rst
@@ -15,7 +15,9 @@ Pyramid Has Zope Things In It, So It's Too Complex
 --------------------------------------------------
 
 On occasion, someone will feel compelled to post a mailing
-list message that reads something like this::
+list message that reads something like this:
+
+.. code-block:: text
 
    had a quick look at pyramid ... too complex to me and not really
    understand for which benefits.. I feel should consider whether it's time
@@ -29,7 +31,10 @@ Let's take this criticism point-by point.
 Too Complex
 +++++++++++
 
-- If you can understand this hello world program, you can use Pyramid::
+- If you can understand this hello world program, you can use Pyramid:
+
+.. code-block:: python
+   :linenos:
 
    from paste.httpserver import serve
    from pyramid.configuration import Configurator
@@ -570,10 +575,10 @@ called *declarations*.  For an example:
    :linenos:
 
    <route
-      view=".views.my_view"
-      path="/"
-      name="root"
-      />
+     view=".views.my_view"
+     path="/"
+     name="root"
+    />
 
 This declaration associates a :term:`view` with a route pattern. 
 
@@ -940,7 +945,9 @@ provide some frame of reference for how various components in the
 common web framework might hang together.  But in the opinion of the
 author, "MVC" doesn't match the web very well in general. Quoting from
 the `Model-View-Controller Wikipedia entry
-<http://en.wikipedia.org/wiki/Model–view–controller>`_::
+<http://en.wikipedia.org/wiki/Model–view–controller>`_:
+
+.. code-block:: text
 
   Though MVC comes in different flavors, control flow is generally as
   follows:
@@ -1232,6 +1239,7 @@ it:
 The contents of ``app.py``:
 
 .. code-block:: python
+    :linenos:
 
     from config import decorator
     from config import L
@@ -1248,6 +1256,7 @@ The contents of ``app.py``:
 The contents of ``app2.py``:
 
 .. code-block:: python
+    :linenos:
 
     import app
 
@@ -1258,6 +1267,7 @@ The contents of ``app2.py``:
 The contents of ``config.py``:
 
 .. code-block:: python
+  :linenos:
 
     L = []
 
@@ -1273,7 +1283,7 @@ function ``bar`` in ``app2.py``.  Since each time the decorator is
 used, the list ``L`` in ``config.py`` is appended to, we'd expect a
 list with two elements to be printed, right?  Sadly, no:
 
-.. code-block:: bash
+.. code-block:: text
 
     [chrism@thinko]$ python app.py 
     [<function foo at 0x7f4ea41ab1b8>,
@@ -1303,6 +1313,7 @@ Let's see what happens when we use the same pattern with the
 Replace the contents of ``app.py`` above with this:
 
 .. code-block:: python
+    :linenos:
 
     from config import gh
 
@@ -1317,6 +1328,7 @@ Replace the contents of ``app.py`` above with this:
 Replace the contents of ``app2.py`` above with this:
 
 .. code-block:: python
+    :linenos:
 
     import app
 
@@ -1327,6 +1339,7 @@ Replace the contents of ``app2.py`` above with this:
 Replace the contents of ``config.py`` above with this:
 
 .. code-block:: python
+    :linenos:
 
     from groundhog import Groundhog
     gh = Groundhog('myapp', 'seekrit')
@@ -1418,6 +1431,7 @@ problem.  They allow you to disuse decorator based configuration
 entirely.  Instead of requiring you to do the following:
 
 .. code-block:: python
+    :linenos:
 
     gh = Groundhog('myapp', 'seekrit')
 
@@ -1432,6 +1446,7 @@ They allow you to disuse the decorator syntax and go
 almost-all-imperative:
 
 .. code-block:: python
+    :linenos:
 
     def foo():
         return 'foo'
@@ -1473,6 +1488,7 @@ Consider the following simple `Groundhog
 <http://bfg.repoze.org/videos#groundhog1>`_ application:
 
 .. code-block:: python
+    :linenos:
 
     from groundhog import Groundhog
     app = Groundhog('myapp', 'seekrit')
@@ -1497,6 +1513,7 @@ If you run this application and visit the URL ``/admin``, you will see
 rearrange the order of the function definitions in the file?
 
 .. code-block:: python
+    :linenos:
 
     from groundhog import Groundhog
     app = Groundhog('myapp', 'seekrit')
@@ -1566,6 +1583,7 @@ use the ``import`` statement to get a handle to an object which *is
 not logically global*:
 
 .. code-block:: python
+    :linenos:
 
     from flask import request
 
@@ -1596,6 +1614,7 @@ of a function.  For example, we'd never try to import ``i`` from the
 code below:
 
 .. code-block::  python
+   :linenos:
 
    def afunc():
        for i in range(10):
@@ -1678,6 +1697,7 @@ where comments take into account what we've discussed in the
 :ref:`microframeworks_smaller_hello_world` section.
 
 .. code-block:: python
+   :linenos:
 
    from webob import Response                 # explicit response objects, no TL
    from paste.httpserver import serve         # explicitly WSGI
diff --git a/docs/index.rst b/docs/index.rst
index 72c21bbc8..073a562ca 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -1,7 +1,7 @@
 .. _index:
 
 =================================================
-The pyramid Web Application Development Framework
+The Pyramid Web Application Development Framework
 =================================================
 
 :app:`Pyramid` is a small, fast, down-to-earth Python web application
@@ -73,9 +73,9 @@ applications to various platforms.
 .. toctree::
    :maxdepth: 2
 
-   tutorials/bfg/index.rst
    tutorials/wiki/index.rst
    tutorials/wiki2/index.rst
+   tutorials/bfg/index.rst
    tutorials/cmf/index.rst
    tutorials/gae/index.rst
    tutorials/modwsgi/index.rst
@@ -117,7 +117,9 @@ Sample Applications
 application based on Rocky Burt's `ClueBin
 <http://pypi.python.org/pypi/ClueBin/0.2.3>`_.  It demonstrates form
 processing, security, and the use of :term:`ZODB` within a :app:`Pyramid`
-application.  Check this application out via::
+application.  Check this application out via:
+
+.. code-block:: text
 
   git clone git://github.com/Pylons/cluegun.git
 
@@ -125,7 +127,9 @@ application.  Check this application out via::
 file rendering application.  It is willing to render structured text
 documents, HTML documents, and images from a filesystem directory.  An
 earlier version of this application runs the `repoze.org
-<http://repoze.org>`_ website.  Check this application out via::
+<http://repoze.org>`_ website.  Check this application out via:
+
+.. code-block:: text
 
   git clone git://github.com/Pylons/virginia.git
 
@@ -134,7 +138,9 @@ competition" application by Carlos de la Guardia.  It demonstrates a hybrid
 of :term:`URL dispatch` and :term:`traversal` and integration with
 `SQLAlchemy <http://www.sqlalchemy.org/>`_, :term:`repoze.who`, and
 `Deliverance <http://www.deliveranceproject.org/>`_.  Check this application
-out of version control via::
+out of version control via:
+
+.. code-block:: text
 
   git clone git://github.com/Pylons/shootout.git
 
@@ -151,7 +157,9 @@ Older Sample Applications (repoze.bfg)
 runs the `bfg.repoze.org <http://bfg.repoze.org>`_ website.  It
 demonstrates integration with Trac, and includes several
 mini-applications such as a pastebin and tutorial engine.  Check a
-buildout for this application out of Subversion via::
+buildout for this application out of Subversion via:
+
+.. code-block:: text
 
   svn co http://svn.repoze.org/buildouts/bfgsite/ bfgsite_buildout
 
@@ -179,7 +187,9 @@ IRC channel <irc://irc.freenode.net/#pylons>`_.
 
 Browse and check out tagged and trunk versions of :app:`Pyramid` via
 the `Pyramid GitHub repository <http://github.com/Pylons/pyramid/>`_.
-To check out the trunk via ``git``, use this command::
+To check out the trunk via ``git``, use this command:
+
+.. code-block:: text
 
   git clone git@github.com:Pylons/pyramid.git
 
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)
 
diff --git a/docs/tutorials/cmf/index.rst b/docs/tutorials/cmf/index.rst
index 94c73af8e..26aa336a9 100644
--- a/docs/tutorials/cmf/index.rst
+++ b/docs/tutorials/cmf/index.rst
@@ -7,13 +7,12 @@ The Zope `Content Management Framework
 websites.  It's reasonably easy to convert a modern Zope/CMF
 application to :app:`Pyramid`.
 
-The main difference between CMF and :app:`Pyramid` is that
-:app:`Pyramid` does not advertise itself as a system into which you
-can plug arbitrary "packages" that extend a system-supplied management
-user interface.  You *could* build a CMF-like layer on top of
-:app:`Pyramid` (as CMF is built on Zope) but none currently exists.
-For those sorts of high-extensibility, highly-regularized-UI systems,
-CMF is still the better choice.
+The main difference between CMF and :app:`Pyramid` is that :app:`Pyramid`
+does not advertise itself as a system into which you can plug arbitrary
+"packages" that extend a system-supplied management user interface.  You
+*could* build a CMF-like layer on top of :app:`Pyramid` but none currently
+exists.  For those sorts of high-extensibility, highly-regularized-UI
+systems, CMF is still the better choice.
 
 :app:`Pyramid` (and other more lightweight systems) is often a
 better choice when you're building the a user interface from scratch,