Rendering cleanups.

20 files changed, 170 insertions, 150 deletions

diff --git a/docs/conf.py b/docs/conf.py
index e281653ff..3fb2767ea 100644
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -76,7 +76,7 @@ today_fmt = '%B %d, %Y'
 
 # If true, the current module name will be prepended to all description
 # unit titles (such as .. function::).
-#add_module_names = True
+add_module_names = False
 
 # If true, sectionauthor and moduleauthor directives will be shown in the
 # output. They are ignored by default.
diff --git a/docs/conventions.rst b/docs/conventions.rst
index 23c0017b6..082037782 100644
--- a/docs/conventions.rst
+++ b/docs/conventions.rst
@@ -1,8 +1,6 @@
 Typographical Conventions
 =========================
 
-The following typographical conventions are used within this guide.
-
 Literals, filenames and function arguments are presented using the
 following style:
 
@@ -18,31 +16,31 @@ related to a topic or concept are presented in the following style:
 Notes, which represent additional information related to a topic or
 concept are presented in the following style:
 
-.. note::
+  .. note::
 
-   This is a note.
+     This is a note.
 
-We present Python class names using the following style:
+We present Python method names using the following style:
 
-  :class:`Python.class.name`
+  :meth:`Python.method_name`
 
-We present Python method names using the following style:
+We present Python class names, module names, attributes and global
+variables using the following style:
 
-  :meth:`Python.method_name`.
+  :class:`Python.class.name`
 
-We present Python module names using the following style:
+References to glossary terms are presented using the following style:
 
-  :mod:`Python.module.name`.
+  :term:`Repoze`
 
-We present Python attributes and global variables using the following
-style:
+URLs are presented using the following style:
 
-  :data:`Python.attribute`.
+  `Repoze <http://repoze.org>`_
 
-References ot glossary terms and other document sections are presented
-using the following style:
+References to sections and chapters are presented using the following
+style:
 
-  :term:`Repoze`.
+  :ref:`traversal_chapter`
 
 Python code blocks are presented in the following style:
 
diff --git a/docs/copyright.rst b/docs/copyright.rst
index 188d005a5..60c5f4793 100644
--- a/docs/copyright.rst
+++ b/docs/copyright.rst
@@ -8,20 +8,20 @@ by Chris McDonough
 Copyright ©2008-2010, Agendaless Consulting.
 
 All rights reserved.  This material may be copied or distributed only
-subject to the terms and conditions set forth in the Creative Commons
+subject to the terms and conditions set forth in the `Creative Commons
 Attribution-Noncommercial-No Derivative Works 3.0 United States
-License as described by
-http://creativecommons.org/licenses/by-nc-nd/3.0/us/ .  You must give
-the original author credit.  You may not use this work for commercial
-purposes.  You may not alter, transform, or build upon this work. 
+License <http://creativecommons.org/licenses/by-nc-nd/3.0/us/>`_.  You
+must give the original author credit.  You may not use this work for
+commercial purposes.  You may not alter, transform, or build upon this
+work.
 
 .. note::
 
-   While the :mod:`repoze.bfg` *documentation* is offered under the
-   Creative Commons Attribution-Nonconmmercial-No Derivate Works 3.0
+   While the :mod:`repoze.bfg` documentation is offered under the
+   Creative Commons Attribution-Nonconmmercial-No Derivative Works 3.0
    United States License, the :mod:`repoze.bfg` *software* is offered
-   under the less restrictive (BSD-like) license described at
-   http://repoze.org/license.html .
+   under a `less restrictive (BSD-like) license
+   <http://repoze.org/license.html>`_ .
 
 **Trademarks**
 
@@ -43,7 +43,7 @@ with respect to the use of the information contained herein.
 **Contacting The Publisher**
 
 Please send documentation licensing inquiries and other business
-communications to ``webmaster@agendaless.com``.  Please send software
-and other technical queries to the ``repoze-dev`` mailing list
-described at http://lists.repoze.org/listinfo/repoze-dev .
-
+communications to `Agendaless Consulting
+<mailto:webmaster@agendaless.com>`_.  Please send software and other
+technical queries to the `repoze-dev maillist
+<http://lists.repoze.org/listinfo/repoze-dev>`_.
diff --git a/docs/glossary.rst b/docs/glossary.rst
index f9cd79929..a0d999c84 100644
--- a/docs/glossary.rst
+++ b/docs/glossary.rst
@@ -606,3 +606,10 @@ Glossary
       the `threading.local documentation
       <http://docs.python.org/library/threading.html#threading.local>`
       for more information.
+
+   Multidict
+     An ordered dictionary that can have multiple values for each
+     key. Adds the methods ``getall``, ``getone``, ``mixed``, and
+     ``add`` to the normal dictionary interface.  See
+     http://pythonpaste.org/webob/class-webob.multidict.MultiDict.html
+
diff --git a/docs/narr/MyProject/myproject/templates/mytemplate.pt b/docs/narr/MyProject/myproject/templates/mytemplate.pt
index b94cb7098..72e4fec9d 100644
--- a/docs/narr/MyProject/myproject/templates/mytemplate.pt
+++ b/docs/narr/MyProject/myproject/templates/mytemplate.pt
@@ -1,4 +1,5 @@
-<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" 
+          "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
 <html xmlns="http://www.w3.org/1999/xhtml"
       xmlns:tal="http://xml.zope.org/namespaces/tal">
 <head>
diff --git a/docs/narr/configuration.rst b/docs/narr/configuration.rst
index 73027e4c2..738295842 100644
--- a/docs/narr/configuration.rst
+++ b/docs/narr/configuration.rst
@@ -766,9 +766,9 @@ configuration` it creates.
 
 Since the relative ordering of calls to
 :meth:`repoze.bfg.configuration.Configurator.add_view` doesn't matter
-(see the sidebar above entitled *View Dispatch and Ordering*), the
-relative order of ``<view>`` tags in ZCML doesn't matter either.  The
-following ZCML orderings are completely equivalent:
+(see the sidebar entitled *View Dispatch and Ordering*), the relative
+order of ``<view>`` tags in ZCML doesn't matter either.  The following
+ZCML orderings are completely equivalent:
 
 .. topic:: Hello Before Goodbye
 
diff --git a/docs/narr/install.rst b/docs/narr/install.rst
index e4eb284f9..4fa0ef1d8 100644
--- a/docs/narr/install.rst
+++ b/docs/narr/install.rst
@@ -84,7 +84,6 @@ same system, to install a Python 2.5 interpreter from *source*, use
 the following commands:
 
 .. code-block:: text
-   :linenos:
 
    [chrism@vitaminf ~]$ cd ~
    [chrism@vitaminf ~]$ mkdir tmp
@@ -128,7 +127,6 @@ setuptools`` within the Python interpreter you'd like to run
 :mod:`repoze.bfg` under:
 
 .. code-block:: text
-   :linenos:
 
    [chrism@vitaminf bfg]$ python
    Python 2.4.5 (#1, Aug 29 2008, 12:27:37) 
@@ -195,7 +193,6 @@ can actually create a virtual environment.  To do so, invoke the
 following:
 
 .. code-block:: text
-   :linenos:
 
    $ virtualenv --no-site-packages bfgenv
    New python executable in bfgenv/bin/python
@@ -225,7 +222,6 @@ After you've got your ``bfgenv`` virtualenv installed, you may install
 virtualenv (``bfgenv``) directory:
 
 .. code-block:: text
-   :linenos:
 
    $ bin/easy_install -i http://dist.repoze.org/bfg/1.1/simple repoze.bfg
 
diff --git a/docs/narr/introduction.rst b/docs/narr/introduction.rst
index 09b690a12..6b5494d76 100644
--- a/docs/narr/introduction.rst
+++ b/docs/narr/introduction.rst
@@ -117,19 +117,18 @@ Differences from Other Web Frameworks
 -------------------------------------
 
 Like :term:`Zope`, the :mod:`repoze.bfg` framework imposes more
-`control inversion <http://plope.com/control_inversion>`_ upon
-application developers than other Python frameworks such as
-:term:`Pylons`.  For example :mod:`repoze.bfg` allows you to
-explicitly resolve a URL to a :term:`context` object before invoking a
-:term:`view`.  Pylons and other Python "MVC" frameworks have no such
-intermediate step; they resolve a URL directly to a "controller".
-Another example: using the :mod:`repoze.bfg` security subsystem
-assumes that you're willing to attach an :term:`ACL` to a
-:term:`context` object; the ACL is checked by the framework itself
-instead of by user code, and access is permitted or denied by the
-framework itself rather than by user code.  Such a task would
-typically be performed by user-space decorators in other Python web
-frameworks.
+*control inversion* upon application developers than other Python
+frameworks such as :term:`Pylons`.  For example :mod:`repoze.bfg`
+allows you to explicitly resolve a URL to a :term:`context` object
+before invoking a :term:`view`.  Pylons and other Python "MVC"
+frameworks have no such intermediate step; they resolve a URL directly
+to a "controller".  Another example: using the :mod:`repoze.bfg`
+security subsystem assumes that you're willing to attach an
+:term:`ACL` to a :term:`context` object; the ACL is checked by the
+framework itself instead of by user code, and access is permitted or
+denied by the framework itself rather than by user code.  Such a task
+would typically be performed by user-space decorators in other Python
+web frameworks.
 
 Like Zope, but unlike :term:`Pylons` applications or most
 :term:`Django` applications, when you build a :mod:`repoze.bfg`
diff --git a/docs/narr/project.rst b/docs/narr/project.rst
index fd0ab27a1..2fe5489e2 100644
--- a/docs/narr/project.rst
+++ b/docs/narr/project.rst
@@ -29,8 +29,7 @@ To start a :mod:`repoze.bfg` :term:`project`, use the ``paster
 create`` facility using the interpreter from the virtualenv
 (``bfgenv``) directory you created in :ref:`installing_chapter`.
 
-.. code-block:: bash
-   :linenos:
+.. code-block:: text
 
    $ bin/paster create -t bfg_starter
 
@@ -39,8 +38,7 @@ project.  You should use a string without spaces and with only letters
 in it.  Here's sample output from a run of ``paster create`` for a
 project we name ``MyProject``:
 
-.. code-block:: bash
-   :linenos:
+.. code-block:: text
 
    $ bin/paster create -t bfg_starter
    Selected and implied templates:
@@ -128,15 +126,13 @@ the project directory.  The file named ``setup.py`` will be in the
 root of the paster-generated project directory.  The ``python`` you're
 invoking should be the one from your virtualenv.
 
-.. code-block:: bash
-   :linenos:
+.. code-block:: text
 
    $ ../bin/python setup.py develop
 
 Elided output from a run of this command is shown below:
 
-.. code-block:: bash
-   :linenos:
+.. code-block:: text
 
    $ ../bin/python setup.py develop
    ...
@@ -152,15 +148,13 @@ Running The Tests For Your Application
 To run unit tests for your application, you should invoke them like
 so:
 
-.. code-block:: bash
-   :linenos:
+.. code-block:: text
 
    $ ../bin/python setup.py test -q
 
 Here's sample output from a test run:
 
-.. code-block:: bash
-   :linenos:
+.. code-block:: text
 
    $ python setup.py test -q
    running test
@@ -209,21 +203,18 @@ section within the ``.ini`` file.  For example, if your application
 If so, you can use the following command to invoke a debug shell using
 the name ``main`` as a section name:
 
-.. code-block::  bash
-   :linenos:
+.. code-block::  text
 
-    [chrism@vitaminf bfgshellenv]$ ../bin/paster --plugin=repoze.bfg bfgshell MyProject.ini main
+   [chrism@vitaminf bfgshellenv]$ ../bin/paster --plugin=repoze.bfg bfgshell MyProject.ini main
 
-    Python 2.4.5 (#1, Aug 29 2008, 12:27:37) 
-    [GCC 4.0.1 (Apple Inc. build 5465)] on darwin
-    Type "help" for more information. "root" is the BFG app root object.
-    >>> root
-    <foo.models.MyModel object at 0x445270>
+   Python 2.4.5 (#1, Aug 29 2008, 12:27:37) 
+   [GCC 4.0.1 (Apple Inc. build 5465)] on darwin
+   Type "help" for more information. "root" is the BFG app root object.
+   >>> root
+   <foo.models.MyModel object at 0x445270>
 
 .. note:: You *might* get away without passing
-          ``--plugin=repoze.bfg`` to the bfgshell command; the
-          ``--plugin=repoze.bfg`` option is only required under
-          conditions that are not yet well-understood.
+          ``--plugin=repoze.bfg`` to the bfgshell command.
 
 If you have `IPython <http://en.wikipedia.org/wiki/IPython>`_
 installed in the interpreter you use to invoke the ``paster`` command,
@@ -233,10 +224,9 @@ happen, even if you have IPython installed, you can pass the
 ``--disable-ipython`` flag to the ``bfgshell`` command to use a
 standard Python interpreter shell unconditionally.
 
-.. code-block::  bash
-   :linenos:
+.. code-block::  text
 
-    [chrism@vitaminf bfgshellenv]$ ../bin/paster --plugin=repoze.bfg bfgshell MyProject.ini main
+   [chrism@vitaminf bfgshellenv]$ ../bin/paster --plugin=repoze.bfg bfgshell MyProject.ini main
 
 Press "Ctrl-D" to exit the interactive shell.
 
@@ -263,10 +253,9 @@ following ``.ini`` file content:
 
 The command you use to invoke the interactive shell should be:
 
-.. code-block::  bash
-   :linenos:
+.. code-block::  text
 
-    [chrism@vitaminf bfgshellenv]$ ../bin/paster --plugin=repoze.bfg bfgshell MyProject.ini myapp
+   [chrism@vitaminf bfgshellenv]$ ../bin/paster --plugin=repoze.bfg bfgshell MyProject.ini myapp
 
 If you use ``main`` as the section name argument instead of ``myapp``
 against the above ``.ini`` file, an error will likely occur.  Use the
@@ -290,15 +279,13 @@ the generated ``MyProject.ini`` configuration file:
    webserver, as exception and debugging output will be sent to the
    console.
 
-.. code-block:: bash
-   :linenos:
+.. code-block:: text
 
    $ ../bin/paster serve MyProject.ini
 
 Here's sample output from a run:
 
-.. code-block:: bash
-   :linenos:
+.. code-block:: text
 
    $ paster serve MyProject.ini
    Starting server in PID 16601.
diff --git a/docs/narr/scanning.rst b/docs/narr/scanning.rst
index a7f47efd4..2226b557f 100644
--- a/docs/narr/scanning.rst
+++ b/docs/narr/scanning.rst
@@ -76,7 +76,6 @@ effectively:
 
 .. ignore-next-block
 .. code-block:: python
-   :linenos:
 
    config.add_view(hello, name='hello', request_method='GET')
 
diff --git a/docs/narr/startup.rst b/docs/narr/startup.rst
index f4904f0bf..4e806ec17 100644
--- a/docs/narr/startup.rst
+++ b/docs/narr/startup.rst
@@ -6,7 +6,7 @@ Startup
 When you cause :mod:`repoze.bfg` to start up in a console window,
 you'll see something much like this show up on the console:
 
-.. code-block:: bash
+.. code-block:: text
 
   $ paster serve myproject/MyProject.ini
   Starting server in PID 16601.
diff --git a/docs/narr/traversal.rst b/docs/narr/traversal.rst
index 1683b3cef..3476622d5 100644
--- a/docs/narr/traversal.rst
+++ b/docs/narr/traversal.rst
@@ -82,8 +82,7 @@ This inexperienced user's attempt to execute ``cat`` against the file
 named ``/fiz/buz/myfile`` might be to issue the following set of UNIX
 commands:
 
-.. code-block::  bash
-   :linenos:
+.. code-block::  text
 
    cd /
    cd fiz
@@ -94,8 +93,7 @@ The user now know he has found a *file*, because the ``cd`` command
 issues an error when he executed ``cd myfile``.  Now he knows that he
 can run the ``cat`` command:
 
-.. code-block::  bash
-   :linenos:
+.. code-block::  text
 
    cat myfile
 
diff --git a/docs/narr/urldispatch.rst b/docs/narr/urldispatch.rst
index 443ffbfaa..2d74bfbca 100644
--- a/docs/narr/urldispatch.rst
+++ b/docs/narr/urldispatch.rst
@@ -62,14 +62,9 @@ registry`.  Here's an example:
 
 .. ignore-next-block
 .. code-block:: python
-   :linenos:
 
    config.add_route('myroute', '/prefix/:one/:two')
 
-See the :meth:`repoze.bfg.configuration.Configurator.add_route` API
-documentation for more information and options for adding a route
-imperatively.
-
 Configuring a Route via ZCML
 ----------------------------
 
@@ -109,13 +104,17 @@ The path pattern syntax is simple.
 
 The path may start with a slash character.  If the path does not start
 with a slash character, an implicit slash will be prepended to it at
-matching time.  For example, the following paths are equivalent::
+matching time.  For example, the following paths are equivalent:
+
+.. code-block:: text
 
-    :foo/bar/baz
+   :foo/bar/baz
 
-and::
+and:
 
-     /:foo/bar/baz
+.. code-block:: text
+
+   /:foo/bar/baz
 
 A path segment (an individual item between ``/`` characters in the
 path) may either be a literal string (e.g. ``foo``) *or* it may
@@ -123,17 +122,23 @@ segment replacement marker (e.g. ``:foo``).  A segment replacement
 marker is in the format ``:name``, where this means "accept any
 characters up to the next slash and use this as the ``name`` matchdict
 value."  For example, the following pattern defines one literal
-segment ("foo") and two dynamic segments ("baz", and "bar")::
+segment ("foo") and two dynamic segments ("baz", and "bar"):
+
+.. code-block:: text
 
-    foo/:baz/:bar
+   foo/:baz/:bar
 
 The above pattern will match these URLs, generating the following
-matchdicts::
+matchdicts:
+
+.. code-block:: text
 
    foo/1/2        -> {'baz':u'1', 'bar':u'2'}
    foo/abc/def    -> {'baz':u'abc', 'bar':u'2'}
 
-It will not match the following patterns however::
+It will not match the following patterns however:
+
+.. code-block:: text
 
    foo/1/2/        -> No match (trailing slash)
    bar/abc/def     -> First segment literal mismatch
@@ -141,28 +146,38 @@ It will not match the following patterns however::
 Note that values representing path segments matched with a
 ``:segment`` match will be url-unquoted and decoded from UTF-8 into
 Unicode within the matchdict.  So for instance, the following
-pattern::
+pattern:
+
+.. code-block:: text
+
+   foo/:bar
 
-    foo/:bar
+When matching the following URL:
 
-When matching the following URL::
+.. code-block:: text
 
-    foo/La%20Pe%C3%B1a
+   foo/La%20Pe%C3%B1a
 
 The matchdict will look like so (the value is URL-decoded / UTF-8
-decoded)::
+decoded):
 
-  {'bar':u'La Pe\xf1a'}
+.. code-block:: text
+
+   {'bar':u'La Pe\xf1a'}
 
 If the pattern has a ``*`` in it, the name which follows it is
 considered a "remainder match".  A remainder match *must* come at the
 end of the path pattern.  Unlike segment replacement markers, it does
-not need to be preceded by a slash.  For example::
+not need to be preceded by a slash.  For example:
+
+.. code-block:: text
 
-    foo/:baz/:bar*traverse
+   foo/:baz/:bar*traverse
 
 The above pattern will match these URLs, generating the following
-matchdicts::
+matchdicts:
+
+.. code-block:: text
 
    foo/1/2/               -> {'baz':1, 'bar':2, 'traverse':()}
    foo/abc/def/a/b/c      -> {'baz':abc, 'bar':2, 'traverse':('a', 'b', 'c')}
@@ -171,17 +186,23 @@ Note that when a ``*stararg`` remainder match is matched, the value
 put into the matchdict is turned into a tuple of path segments
 representing the remainder of the path.  These path segments are
 url-unquoted and decoded from UTF-8 into Unicode.  For example, for
-the following pattern::
+the following pattern:
+
+.. code-block:: text
+
+   foo/*traverse
 
-    foo/*traverse
+When matching the following path:
 
-When matching the following path::
+.. code-block:: text
 
-    /foo/La%20Pe%C3%B1a/a/b/c
+   /foo/La%20Pe%C3%B1a/a/b/c
 
-Will generate the following matchdict::
+Will generate the following matchdict:
 
-  {'traverse':(u'La Pe\xf1a', u'a', u'b', u'c')}
+.. code-block:: text
+
+   {'traverse':(u'La Pe\xf1a', u'a', u'b', u'c')}
 
 ``<route>`` Statement Examples
 ------------------------------
@@ -283,8 +304,7 @@ might add to your ``configure.zcml``:
 The above configuration will allow :mod:`repoze.bfg` to service URLs
 in these forms:
 
-.. code-block:: bash
-   :linenos:
+.. code-block:: text
 
    /ideas/<ideaname>
    /users/<username>
@@ -436,6 +456,7 @@ this.
 
 .. ignore-next-block
 .. code-block:: python
+   :linenos:
 
    from repoze.bfg.url import route_url
    url = route_url('foo', request, a='1', b='2', c='3')
@@ -529,6 +550,7 @@ be removed after each request.  Put the following in the
 
 .. ignore-next-block
 .. code-block:: python
+   :linenos:
 
     from mypackage.sql import DBSession
 
diff --git a/docs/narr/urlmapping.rst b/docs/narr/urlmapping.rst
index 2eeaa0646..e5933ae1e 100644
--- a/docs/narr/urlmapping.rst
+++ b/docs/narr/urlmapping.rst
@@ -38,10 +38,12 @@ item "below" ``members`` in the URL represents a member in the system.
 You just match everything "below" ``members`` to a particular view.
 
 For example, you might configure a :term:`route` to match against the
-following URL patterns::
+following URL patterns:
 
-  archives/:year/:month/:day
-  members/:membername
+.. code-block:: text
+
+   archives/:year/:month/:day
+   members/:membername
 
 In this configuration, there are exactly two types of URLs that will
 match views in your application: ones that start with ``/archives``
@@ -50,10 +52,12 @@ day.  And ones that start with ``/members`` which are followed by a
 path segment containing a member's name.  This is very simple.
 
 :term:`URL dispatch` is not very good, however, at inferring the
-difference between sets of URLs such as::
+difference between sets of URLs such as:
+
+.. code-block:: text
 
-       http://example.com/members/Chris/document
-       http://example.com/members/Chris/stuff/page
+   http://example.com/members/Chris/document
+   http://example.com/members/Chris/stuff/page
 
 ...wherein you'd like the ``document`` in the first URL to represent a
 PDF document, and ``/stuff/page`` in the second to represent an
diff --git a/docs/narr/views.rst b/docs/narr/views.rst
index 5f9eb9140..c9929538f 100644
--- a/docs/narr/views.rst
+++ b/docs/narr/views.rst
@@ -125,7 +125,10 @@ request
 The following types work as views in this style:
 
 #. Functions that accept two arguments: ``context``, and ``request``,
-   e.g.::
+   e.g.:
+
+   .. code-block:: python
+      :linenos:
 
       from webob import Response
 
@@ -133,7 +136,10 @@ The following types work as views in this style:
           return Response('OK')
 
 #. New-style and old-style classes that have an ``__init__`` method
-   that accepts ``context, request``, e.g.::
+   that accepts ``context, request``, e.g.:
+
+   .. code-block:: python
+      :linenos:
 
       from webob import Response
 
@@ -142,7 +148,10 @@ The following types work as views in this style:
               return Response('OK')
 
 #. Arbitrary callables that have a ``__call__`` method that accepts
-   ``context, request``, e.g.::
+   ``context, request``, e.g.:
+
+   .. code-block:: python
+      :linenos:
 
       from webob import Response
 
@@ -358,7 +367,6 @@ the following:
   your application's ``configure.zcml``:
 
   .. code-block:: xml
-     :linenos:
 
       <scan package="."/>
 
@@ -366,7 +374,6 @@ the following:
   :meth:`repoze.bfg.configuration.Configurator.scan` method:
 
   .. code-block:: python
-     :linenos:
 
       config.scan()
 
@@ -436,7 +443,6 @@ Or replaces the need to add this imperative configuration stanza:
 
 .. ignore-next-block
 .. code-block:: python
-   :linenos:
 
    config.add_view(name='my_view', request_method='POST', for_=MyModel,
                    permission='read')
@@ -1461,6 +1467,7 @@ a browser client, and its ``action`` points at some :mod:`repoze.bfg`
 view code:
 
 .. code-block:: xml
+   :linenos:
 
    <html xmlns="http://www.w3.org/1999/xhtml">
      <head>
@@ -1483,6 +1490,7 @@ expect that the values returned by ``request.params`` will be of type
 accept a form post from the above form:
 
 .. code-block:: python
+   :linenos:
 
    def myview(request):
        firstname = request.params['firstname']
@@ -1493,6 +1501,7 @@ decode already-decoded (``unicode``) values obtained from
 ``request.params``:
 
 .. code-block:: python
+   :linenos:
 
    def myview(request):
        # the .decode('utf-8') will break below if there are any high-order
diff --git a/docs/narr/webob.rst b/docs/narr/webob.rst
index 8dbdef6f2..c4bd568c7 100644
--- a/docs/narr/webob.rst
+++ b/docs/narr/webob.rst
@@ -53,16 +53,16 @@ object:
     The request method, e.g., ``'GET'``, ``'POST'``
 
 ``req.GET``:
-    A `dictionary-like object`_ with all the variables in the query
+    A :term:`multidict` with all the variables in the query
     string.
 
 ``req.POST``:
-    A `dictionary-like object`_ with all the variables in the request
+    A :term:`multidict` with all the variables in the request
     body.  This only has variables if the request was a ``POST`` and
     it is a form submission.  
 
 ``req.params``:
-    A `dictionary-like object`_ with a combination of everything in
+    A :term:`multidict` with a combination of everything in
     ``req.GET`` and ``req.POST``.
 
 ``req.body``:
@@ -85,8 +85,6 @@ object:
     <http://routes.groovie.org/>`_ and `Selector
     <http://lukearno.com/projects/selector/>`_.
 
-.. _`dictionary-like object`: #multidict
-
 Also, for standard HTTP request headers there are usually attributes,
 for instance: ``req.accept_language``, ``req.content_length``,
 ``req.user_agent``, as an example.  These properties expose the
@@ -171,8 +169,8 @@ WSGI):
 
 ``response.headerlist``:
     A list of all the headers, like ``[('Content-Type',
-    'text/html')]``.  There's a case-insensitive `dictionary-like
-    object`_ in ``response.headers`` that also allows you to access
+    'text/html')]``.  There's a case-insensitive :term:`multidict`
+    in ``response.headers`` that also allows you to access
     these same headers.
 
 ``response.app_iter``:
diff --git a/docs/thanks.rst b/docs/thanks.rst
index 6270e8a36..6f2b07ceb 100644
--- a/docs/thanks.rst
+++ b/docs/thanks.rst
@@ -6,10 +6,10 @@ This book is dedicated to my grandmother, Dorothy Phillips.
 Thanks to the following people for providing expertise, resources, and
 software.  Without the help of these folks, neither this book nor the
 software which it details would exist: Paul Everitt, Tres Seaver,
-Malthe Borch, Carlos de la Guardia, Simon Oram of Electrosoup, Ian
-Bicking of the Open Planning Project, Jim Fulton of Zope Corporation,
-Tom Moroz of the Open Society Institute, and Todd Koym of
-Environmental Health Sciences.
+Malthe Borch, Carlos de la Guardia, Georg Brandl, Simon Oram of
+Electrosoup, Ian Bicking of the Open Planning Project, Jim Fulton of
+Zope Corporation, Tom Moroz of the Open Society Institute, and Todd
+Koym of Environmental Health Sciences.
 
 Special thanks to Guido van Rossum and Tim Peters for Python.
 
diff --git a/docs/tutorials/bfgwiki/basiclayout.rst b/docs/tutorials/bfgwiki/basiclayout.rst
index 84f6e493e..a0fa2b924 100644
--- a/docs/tutorials/bfgwiki/basiclayout.rst
+++ b/docs/tutorials/bfgwiki/basiclayout.rst
@@ -109,7 +109,7 @@ function within the file named ``run.py``:
    dictionary passed to our ``app`` function.  This will be a URI
    (something like ``file:///path/to/Data.fs``).
 
-#. Line *14*. We create a "finder" object using the
+#. *Line 14*. We create a "finder" object using the
    :class:`repoze.zodbconn.finder.PersistentApplicationFinder` helper
    class, passing it the ZODB URI and the "appmaker" we've imported
    from ``models.py``.
@@ -117,18 +117,18 @@ function within the file named ``run.py``:
 #. *Lines 15 - 16*.  We create a :term:`root factory` which uses the
    finder to return a ZODB root object.
 
-#. Line *17*.  We construct a :term:`Configurator` with a :term:`root
+#. *Line 17*.  We construct a :term:`Configurator` with a :term:`root
    factory` and the settings keywords parsed by PasteDeploy.  The root
    factory is named ``get_root``.
 
-# *Lines 18-20*.  Begin configuration using the
+#. *Lines 18-20*.  Begin configuration using the
    :meth:`repoze.bfg.configuration.Configurator.begin` method, load
    the ``configure.zcml`` file from our package using the
    :meth:`repoze.bfg.configuration.Configurator.load_zcml` method, and
    end configuration using the
    :meth:`repoze.bfg.configuration.Configurator.end` method.
 
-# *Line 21*.  Use the
+#. *Line 21*.  Use the
    :meth:`repoze.bfg.configuration.Configurator.make_wsgi_app` method
    to return a :term:`WSGI` application.
 
diff --git a/docs/tutorials/bfgwiki/installation.rst b/docs/tutorials/bfgwiki/installation.rst
index df3eeee93..90bd57e31 100644
--- a/docs/tutorials/bfgwiki/installation.rst
+++ b/docs/tutorials/bfgwiki/installation.rst
@@ -117,7 +117,8 @@ Preparation, Windows
 
    .. code-block:: bat
 
-     c:\bigfntut> Scripts\easy_install -i http://dist.repoze.org/bfgsite/simple docutils repoze.tm repoze.zodbconn repoze.who nose coverage
+     c:\bigfntut> Scripts\easy_install -i http://dist.repoze.org/bfgsite/simple \
+              docutils repoze.tm repoze.zodbconn repoze.who nose coverage
 
 .. _making_a_project:
 
@@ -228,7 +229,8 @@ On Windows:
 
 .. code-block:: bat
 
-  c:\bigfntut\tutorial> ..\Scripts\nosetests --cover-package=tutorial --cover-erase --with-coverage
+  c:\bigfntut\tutorial> ..\Scripts\nosetests --cover-package=tutorial \
+       --cover-erase --with-coverage
 
 Looks like the code in the ``bfg_zodb`` template for ZODB projects is
 missing some test coverage, particularly in the file named
diff --git a/docs/zcml.rst b/docs/zcml.rst
index 78f4fc344..889008e85 100644
--- a/docs/zcml.rst
+++ b/docs/zcml.rst
@@ -309,7 +309,7 @@ Predicate Attributes
 ``route_name``
 
   *This attribute services an advanced feature that isn't often used
-  unless you want to perform traversal *after* a route has matched.*
+  unless you want to perform traversal after a route has matched.*
   This value must match the ``name`` of a ``<route>`` declaration (see
   :ref:`urldispatch_chapter`) that must match before this view will be
   called.  Note that the ``route`` configuration referred to by