Latex rendering.

Documentation licensing.

14 files changed, 1040 insertions, 1011 deletions

diff --git a/CHANGES.txt b/CHANGES.txt
index 5459a978c..a221ba8dc 100644
--- a/CHANGES.txt
+++ b/CHANGES.txt
@@ -1,6 +1,18 @@
 Next release
 ============
 
+Documentation Licensing
+-----------------------
+
+- The *documentation* (the result of ``make <html|latex|htmlhelp>``
+  within the ``docs`` directory) in this release is now offered under
+  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/ .  This is only
+  a licensing change for the documentation; the ``repoze.bfg``
+  software continues to be offered under the Repoze Public License
+  at http://repoze.org/license.html (BSD-like).
+
 Documentation
 -------------
 
@@ -14,6 +26,11 @@ Documentation
   This section contains detailed ZCML directive information, some of
   which was removed from various narrative chapters.
 
+- The LaTeX rendering of the documentation has been improved.
+
+- Added a "Fore-Matter" section with author, copyright, and licensing
+  information.
+
 1.2a8 (2009-12-24)
 ==================
 
diff --git a/LICENSE.txt b/LICENSE.txt
index af4b8ecc6..9040b45a9 100644
--- a/LICENSE.txt
+++ b/LICENSE.txt
@@ -1,4 +1,4 @@
-The majority of the code in bfg is supplied under this license:
+The majority of the code in repoze.bfg is supplied under this license:
 
   A copyright notice accompanies this license document that identifies
   the copyright holders.
@@ -43,57 +43,63 @@ Portions of the code in repoze.bfg are supplied under the ZPL (headers
 within individiual files indicate that these portions are licensed
 under the ZPL):
 
-Zope Public License (ZPL) Version 2.1
--------------------------------------
-
-A copyright notice accompanies this license document that
-identifies the copyright holders.
-
-This license has been certified as open source. It has also
-been designated as GPL compatible by the Free Software
-Foundation (FSF).
-
-Redistribution and use in source and binary forms, with or
-without modification, are permitted provided that the
-following conditions are met:
-
-1. Redistributions in source code must retain the
-   accompanying copyright notice, this list of conditions,
-   and the following disclaimer.
-
-2. Redistributions in binary form must reproduce the accompanying
-   copyright notice, this list of conditions, and the
-   following disclaimer in the documentation and/or other
-   materials provided with the distribution.
-
-3. Names of the copyright holders must not be used to
-   endorse or promote products derived from this software
-   without prior written permission from the copyright
-   holders.
-
-4. The right to distribute this software or to use it for
-   any purpose does not give you the right to use
-   Servicemarks (sm) or Trademarks (tm) of the copyright
-   holders. Use of them is covered by separate agreement
-   with the copyright holders.
-
-5. If any files are modified, you must cause the modified
-   files to carry prominent notices stating that you changed
-   the files and the date of any change.
-
-Disclaimer
-
-  THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS ``AS IS''
-  AND ANY EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT
-  NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY
-  AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.  IN
-  NO EVENT SHALL THE COPYRIGHT HOLDERS BE
-  LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
-  EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
-  LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
-  LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
-  HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
-  CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE
-  OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
-  SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH
-  DAMAGE.
+  Zope Public License (ZPL) Version 2.1
+  -------------------------------------
+
+  A copyright notice accompanies this license document that
+  identifies the copyright holders.
+
+  This license has been certified as open source. It has also
+  been designated as GPL compatible by the Free Software
+  Foundation (FSF).
+
+  Redistribution and use in source and binary forms, with or
+  without modification, are permitted provided that the
+  following conditions are met:
+
+  1. Redistributions in source code must retain the
+     accompanying copyright notice, this list of conditions,
+     and the following disclaimer.
+
+  2. Redistributions in binary form must reproduce the accompanying
+     copyright notice, this list of conditions, and the
+     following disclaimer in the documentation and/or other
+     materials provided with the distribution.
+
+  3. Names of the copyright holders must not be used to
+     endorse or promote products derived from this software
+     without prior written permission from the copyright
+     holders.
+
+  4. The right to distribute this software or to use it for
+     any purpose does not give you the right to use
+     Servicemarks (sm) or Trademarks (tm) of the copyright
+     holders. Use of them is covered by separate agreement
+     with the copyright holders.
+
+  5. If any files are modified, you must cause the modified
+     files to carry prominent notices stating that you changed
+     the files and the date of any change.
+
+  Disclaimer
+
+    THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS ``AS IS''
+    AND ANY EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT
+    NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY
+    AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.  IN
+    NO EVENT SHALL THE COPYRIGHT HOLDERS BE
+    LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
+    EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
+    LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
+    LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
+    HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
+    CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE
+    OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
+    SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH
+    DAMAGE.
+
+The documentation portion of repoze.bfg (the rendered contents of the
+"docs" directory of a software distribution or checkout) is supplied
+under 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/
diff --git a/docs/conf.py b/docs/conf.py
index 540c2305a..e281653ff 100644
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -44,7 +44,7 @@ source_suffix = '.rst'
 master_doc = 'index'
 
 # General substitutions.
-project = 'repoze.bfg'
+project = 'The repoze.bfg Web Application Framework'
 copyright = '2008-2010, Agendaless Consulting'
 
 # The default replacements for |version| and |release|, also used in various
@@ -96,7 +96,7 @@ html_style = 'repoze.css'
 
 # The name for this set of Sphinx documents.  If None, it defaults to
 # "<project> v<release> documentation".
-#html_title = None
+#html_title = 'The repoze.bfg Web Application Framework v%release%'
 
 # A shorter title for the navigation bar.  Default is the same as html_title.
 #html_short_title = None
@@ -151,8 +151,7 @@ html_last_updated_fmt = '%b %d, %Y'
 #html_file_suffix = ''
 
 # Output file base name for HTML help builder.
-htmlhelp_basename = 'repozebfgdoc'
-
+htmlhelp_basename = 'repozebfg'
 
 # Options for LaTeX output
 # ------------------------
@@ -166,7 +165,7 @@ latex_font_size = '10pt'
 # Grouping the document tree into LaTeX files. List of tuples
 # (source start file, target name, title, author, document class [howto/manual]).
 latex_documents = [
-  ('latexindex', 'repoze.bfg.tex', 'The repoze.bfg Web Framework',
+  ('latexindex', 'repozebfg.tex', 'The repoze.bfg Web Application Framework',
    'Chris McDonough', 'manual'),
     ]
 
diff --git a/docs/conventions.rst b/docs/conventions.rst
new file mode 100644
index 000000000..23c0017b6
--- /dev/null
+++ b/docs/conventions.rst
@@ -0,0 +1,63 @@
+Typographical Conventions
+=========================
+
+The following typographical conventions are used within this guide.
+
+Literals, filenames and function arguments are presented using the
+following style:
+
+  ``argument1``
+
+Warnings, which represent limitations and need-to-know information
+related to a topic or concept are presented in the following style:
+
+  .. warning::
+
+     This is a warning.
+
+Notes, which represent additional information related to a topic or
+concept are presented in the following style:
+
+.. note::
+
+   This is a note.
+
+We present Python class names using the following style:
+
+  :class:`Python.class.name`
+
+We present Python method names using the following style:
+
+  :meth:`Python.method_name`.
+
+We present Python module names using the following style:
+
+  :mod:`Python.module.name`.
+
+We present Python attributes and global variables using the following
+style:
+
+  :data:`Python.attribute`.
+
+References ot glossary terms and other document sections are presented
+using the following style:
+
+  :term:`Repoze`.
+
+Python code blocks are presented in the following style:
+
+  .. code-block:: python
+     :linenos:
+
+     def foo(abc):
+         pass
+
+Blocks of XML markup are presented in the following style:
+
+  .. code-block:: xml
+     :linenos:
+
+     <root>
+       <!-- ... more XML .. -->
+     </root>
+
diff --git a/docs/copyright.rst b/docs/copyright.rst
new file mode 100644
index 000000000..188d005a5
--- /dev/null
+++ b/docs/copyright.rst
@@ -0,0 +1,49 @@
+Copyright and Trademarks
+========================
+
+*The repoze.bfg Web Application Framework*
+
+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
+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. 
+
+.. note::
+
+   While the :mod:`repoze.bfg` *documentation* is offered under the
+   Creative Commons Attribution-Nonconmmercial-No Derivate 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 .
+
+**Trademarks**
+
+All terms mentioned in this book that are known to be trademarks or
+service marks have been appropriately capitalized.  However, use of a
+term in this book should not be regarded as affecting the validity of
+any trademark or service mark.
+
+**Warning and Disclaimer**
+
+Every effort has been made to make this book as complete and as
+accurate as possible, but no warranty or fitness is implied.  The
+information provided is on as "as-is" basis.  The author and the
+publisher shall have neither liability nor responsibility to any
+person or entity with respect to any loss or damages arising from the
+information contained in this book.  No patent liability is assumed
+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 .
+
diff --git a/docs/glossary.rst b/docs/glossary.rst
index b2a211113..f9cd79929 100644
--- a/docs/glossary.rst
+++ b/docs/glossary.rst
@@ -1,526 +1,608 @@
 .. _glossary:
 
-============================
 Glossary
-============================
+========
 
 .. glossary::
+   :sorted:
 
-  Request
-    A ``WebOb`` request object.  See :ref:`webob_chapter` for
-    information about request objects.
-  Response
-    An object that has three attributes: ``app_iter`` (representing an
-    iterable body), ``headerlist`` (representing the http headers sent
-    to the user agent), and ``status`` (representing the http status
-    string sent to the user agent).  This is the interface defined for
-    ``WebOb`` response objects.  See :ref:`webob_chapter` for
-    information about response objects.
-  Repoze
-    "Repoze" is essentially a "brand" of software developed by
-    `Agendaless Consulting <http://agendaless.com>`_ and a set of
-    contributors.  The term has no special intrinsic meaning.  The
-    project's `website <http://repoze.org>`_ has more information.
-    The software developed "under the brand" is available in a
-    `Subversion repository <http://svn.repoze.org>`_.
-  Setuptools
-    `Setuptools <http://peak.telecommunity.com/DevCenter/setuptools>`_
-    builds on Python's ``distutils`` to provide easier building,
-    distribution, and installation of libraries and applications.
-  pkg_resources
-    A module which ships with :term:`setuptools` that provides an API
-    for addressing "resource files" within Python packages.  Resource
-    files are static files, template files, etc; basically anything
-    non-Python-source that lives in a Python package can be considered
-    a resource file.  See also `PkgResources
-    <http://peak.telecommunity.com/DevCenter/PkgResources>`_
-  Resource
-    Any file contained within a Python :term:`package` which is *not*
-    a Python source code file.
-  Resource Specification
-    A colon-delimited identifier for a :term:`resource`.  The colon
-    separates a Python :term:`package` name from a package subpath.
-    For example, the resource specification
-    ``my.package:static/baz.css`` identifies the file named
-    ``baz.css`` in the ``static`` subdirectory of the ``my.package``
-    Python :term:`package`.
-  Package
-    A directory on disk which contains an ``__init__.py`` file, making
-    it recognizable to Python as a location which can be ``import`` -ed.
-  Project
-    (Setuptools/distutils terminology). A directory on disk which
-    contains a ``setup.py`` file and one or more Python packages.  The
-    ``setup.py`` file contains code that allows the package(s) to be
-    installed, distributed, and tested.
-  Distribution
-    (Setuptools/distutils terminology).  A file representing an
-    installable library or application.  Distributions are usually
-    files that have the suffix of ``.egg``, ``.tar.gz``, or ``.zip``.
-    Distributions are the target of Setuptools commands such as
-    ``easy_install``.
-  Entry Point
-    A :term:`setuptools` indirection, defined within a setuptools
-    :term:`distribution` setup.py.  It is usually a name which refers
-    to a function somewhere in a package which is held by the
-    distribution.
-  Dotted Python name
-    A reference to a Python object by name using a string, in the form
-    ``path.to.modulename:attributename``.  Often used in Paste and
-    setuptools configurations.  A variant is used in dotted names
-    within :term:`ZCML` attributes that name objects (such as the ZCML
-    "view" directive's "view" attribute): the colon (``:``) is not
-    used; in its place is a dot.
-  View
-    Common vernacular for a :term:`view callable`.
-  View Callable
-    A "view callable" is a callable Python object which is associated
-    with a :term:`view configuration`; it returns a :term:`response`
-    object .  A view callable accepts a single argument: ``request``,
-    which will be an instance of a :term:`request` object.  An
-    alternate calling convention allows a view to be defined as a
-    callable which accepts a pair of arguments: ``context`` and
-    ``request``: this calling convention is useful for traversal-based
-    applications in which a :term:`context` is always very important.  A
-    view callable is the primary mechanism by which a developer writes
-    user interface code within :mod:`repoze.bfg`.  See
-    :ref:`views_chapter` for more information about :mod:`repoze.bfg`
-    view callables.
-  View Configuration
-    View configuration is the act of associating a :term:`view
-    callable` with configuration information.  This configuration
-    information helps map a given :term:`request` to a particular view
-    callable and it can influence the response of a view callable.
-    :mod:`repoze.bfg` views can be configured via :term:`imperative
-    configuration`, :term:`ZCML` or by a special ``@bfg_view``
-    decorator coupled with a :term:`scan`.  See :ref:`views_chapter`
-    for more information about view configuration.
-  View name
-    The "URL name" of a view, e.g ``index.html``.  If a view is
-    configured without a name, its name is considered to be the empty
-    string (which implies the :term:`default view`).
-  Default view
-    The default view of a model is the view invoked when the
-    :term:`view name` is the empty string (``''``).  This is the case
-    when :term:`traversal` exhausts the path elements in the PATH_INFO
-    of a request before it returns a :term:`context`.
-  Virtualenv
-    An isolated Python environment.  Allows you to control which
-    packages are used on a particular project by cloning your main
-    Python.  `virtualenv <http://pypi.python.org/pypi/virtualenv>`_
-    was created by Ian Bicking.
-  Model
-    An object representing data in the system.  If :mod:`traversal` is
-    used, a model is a node in the object graph traversed by the
-    system.  When traversal is used, a model instance becomes the
-    :term:`context` of a :term:`view`.  If :mod:`url dispatch` is
-    used, a single :term:`context` is generated for each request and
-    is used as the context of a view: this object is also technically
-    a "model" in :mod:`repoze.bfg` terms, although this terminology
-    can be a bit confusing: see :ref:`model_traversal_confusion`.
-  Traversal
-    The act of descending "down" a graph of model objects from a root
-    model in order to find a :term:`context`.  The :mod:`repoze.bfg`
-    :term:`router` performs traversal of model objects when a
-    :term:`root factory` is specified.  See the
-    :ref:`traversal_chapter` chapter for more information.  Traversal
-    can be performed *instead* of :term:`URL dispatch` or can be
-    combined *with* URL dispatch.  See :ref:`hybrid_chapter` for more
-    information about combining traversal and URL dispatch (advanced).
-  Router
-    The :term:`WSGI` application created when you start a
-    :mod:`repoze.bfg` application.  The router intercepts requests,
-    invokes traversal and/or URL dispatch, calls view functions, and
-    returns responses to the WSGI server on behalf of your
-    :mod:`repoze.bfg` application.
-  URL dispatch
-    An alternative to graph traversal as a mechanism for locating a
-    :term:`context` for a :term:`view`.  When you use a :term:`route`
-    in your :mod:`repoze.bfg` application via a :term:`route
-    configuration`, you are using URL dispatch. See the
-    :ref:`urldispatch_chapter` for more information.
-  Context
-    An object in the system that is found during :term:`traversal` or
-    :term:`URL dispatch` based on URL data; if it's found via
-    traversal, it's usually a :term:`model` object that is part of an
-    object graph; if it's found via :term:`URL dispatch`, it's a
-    object manufactured on behalf of the route's "factory".  A context
-    becomes the subject of a :term:`view`, and typically has security
-    information attached to it.  See the :ref:`traversal_chapter`
-    chapter and the :ref:`urldispatch_chapter` chapter for more
-    information about how a URL is resolved to a context.
-  Application registry
-    A registry of configuration information consulted by
-    :mod:`repoze.bfg` while servicing an appliation.  An application
-    registry maps model types to views, as well as housing other
-    application-specific component registrations.  Every
-    :mod:`repoze.bfg` application has one (and only one) application
-    registry.
-  Template
-    A file with replaceable parts that is capable of representing some
-    text, XML, or HTML when rendered.
-  Location
-    The path to an object in an object graph.  See :ref:`location_aware`
-    for more information about how to make a model object *location-aware*.
-  Principal
-    A user id or group id.
-  Permission
-    A string or unicode object that represents an action being taken
-    against a context.  A permission is associated with a view name
-    and a model type by the developer.  Models are decorated with
-    security declarations (e.g. an :term:`ACL`), which reference these
-    tokens also.  Permissions are used by the active to security
-    policy to match the view permission against the model's statements
-    about which permissions are granted to which principal in a
-    context in order to to answer the question "is this user allowed
-    to do this".  Examples of permissions: ``read``, or
-    ``view_blog_entries``.
-  ACE
-    An *access control entry*.  An access control entry is one element
-    in an :term:`ACL`.  An access control entry is a three-tuple that
-    describes three things: an *action* (one of either ``Allow`` or
-    ``Deny``), a :term:`principal` (a string describing a user or
-    group), and a :term:`permission`.  For example the ACE, ``(Allow,
-    'bob', 'read')`` is a member of an ACL that indicates that the
-    principal ``bob`` is allowed the permission ``read`` against the
-    context the ACL is attached to.
-  ACL
-    An *access control list*.  An ACL is a sequence of :term:`ACE`
-    tuples.  An ACL is attached to a model instance.  An example of an
-    ACL is ``[ (Allow, 'bob', 'read'), (Deny, 'fred', 'write')]``.  If
-    an ACL is attached to a model instance, and that model instance is
-    findable via the context, it will be consulted any active security
-    policy to determine wither a particular request can be fulfilled
-    given the :term:`authentication` information in the request.
-  Authentication
-    The act of determining that the credentials a user presents during
-    a particular request are "good".  :mod:`repoze.bfg` uses the
-    :term:`authentication` data supplied by the upstream component as
-    one input during :term:`authorization`.  Authentication in
-    :mod:`repoze.bfg` is performed via an :term:`authentication
-    policy`.
-  Authorization
-    The act of determining whether a user can perform a specific
-    action.  In bfg terms, this means determining whether, for a given
-    context, any :term:`principal` (or principals) associated with the
-    request have the requisite :term:`permission` to allow the request
-    to continue.  Authorization in :mod:`repoze.bfg` is performed via
-    its :term:`authorization policy`.
-  Principal
-    A *principal* is a string or unicode object representing a user or
-    a user's membership in a group.  It is provided by an
-    :term:`authentication policy`.  For example, if a user had the
-    user id "bob", and Bob was part of two groups named "group foo"
-    and "group bar", the request might have information attached to it
-    that would indictate that Bob was represented by three principals:
-    "bob", "group foo" and "group bar".
-  Authorization Policy
-    An authorization policy in :mod:`repoze.bfg` terms is a bit of
-    code which has an API which determines whether or not the
-    principals associated with the request can perform an action
-    associated with a permission, based on the information found on the
-    :term:`context`.
-  Authentication Policy
-    An authentication policy in :mod:`repoze.bfg` terms is a bit of
-    code which has an API which determines the current
-    :term:`principal` (or principals) associated with a request.
-  WSGI
-    `Web Server Gateway Interface <http://wsgi.org/>`_.  This is a
-    Python standard for connecting web applications to web servers,
-    similar to the concept of Java Servlets.  ``repoze.bfg`` requires
-    that your application be served as a WSGI application.
-  Middleware
-    *Middleware* is a :term:`WSGI` concept.  It is a WSGI component
-    that acts both as a server and an application.  Interesting uses
-    for middleware exist, such as caching, content-transport
-    encoding, and other functions.  See `WSGI.org <http://wsgi.org>`_
-    or `PyPI <http://python.org/pypi>`_ to find middleware for your
-    application.
-  Pipeline
-    The :term:`Paste` term for a single configuration of a WSGI
-    server, a WSGI application, with a set of middleware in-between.
-  mod_wsgi
-    An `Apache module <http://code.google.com/p/modwsgi/>`_ for hosting
-    Python WSGI applications.
-  Zope
-    `The Z Object Publishing Framework <http://zope.org>`_, a
-    full-featured Python web framework.
-  Grok
-    `A web framework based on Zope 3 <http://grok.zope.org>`_.
-  Django
-    `A full-featured Python web framework <http://djangoproject.com>`_.
-  Pylons
-    `A lightweight Python web framework <http://pylonshq.com>`_.
-  ZODB
-     `Zope Object Database <http://wiki.zope.org/ZODB/FrontPage>`_, a
-     persistent Python object store.
-  ZEO
-     `Zope Enterprise Objects
-     <http://www.zope.org/Documentation/Books/ZopeBook/2_6Edition/ZEO.stx>`_
-     allows multiple simultaneous processes to access a single
-     :term:`ZODB` database.
-  WebOb
-    `WebOb <http://pythonpaste.org/webob/>`_ is a WSGI request/response
-    library created by Ian Bicking.
-  Paste
-    `Paste <http://pythonpaste.org>`_ is a WSGI development and
-    deployment system developed by Ian Bicking.
-  PasteDeploy
-    `PasteDeploy <http://pythonpaste.org>`_ is a library used by
-    :mod:`repoze.bfg` which makes it possible to configure
-    :term:`WSGI` components together declaratively within an ``.ini``
-    file.  It was developed by Ian Bicking as part of :term:`Paste`.
-  Chameleon
-    `chameleon <http://chameleon.repoze.org>`_ is an attribute
-    language template compiler which supports both the :term:`ZPT` and
-    :term:`Genshi` templating specifications.  It is written and
-    maintained by Malthe Borch.  It has several extensions, such as
-    the ability to use bracketed (Genshi-style) ``${name}`` syntax,
-    even within ZPT.  It is also much faster than the reference
-    implementations of both ZPT and Genshi.  :mod:`repoze.bfg` offers
-    Chameleon templating out of the box in ZPT and text flavors.
-  ZPT
-    The `Zope Page Template <http://wiki.zope.org/ZPT/FrontPage>`_
-    templating language.
-  METAL
-    `Macro Expansion for TAL <http://wiki.zope.org/ZPT/METAL>`_, a
-    part of :term:`ZPT` which makes it possible to share common look
-    and feel between templates.  
-  Genshi
-    An `XML templating language <http://pypi.python.org/pypi/Genshi/>`_
-    by Christopher Lenz.
-  Jinja2
-    A `text templating language <http://jinja.pocoo.org/2/>`_ by Armin 
-    Ronacher.
-  Routes
-    A `system by Ben Bangert <http://routes.groovie.org/>`_ which
-    parses URLs and compares them against a number of user defined
-    mappings. The URL pattern matching syntax in :mod:`repoze.bfg` is
-    inspired by the Routes syntax (which was inspired by Ruby On
-    Rails pattern syntax).
-  Route
-    A single pattern matched by the :term:`url dispatch` subsystem,
-    which generally resolves to a :term:`root factory` (and then
-    ultimately a :term:`view`).  See also :term:`url dispatch`.
-  Route Configuration
-    Route configuration is the act of using :term:`imperative
-    configuration` or a :term:`ZCML` ``<route>`` statement to
-    associate request parameters with a particular :term:`route` using
-    pattern matching and :term:`route predicate` statements.  See
-    :ref:`urldispatch_chapter` for more information about route
-    configuration.
-  ZCML
-    `Zope Configuration Markup Language
-    <http://www.muthukadan.net/docs/zca.html#zcml>`_, an XML dialect
-    used by Zope and :mod:`repoze.bfg` for configuration tasks.  ZCML
-    is capable of performing different types of :term:`configuration
-    declaration`, but its primary purpose in :mod:`repoze.bfg` is to
-    perform :term:`view configuration` and :term:`route configuration`
-    within the ``configure.zcml`` file in a :mod:`repoze.bfg`
-    application.  You can use ZCML as an alternative to
-    :term:`imperative configuration`.
-  ZCML Directive
-    A ZCML "tag" such as ``<view>`` or ``<route>``.
-  ZCML Declaration
-    The concrete use of a :term:`ZCML directive` within a ZCML file.
-  Zope Component Architecture
-    The `Zope Component Architecture
-    <http://www.muthukadan.net/docs/zca.html>`_ (aka ZCA) is a system
-    which allows for application pluggability and complex dispatching
-    based on objects which implement an :term:`interface`.
-    :mod:`repoze.bfg` uses the ZCA "under the hood" to perform view
-    dispatching and other application configuration tasks.
-  ReStructuredText
-    A `plain text format <http://docutils.sourceforge.net/rst.html>`_
-    that is the defacto standard for descriptive text shipped in
-    :term:`distribution` files, and Python docstrings.  This
-    documentation is authored in ReStructuredText format.
-  Root
-    The object at which :term:`traversal` begins when
-    :mod:`repoze.bfg` searches for a :term:`context` (for :term:`URL
-    Dispatch`, the root is *always* the context).
-  Subpath
-    A list of element "left over" after the :term:`router` has
-    performed a successful traversal to a view.  The subpath is a
-    sequence of strings, e.g. ``['left', 'over', 'names']``.  Within
-    BFG applications that use URL dispatch rather than traversal, you
-    can use ``*subpath`` in the route pattern to influence the
-    subpath.  See :ref:`star_subpath` for more information.
-  Interface
-    A `Zope interface <http://pypi.python.org/pypi/zope.interface>`_
-    object.  In :mod:`repoze.bfg`, an interface may be attached to a
-    :term:`model` object or a :term:`request` object in order to
-    identify that the object is "of a type".  Interfaces are used
-    internally by :mod:`repoze.bfg` to perform view lookups and other
-    policy lookups.  The ability to make use of an interface is
-    exposed to an application programmers during :term:`view
-    configuration` via the ``for`` argument, the ``request_type``
-    argument and the ``containment`` argument.  Interfaces are also
-    exposed to application developers when they make use of the
-    :term:`event` system. Fundamentally, :mod:`repoze.bfg` programmers
-    can think of an interface as something that they can attach to an
-    object that stamps it with a "type" unrelated to its underlying
-    Python type.  Interfaces can also be used to describe the behavior
-    of an object (its methods and attributes), but unless they choose
-    to, :mod:`repoze.bfg` programmers do not need to understand or use
-    this feature of interfaces.
-  Event
-    An object broadcast to zero or more :term:`subscriber` callables
-    during normal :mod:`repoze.bfg` system operations during the
-    lifetime of an application.  Application code can subscribe to
-    these events by using the subscriber functionality described in
-    :ref:`events_chapter`.
-  Subscriber
-    A callable which receives an :term:`event`.  A callable becomes a
-    subscriber via :term:`imperative configuration` or the
-    ``<subscriber>`` ZCML directive.  See :ref:`events_chapter` for
-    more information.
-  Request type
-    An attribute of a :term:`request` that allows for specialization
-    of view invocation based on arbitrary categorization.  The every
-    :term:`request` object that :mod:`repoze.bfg` generates and
-    manipulates has one or more :term:`interface` objects attached to
-    it.  The default interface attached to a request object is
-    ``repoze.bfg.interfaces.IRequest``.
-  repoze.lemonade
-    Zope2 CMF-like `data structures and helper facilities
-    <http://docs.repoze.org/lemonade>`_ for CA-and-ZODB-based
-    applications useful within bfg applications.
-  repoze.catalog
-    An indexing and search facility (fielded and full-text) based on
-    `zope.index <http://pypi.python.org/pypi/zope.index>`_.  See `the
-    documentation <http://docs.repoze.org/catalog>`_ for more
-    information.
-  repoze.who
-    `Authentication middleware <http://docs.repoze.org/who>`_ for
-    :term:`WSGI` applications.  It can be used by :mod:`repoze.bfg` to
-    provide authentication information.
-  repoze.workflow
-    `Barebones workflow for Python apps
-    <http://docs.repoze.org/workflow>`_ .  It can be used by
-    :mod:`repoze.bfg` to form a workflow system.
-  Virtual root
-    A model object representing the "virtual" root of a request; this
-    is typically the physical root object (the object returned by the
-    application root factory) unless :ref:`vhosting_chapter` is in
-    use.
-  Lineage
-    An ordered sequence of objects based on a ":term:`location`
-    -aware" context.  The lineage of any given :term:`context` is
-    composed of itself, its parent, its parent's parent, and so on.
-    The order of the sequence is context-first, then the parent of the
-    context, then its parent's parent, and so on.  The parent of an
-    object in a lineage is available as its ``__parent__`` attribute.
-  Root Factory
-    The "root factory" of an :mod:`repoze.bfg` application is called
-    on every request sent to the application.  The root factory
-    returns the traversal root of an application.  It is
-    conventionally named ``get_root``.  An application may supply a
-    root factory to :mod:`repoze.bfg` during the construction of a
-    :term:`Configurator`.  If a root factory is not supplied, the
-    application uses a default root object.  Use of the default root
-    object is useful in application which use :term:`URL dispatch` for
-    all URL-to-view code mappings.
-  SQLAlchemy
-    `SQLAlchemy' <http://www.sqlalchemy.org/>`_ is an object
-    relational mapper used in tutorials within this documentation.
-  JSON
-    `JavaScript Object Notation <http://www.json.org/>`_ is a data
-    serialization format.
-  Renderer
-    A registered serializer that can be configured via :term:`view
-    configuration` which converts a non-:term:`Response` return values
-    from a :term:`view` into a string (and ultimately a response).
-    Using a renderer can make writing views that require templating or
-    other serialization less tedious.  See
-    :ref:`views_which_use_a_renderer` for more information.
-  mod_wsgi
-    `mod_wsgi <http://code.google.com/p/modwsgi/>`_ is an Apache
-    module developed by Graham Dumpleton.  It allows :term:`WSGI`
-    applications (such as applications developed using
-    :mod:`repoze.bfg`) to be served using the Apache web server.
-  View Predicate
-    An argument to a :term:`view configuration` which evaluates to
-    ``True`` or ``False`` for a given :term:`request`.  All predicates
-    attached to a view configuration must evaluate to true for the
-    associated view to be considered as a possible callable for a
-    given request.
-  Route Predicate
-    An argument to a :term:`route configuration` which implies a value
-    that evaluates to ``True`` or ``False`` for a given
-    :term:`request`.  All predicates attached to a :term:`route
-    configuration` must evaluate to ``True`` for the associated route
-    to "match" the current request.  If a route does not match the
-    current request, the next route (in definition order) is
-    attempted.
-  Predicate
-    A test which returns ``True`` or ``False``.  Two different types
-    of predicates exist in :mod:`repoze.bfg`: a :term:`view predicate`
-    and a :term:`route predicate`.  View predicates are attached to
-    :term:`view configuration` and route predicates are attached to
-    :term:`route configuration`.
-  Decorator
-    A wrapper around a Python function or class which accepts the
-    function or class as its first argument and which returns an
-    arbitrary object.  :mod:`repoze.bfg` provides several decorators,
-    used for configuration and return value modification purposes.  See
-    also `PEP 318 <http://www.python.org/dev/peps/pep-0318/>`_.
-  Configuration Declaration
-    An individual method call made to an instance of a
-    :mod:`repoze.bfg` :term:`Configurator` object which performs an
-    arbitrary action, such as registering a :term:`view configuration`
-    (via the ``view`` method of the configurator) or :term:`route
-    configuration` (via the ``route`` method of the configurator).  A
-    set of configuration declarations is also usually implied via the
-    use of a :term:`ZCML declaration` within an application, or a set
-    of configuration declarations might be performed by a :term:`scan`
-    of code in a package.
-  Configuration Decoration
-    Metadata implying one or more :term:`configuration declaration`
-    invocations.  Often set by configuration Python :term:`decorator`
-    attributes, such as ``repoze.bfg.view.bfg_view``, aka ``@bfg_view``.
-  Scan
-    The term used by :mod:`repoze.bfg` to define the process of
-    importing and examining all code in a Python package or module for
-    :term:`configuration decoration`.
-  Configurator
-    An object used to do :term:`configuration declaration` within an
-    application.  The most common configurator is an instance of the
-    ``repoze.bfg.configuration.Configurator`` class.
-  Imperative Configuration
-    The configuration mode in which you use Python to call methods on
-    a :term:`Configurator` in order to add each :term:`configuration
-    declaration` required by your application.
-  Declarative Configuration
-    The configuration mode in which you use :term:`ZCML` to make
-    a set of :term:`configuration declaration` statements.
-  Not Found View
-     The :term:`view callable` invoked by :mod:`repoze.bfg` when the
-     developer explicitly raises a
-     ``repoze.bfg.exceptions.NotFound`` exception from within
-     :term:`view` code or :term:`root factory` code, or when the
-     current request doesn't match any :term:`view configuration`.
-     :mod:`repoze.bfg` provides a default implementation of a not
-     found view; it can be overridden.  See
-     :ref:`changing_the_notfound_view`.
-  Forbidden View
-     The :term:`view callable` invoked by :mod:`repoze.bfg` when the
-     developer explicitly raises a
-     ``repoze.bfg.exceptions.Forbidden`` exception from within
-     :term:`view` code or :term:`root factory` code, or when the the
-     :term:`view configuration` and :term:`authorization policy` found
-     for a request disallows a particular view invocation.
-     :mod:`repoze.bfg` provides a default implementation of a
-     forbidden view; it can be overridden.  See
-     :ref:`changing_the_forbidden_view`.
-  Thread Local
-     A thread-local variable is one which is essentially a global
-     variable in terms of how it is accessed and treated, however,
-     each `thread
-     <http://en.wikipedia.org/wiki/Thread_(computer_science)>` used by
-     the application may have a different value for this same "global"
-     variable.  :mod:`repoze.bfg` uses a small number of thread local
-     variables, as described in :ref:`threadlocals_chapter`. See also
-     the `threading.local documentation
-     <http://docs.python.org/library/threading.html#threading.local>`
-     for more information.
+   Request
+     A ``WebOb`` request object.  See :ref:`webob_chapter` for
+     information about request objects.
 
+   Response
+     An object that has three attributes: ``app_iter`` (representing an
+     iterable body), ``headerlist`` (representing the http headers sent
+     to the user agent), and ``status`` (representing the http status
+     string sent to the user agent).  This is the interface defined for
+     ``WebOb`` response objects.  See :ref:`webob_chapter` for
+     information about response objects.
+
+   Repoze
+     "Repoze" is essentially a "brand" of software developed by
+     `Agendaless Consulting <http://agendaless.com>`_ and a set of
+     contributors.  The term has no special intrinsic meaning.  The
+     project's `website <http://repoze.org>`_ has more information.
+     The software developed "under the brand" is available in a
+     `Subversion repository <http://svn.repoze.org>`_.
+
+   Setuptools
+     `Setuptools <http://peak.telecommunity.com/DevCenter/setuptools>`_
+     builds on Python's ``distutils`` to provide easier building,
+     distribution, and installation of libraries and applications.
+
+   pkg_resources
+     A module which ships with :term:`setuptools` that provides an API
+     for addressing "resource files" within Python packages.  Resource
+     files are static files, template files, etc; basically anything
+     non-Python-source that lives in a Python package can be considered
+     a resource file.  See also `PkgResources
+     <http://peak.telecommunity.com/DevCenter/PkgResources>`_
+
+   Resource
+     Any file contained within a Python :term:`package` which is *not*
+     a Python source code file.
+
+   Resource Specification
+     A colon-delimited identifier for a :term:`resource`.  The colon
+     separates a Python :term:`package` name from a package subpath.
+     For example, the resource specification
+     ``my.package:static/baz.css`` identifies the file named
+     ``baz.css`` in the ``static`` subdirectory of the ``my.package``
+     Python :term:`package`.
+
+   Package
+     A directory on disk which contains an ``__init__.py`` file, making
+     it recognizable to Python as a location which can be ``import`` -ed.
+
+   Project
+     (Setuptools/distutils terminology). A directory on disk which
+     contains a ``setup.py`` file and one or more Python packages.  The
+     ``setup.py`` file contains code that allows the package(s) to be
+     installed, distributed, and tested.
+
+   Distribution
+     (Setuptools/distutils terminology).  A file representing an
+     installable library or application.  Distributions are usually
+     files that have the suffix of ``.egg``, ``.tar.gz``, or ``.zip``.
+     Distributions are the target of Setuptools commands such as
+     ``easy_install``.
+
+   Entry Point
+     A :term:`setuptools` indirection, defined within a setuptools
+     :term:`distribution` setup.py.  It is usually a name which refers
+     to a function somewhere in a package which is held by the
+     distribution.
+
+   Dotted Python name
+     A reference to a Python object by name using a string, in the form
+     ``path.to.modulename:attributename``.  Often used in Paste and
+     setuptools configurations.  A variant is used in dotted names
+     within :term:`ZCML` attributes that name objects (such as the ZCML
+     "view" directive's "view" attribute): the colon (``:``) is not
+     used; in its place is a dot.
+
+   View
+     Common vernacular for a :term:`view callable`.
+
+   View Callable
+     A "view callable" is a callable Python object which is associated
+     with a :term:`view configuration`; it returns a :term:`response`
+     object .  A view callable accepts a single argument: ``request``,
+     which will be an instance of a :term:`request` object.  An
+     alternate calling convention allows a view to be defined as a
+     callable which accepts a pair of arguments: ``context`` and
+     ``request``: this calling convention is useful for traversal-based
+     applications in which a :term:`context` is always very important.  A
+     view callable is the primary mechanism by which a developer writes
+     user interface code within :mod:`repoze.bfg`.  See
+     :ref:`views_chapter` for more information about :mod:`repoze.bfg`
+     view callables.
+
+   View Configuration
+     View configuration is the act of associating a :term:`view
+     callable` with configuration information.  This configuration
+     information helps map a given :term:`request` to a particular view
+     callable and it can influence the response of a view callable.
+     :mod:`repoze.bfg` views can be configured via :term:`imperative
+     configuration`, :term:`ZCML` or by a special ``@bfg_view``
+     decorator coupled with a :term:`scan`.  See :ref:`views_chapter`
+     for more information about view configuration.
+
+   View name
+     The "URL name" of a view, e.g ``index.html``.  If a view is
+     configured without a name, its name is considered to be the empty
+     string (which implies the :term:`default view`).
+
+   Default view
+     The default view of a model is the view invoked when the
+     :term:`view name` is the empty string (``''``).  This is the case
+     when :term:`traversal` exhausts the path elements in the PATH_INFO
+     of a request before it returns a :term:`context`.
+
+   Virtualenv
+     An isolated Python environment.  Allows you to control which
+     packages are used on a particular project by cloning your main
+     Python.  `virtualenv <http://pypi.python.org/pypi/virtualenv>`_
+     was created by Ian Bicking.
+
+   Model
+     An object representing data in the system.  If :mod:`traversal` is
+     used, a model is a node in the object graph traversed by the
+     system.  When traversal is used, a model instance becomes the
+     :term:`context` of a :term:`view`.  If :mod:`url dispatch` is
+     used, a single :term:`context` is generated for each request and
+     is used as the context of a view: this object is also technically
+     a "model" in :mod:`repoze.bfg` terms, although this terminology
+     can be a bit confusing: see :ref:`model_traversal_confusion`.
+
+   Traversal
+     The act of descending "down" a graph of model objects from a root
+     model in order to find a :term:`context`.  The :mod:`repoze.bfg`
+     :term:`router` performs traversal of model objects when a
+     :term:`root factory` is specified.  See the
+     :ref:`traversal_chapter` chapter for more information.  Traversal
+     can be performed *instead* of :term:`URL dispatch` or can be
+     combined *with* URL dispatch.  See :ref:`hybrid_chapter` for more
+     information about combining traversal and URL dispatch (advanced).
+
+   Router
+     The :term:`WSGI` application created when you start a
+     :mod:`repoze.bfg` application.  The router intercepts requests,
+     invokes traversal and/or URL dispatch, calls view functions, and
+     returns responses to the WSGI server on behalf of your
+     :mod:`repoze.bfg` application.
+
+   URL dispatch
+     An alternative to graph traversal as a mechanism for locating a
+     :term:`context` for a :term:`view`.  When you use a :term:`route`
+     in your :mod:`repoze.bfg` application via a :term:`route
+     configuration`, you are using URL dispatch. See the
+     :ref:`urldispatch_chapter` for more information.
+
+   Context
+     An object in the system that is found during :term:`traversal` or
+     :term:`URL dispatch` based on URL data; if it's found via
+     traversal, it's usually a :term:`model` object that is part of an
+     object graph; if it's found via :term:`URL dispatch`, it's a
+     object manufactured on behalf of the route's "factory".  A context
+     becomes the subject of a :term:`view`, and typically has security
+     information attached to it.  See the :ref:`traversal_chapter`
+     chapter and the :ref:`urldispatch_chapter` chapter for more
+     information about how a URL is resolved to a context.
+
+   Application registry
+     A registry of configuration information consulted by
+     :mod:`repoze.bfg` while servicing an appliation.  An application
+     registry maps model types to views, as well as housing other
+     application-specific component registrations.  Every
+     :mod:`repoze.bfg` application has one (and only one) application
+     registry.
+
+   Template
+     A file with replaceable parts that is capable of representing some
+     text, XML, or HTML when rendered.
+
+   Location
+     The path to an object in an object graph.  See :ref:`location_aware`
+     for more information about how to make a model object *location-aware*.
+
+   Permission
+     A string or unicode object that represents an action being taken
+     against a context.  A permission is associated with a view name
+     and a model type by the developer.  Models are decorated with
+     security declarations (e.g. an :term:`ACL`), which reference these
+     tokens also.  Permissions are used by the active to security
+     policy to match the view permission against the model's statements
+     about which permissions are granted to which principal in a
+     context in order to to answer the question "is this user allowed
+     to do this".  Examples of permissions: ``read``, or
+     ``view_blog_entries``.
+
+   ACE
+     An *access control entry*.  An access control entry is one element
+     in an :term:`ACL`.  An access control entry is a three-tuple that
+     describes three things: an *action* (one of either ``Allow`` or
+     ``Deny``), a :term:`principal` (a string describing a user or
+     group), and a :term:`permission`.  For example the ACE, ``(Allow,
+     'bob', 'read')`` is a member of an ACL that indicates that the
+     principal ``bob`` is allowed the permission ``read`` against the
+     context the ACL is attached to.
+
+   ACL
+     An *access control list*.  An ACL is a sequence of :term:`ACE`
+     tuples.  An ACL is attached to a model instance.  An example of an
+     ACL is ``[ (Allow, 'bob', 'read'), (Deny, 'fred', 'write')]``.  If
+     an ACL is attached to a model instance, and that model instance is
+     findable via the context, it will be consulted any active security
+     policy to determine wither a particular request can be fulfilled
+     given the :term:`authentication` information in the request.
+
+   Authentication
+     The act of determining that the credentials a user presents during
+     a particular request are "good".  :mod:`repoze.bfg` uses the
+     :term:`authentication` data supplied by the upstream component as
+     one input during :term:`authorization`.  Authentication in
+     :mod:`repoze.bfg` is performed via an :term:`authentication
+     policy`.
+
+   Authorization
+     The act of determining whether a user can perform a specific
+     action.  In bfg terms, this means determining whether, for a given
+     context, any :term:`principal` (or principals) associated with the
+     request have the requisite :term:`permission` to allow the request
+     to continue.  Authorization in :mod:`repoze.bfg` is performed via
+     its :term:`authorization policy`.
+
+   Principal
+     A *principal* is a string or unicode object representing a userid
+     or a group id.  It is provided by an :term:`authentication
+     policy`.  For example, if a user had the user id "bob", and Bob
+     was part of two groups named "group foo" and "group bar", the
+     request might have information attached to it that would
+     indictate that Bob was represented by three principals: "bob",
+     "group foo" and "group bar".
+
+   Authorization Policy
+     An authorization policy in :mod:`repoze.bfg` terms is a bit of
+     code which has an API which determines whether or not the
+     principals associated with the request can perform an action
+     associated with a permission, based on the information found on the
+     :term:`context`.
+
+   Authentication Policy
+     An authentication policy in :mod:`repoze.bfg` terms is a bit of
+     code which has an API which determines the current
+     :term:`principal` (or principals) associated with a request.
+
+   WSGI
+     `Web Server Gateway Interface <http://wsgi.org/>`_.  This is a
+     Python standard for connecting web applications to web servers,
+     similar to the concept of Java Servlets.  ``repoze.bfg`` requires
+     that your application be served as a WSGI application.
+
+   Middleware
+     *Middleware* is a :term:`WSGI` concept.  It is a WSGI component
+     that acts both as a server and an application.  Interesting uses
+     for middleware exist, such as caching, content-transport
+     encoding, and other functions.  See `WSGI.org <http://wsgi.org>`_
+     or `PyPI <http://python.org/pypi>`_ to find middleware for your
+     application.
+
+   Pipeline
+     The :term:`Paste` term for a single configuration of a WSGI
+     server, a WSGI application, with a set of middleware in-between.
+
+   Zope
+     `The Z Object Publishing Framework <http://zope.org>`_, a
+     full-featured Python web framework.
+
+   Grok
+     `A web framework based on Zope 3 <http://grok.zope.org>`_.
+
+   Django
+     `A full-featured Python web framework <http://djangoproject.com>`_.
+
+   Pylons
+     `A lightweight Python web framework <http://pylonshq.com>`_.
+
+   ZODB
+      `Zope Object Database <http://wiki.zope.org/ZODB/FrontPage>`_, a
+      persistent Python object store.
+
+   ZEO
+      `Zope Enterprise Objects
+      <http://www.zope.org/Documentation/Books/ZopeBook/2_6Edition/ZEO.stx>`_
+      allows multiple simultaneous processes to access a single
+      :term:`ZODB` database.
+
+   WebOb
+     `WebOb <http://pythonpaste.org/webob/>`_ is a WSGI request/response
+     library created by Ian Bicking.
+
+   Paste
+     `Paste <http://pythonpaste.org>`_ is a WSGI development and
+     deployment system developed by Ian Bicking.
+
+   PasteDeploy
+     `PasteDeploy <http://pythonpaste.org>`_ is a library used by
+     :mod:`repoze.bfg` which makes it possible to configure
+     :term:`WSGI` components together declaratively within an ``.ini``
+     file.  It was developed by Ian Bicking as part of :term:`Paste`.
+
+   Chameleon
+     `chameleon <http://chameleon.repoze.org>`_ is an attribute
+     language template compiler which supports both the :term:`ZPT` and
+     :term:`Genshi` templating specifications.  It is written and
+     maintained by Malthe Borch.  It has several extensions, such as
+     the ability to use bracketed (Genshi-style) ``${name}`` syntax,
+     even within ZPT.  It is also much faster than the reference
+     implementations of both ZPT and Genshi.  :mod:`repoze.bfg` offers
+     Chameleon templating out of the box in ZPT and text flavors.
+
+   ZPT
+     The `Zope Page Template <http://wiki.zope.org/ZPT/FrontPage>`_
+     templating language.
+
+   METAL
+     `Macro Expansion for TAL <http://wiki.zope.org/ZPT/METAL>`_, a
+     part of :term:`ZPT` which makes it possible to share common look
+     and feel between templates.  
+
+   Genshi
+     An `XML templating language <http://pypi.python.org/pypi/Genshi/>`_
+     by Christopher Lenz.
+
+   Jinja2
+     A `text templating language <http://jinja.pocoo.org/2/>`_ by Armin 
+     Ronacher.
+
+   Routes
+     A `system by Ben Bangert <http://routes.groovie.org/>`_ which
+     parses URLs and compares them against a number of user defined
+     mappings. The URL pattern matching syntax in :mod:`repoze.bfg` is
+     inspired by the Routes syntax (which was inspired by Ruby On
+     Rails pattern syntax).
+
+   Route
+     A single pattern matched by the :term:`url dispatch` subsystem,
+     which generally resolves to a :term:`root factory` (and then
+     ultimately a :term:`view`).  See also :term:`url dispatch`.
+
+   Route Configuration
+     Route configuration is the act of using :term:`imperative
+     configuration` or a :term:`ZCML` ``<route>`` statement to
+     associate request parameters with a particular :term:`route` using
+     pattern matching and :term:`route predicate` statements.  See
+     :ref:`urldispatch_chapter` for more information about route
+     configuration.
+
+   ZCML
+     `Zope Configuration Markup Language
+     <http://www.muthukadan.net/docs/zca.html#zcml>`_, an XML dialect
+     used by Zope and :mod:`repoze.bfg` for configuration tasks.  ZCML
+     is capable of performing different types of :term:`configuration
+     declaration`, but its primary purpose in :mod:`repoze.bfg` is to
+     perform :term:`view configuration` and :term:`route configuration`
+     within the ``configure.zcml`` file in a :mod:`repoze.bfg`
+     application.  You can use ZCML as an alternative to
+     :term:`imperative configuration`.
+
+   ZCML Directive
+     A ZCML "tag" such as ``<view>`` or ``<route>``.
+
+   ZCML Declaration
+     The concrete use of a :term:`ZCML directive` within a ZCML file.
+
+   Zope Component Architecture
+     The `Zope Component Architecture
+     <http://www.muthukadan.net/docs/zca.html>`_ (aka ZCA) is a system
+     which allows for application pluggability and complex dispatching
+     based on objects which implement an :term:`interface`.
+     :mod:`repoze.bfg` uses the ZCA "under the hood" to perform view
+     dispatching and other application configuration tasks.
+
+   ReStructuredText
+     A `plain text format <http://docutils.sourceforge.net/rst.html>`_
+     that is the defacto standard for descriptive text shipped in
+     :term:`distribution` files, and Python docstrings.  This
+     documentation is authored in ReStructuredText format.
+
+   Root
+     The object at which :term:`traversal` begins when
+     :mod:`repoze.bfg` searches for a :term:`context` (for :term:`URL
+     Dispatch`, the root is *always* the context).
+
+   Subpath
+     A list of element "left over" after the :term:`router` has
+     performed a successful traversal to a view.  The subpath is a
+     sequence of strings, e.g. ``['left', 'over', 'names']``.  Within
+     BFG applications that use URL dispatch rather than traversal, you
+     can use ``*subpath`` in the route pattern to influence the
+     subpath.  See :ref:`star_subpath` for more information.
+
+   Interface
+     A `Zope interface <http://pypi.python.org/pypi/zope.interface>`_
+     object.  In :mod:`repoze.bfg`, an interface may be attached to a
+     :term:`model` object or a :term:`request` object in order to
+     identify that the object is "of a type".  Interfaces are used
+     internally by :mod:`repoze.bfg` to perform view lookups and other
+     policy lookups.  The ability to make use of an interface is
+     exposed to an application programmers during :term:`view
+     configuration` via the ``for`` argument, the ``request_type``
+     argument and the ``containment`` argument.  Interfaces are also
+     exposed to application developers when they make use of the
+     :term:`event` system. Fundamentally, :mod:`repoze.bfg` programmers
+     can think of an interface as something that they can attach to an
+     object that stamps it with a "type" unrelated to its underlying
+     Python type.  Interfaces can also be used to describe the behavior
+     of an object (its methods and attributes), but unless they choose
+     to, :mod:`repoze.bfg` programmers do not need to understand or use
+     this feature of interfaces.
+
+   Event
+     An object broadcast to zero or more :term:`subscriber` callables
+     during normal :mod:`repoze.bfg` system operations during the
+     lifetime of an application.  Application code can subscribe to
+     these events by using the subscriber functionality described in
+     :ref:`events_chapter`.
+
+   Subscriber
+     A callable which receives an :term:`event`.  A callable becomes a
+     subscriber via :term:`imperative configuration` or the
+     ``<subscriber>`` ZCML directive.  See :ref:`events_chapter` for
+     more information.
+
+   Request type
+     An attribute of a :term:`request` that allows for specialization
+     of view invocation based on arbitrary categorization.  The every
+     :term:`request` object that :mod:`repoze.bfg` generates and
+     manipulates has one or more :term:`interface` objects attached to
+     it.  The default interface attached to a request object is
+     ``repoze.bfg.interfaces.IRequest``.
+
+   repoze.lemonade
+     Zope2 CMF-like `data structures and helper facilities
+     <http://docs.repoze.org/lemonade>`_ for CA-and-ZODB-based
+     applications useful within bfg applications.
+
+   repoze.catalog
+     An indexing and search facility (fielded and full-text) based on
+     `zope.index <http://pypi.python.org/pypi/zope.index>`_.  See `the
+     documentation <http://docs.repoze.org/catalog>`_ for more
+     information.
+
+   repoze.who
+     `Authentication middleware <http://docs.repoze.org/who>`_ for
+     :term:`WSGI` applications.  It can be used by :mod:`repoze.bfg` to
+     provide authentication information.
+
+   repoze.workflow
+     `Barebones workflow for Python apps
+     <http://docs.repoze.org/workflow>`_ .  It can be used by
+     :mod:`repoze.bfg` to form a workflow system.
+
+   Virtual root
+     A model object representing the "virtual" root of a request; this
+     is typically the physical root object (the object returned by the
+     application root factory) unless :ref:`vhosting_chapter` is in
+     use.
+
+   Lineage
+     An ordered sequence of objects based on a ":term:`location`
+     -aware" context.  The lineage of any given :term:`context` is
+     composed of itself, its parent, its parent's parent, and so on.
+     The order of the sequence is context-first, then the parent of the
+     context, then its parent's parent, and so on.  The parent of an
+     object in a lineage is available as its ``__parent__`` attribute.
+
+   Root Factory
+     The "root factory" of an :mod:`repoze.bfg` application is called
+     on every request sent to the application.  The root factory
+     returns the traversal root of an application.  It is
+     conventionally named ``get_root``.  An application may supply a
+     root factory to :mod:`repoze.bfg` during the construction of a
+     :term:`Configurator`.  If a root factory is not supplied, the
+     application uses a default root object.  Use of the default root
+     object is useful in application which use :term:`URL dispatch` for
+     all URL-to-view code mappings.
+
+   SQLAlchemy
+     `SQLAlchemy' <http://www.sqlalchemy.org/>`_ is an object
+     relational mapper used in tutorials within this documentation.
+
+   JSON
+     `JavaScript Object Notation <http://www.json.org/>`_ is a data
+     serialization format.
+
+   Renderer
+     A registered serializer that can be configured via :term:`view
+     configuration` which converts a non-:term:`Response` return values
+     from a :term:`view` into a string (and ultimately a response).
+     Using a renderer can make writing views that require templating or
+     other serialization less tedious.  See
+     :ref:`views_which_use_a_renderer` for more information.
+
+   mod_wsgi
+     `mod_wsgi <http://code.google.com/p/modwsgi/>`_ is an Apache
+     module developed by Graham Dumpleton.  It allows :term:`WSGI`
+     applications (such as applications developed using
+     :mod:`repoze.bfg`) to be served using the Apache web server.
+
+   View Predicate
+     An argument to a :term:`view configuration` which evaluates to
+     ``True`` or ``False`` for a given :term:`request`.  All predicates
+     attached to a view configuration must evaluate to true for the
+     associated view to be considered as a possible callable for a
+     given request.
+
+   Route Predicate
+     An argument to a :term:`route configuration` which implies a value
+     that evaluates to ``True`` or ``False`` for a given
+     :term:`request`.  All predicates attached to a :term:`route
+     configuration` must evaluate to ``True`` for the associated route
+     to "match" the current request.  If a route does not match the
+     current request, the next route (in definition order) is
+     attempted.
+
+   Predicate
+     A test which returns ``True`` or ``False``.  Two different types
+     of predicates exist in :mod:`repoze.bfg`: a :term:`view predicate`
+     and a :term:`route predicate`.  View predicates are attached to
+     :term:`view configuration` and route predicates are attached to
+     :term:`route configuration`.
+
+   Decorator
+     A wrapper around a Python function or class which accepts the
+     function or class as its first argument and which returns an
+     arbitrary object.  :mod:`repoze.bfg` provides several decorators,
+     used for configuration and return value modification purposes.  See
+     also `PEP 318 <http://www.python.org/dev/peps/pep-0318/>`_.
+
+   Configuration Declaration
+     An individual method call made to an instance of a
+     :mod:`repoze.bfg` :term:`Configurator` object which performs an
+     arbitrary action, such as registering a :term:`view configuration`
+     (via the ``view`` method of the configurator) or :term:`route
+     configuration` (via the ``route`` method of the configurator).  A
+     set of configuration declarations is also usually implied via the
+     use of a :term:`ZCML declaration` within an application, or a set
+     of configuration declarations might be performed by a :term:`scan`
+     of code in a package.
+
+   Configuration Decoration
+     Metadata implying one or more :term:`configuration declaration`
+     invocations.  Often set by configuration Python :term:`decorator`
+     attributes, such as ``repoze.bfg.view.bfg_view``, aka ``@bfg_view``.
+
+   Scan
+     The term used by :mod:`repoze.bfg` to define the process of
+     importing and examining all code in a Python package or module for
+     :term:`configuration decoration`.
+
+   Configurator
+     An object used to do :term:`configuration declaration` within an
+     application.  The most common configurator is an instance of the
+     ``repoze.bfg.configuration.Configurator`` class.
+
+   Imperative Configuration
+     The configuration mode in which you use Python to call methods on
+     a :term:`Configurator` in order to add each :term:`configuration
+     declaration` required by your application.
+
+   Declarative Configuration
+     The configuration mode in which you use :term:`ZCML` to make
+     a set of :term:`configuration declaration` statements.
+
+   Not Found View
+      The :term:`view callable` invoked by :mod:`repoze.bfg` when the
+      developer explicitly raises a
+      ``repoze.bfg.exceptions.NotFound`` exception from within
+      :term:`view` code or :term:`root factory` code, or when the
+      current request doesn't match any :term:`view configuration`.
+      :mod:`repoze.bfg` provides a default implementation of a not
+      found view; it can be overridden.  See
+      :ref:`changing_the_notfound_view`.
+
+   Forbidden View
+      The :term:`view callable` invoked by :mod:`repoze.bfg` when the
+      developer explicitly raises a
+      ``repoze.bfg.exceptions.Forbidden`` exception from within
+      :term:`view` code or :term:`root factory` code, or when the the
+      :term:`view configuration` and :term:`authorization policy` found
+      for a request disallows a particular view invocation.
+      :mod:`repoze.bfg` provides a default implementation of a
+      forbidden view; it can be overridden.  See
+      :ref:`changing_the_forbidden_view`.
+
+   Thread Local
+      A thread-local variable is one which is essentially a global
+      variable in terms of how it is accessed and treated, however,
+      each `thread
+      <http://en.wikipedia.org/wiki/Thread_(computer_science)>` used by
+      the application may have a different value for this same "global"
+      variable.  :mod:`repoze.bfg` uses a small number of thread local
+      variables, as described in :ref:`threadlocals_chapter`. See also
+      the `threading.local documentation
+      <http://docs.python.org/library/threading.html#threading.local>`
+      for more information.
diff --git a/docs/index.rst b/docs/index.rst
index aef653803..1b39453e1 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -1,8 +1,8 @@
 .. _index:
 
-===========
-repoze.bfg
-===========
+========================================
+The repoze.bfg Web Application Framework
+========================================
 
 :mod:`repoze.bfg` is a Python web application framework.  It is
 inspired by :term:`Zope`, :term:`Pylons`, and :term:`Django`.  It uses
@@ -15,6 +15,15 @@ responses.
 <http://agendaless.com>`_ and other contributors.  It is licensed
 under a `BSD-like license <http://repoze.org/license.html>`_.
 
+Fore-Matter
+===========
+
+.. toctree::
+   :maxdepth: 1
+
+   copyright.rst
+   conventions.rst
+
 "What's New" Documents
 ======================
 
@@ -57,7 +66,6 @@ Narrative documentation in chapter form explaining how to use
    narr/resources
    narr/router
    narr/threadlocals
-   glossary
 
 API documentation
 =================
@@ -94,66 +102,26 @@ ZCML Directives
 Documentation for each :mod:`repoze.bfg` :term:`ZCML directive`.
 
 .. toctree::
-   :maxdepth: 2
+   :maxdepth: 1
 
    zcml
 
 Tutorials
 =========
 
-ZODB + traversal Wiki tutorial, demonstrating how to build a
-:term:`traversal` based application using :term:`ZODB` and
-:term:`authentication`.  Good for people with prior Zope experience
-(or no experience at all).
+Detailed tutorials explaining how to use :mod:`repoze.bfg` to build
+and various types of applications and how to deploy :mod:`repoze.bfg`
+applications to various platforms.
 
 .. toctree::
    :maxdepth: 2
 
    tutorials/bfgwiki/index.rst
-
-SQLAlchemy + url dispatch Wiki tutorial, demonstrating how to build a
-:term:`url dispatch` based application using :term:`SQLAlchemy` and
-:term:`authentication`.  Good for people with prior Pylons experience
-(or no experience at all).
-
-.. toctree::
-   :maxdepth: 2
-
    tutorials/bfgwiki2/index.rst
-
-:mod:`repoze.bfg` for Zope CMF Developers
-
-.. toctree::
-   :maxdepth: 2
-
    tutorials/cmf/index.rst
-
-:mod:`repoze.bfg` on Google's App Engine
-
-.. toctree::
-   :maxdepth: 2
-
    tutorials/gae/index.rst
-
-:mod:`repoze.bfg` under :term:`mod_wsgi`
-
-.. toctree::
-   :maxdepth: 2
-
    tutorials/modwsgi/index.rst
-
-Using ZODB's :term:`ZEO` with :mod:`repoze.bfg`
-
-.. toctree::
-   :maxdepth: 2
-
    tutorials/zeo/index.rst
-
-Using ZODB Sessions in :mod:`repoze.bfg`
-
-.. toctree::
-   :maxdepth: 2
-
    tutorials/zodbsessions/index.rst
 
 Detailed Change History
@@ -241,11 +209,9 @@ via Subversion, use this command::
 To find out how to become a contributor to :mod:`repoze.bfg`, please
 see the `contributor's page <http://repoze.org/contributing.html>`_.
 
-Indices and tables
+Index and Glossary
 ==================
 
+* :ref:`glossary`
 * :ref:`genindex`
-* :ref:`modindex`
 * :ref:`search`
-* :ref:`glossary`
-
diff --git a/docs/latexindex.rst b/docs/latexindex.rst
index 8f74f466c..9a3ab1c95 100644
--- a/docs/latexindex.rst
+++ b/docs/latexindex.rst
@@ -1,19 +1,18 @@
-.. _index:
+.. _latexindex:
 
-@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@
-The :mod:`repoze.bfg` Web Framework
-@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@
+@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@
+The :mod:`repoze.bfg` Web Application Framework
+@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@
 
-:mod:`repoze.bfg` is a Python web application framework.  It is
-inspired by :term:`Zope`, :term:`Pylons`, and :term:`Django`.  It uses
-various Zope-related libraries internally to do much of its work.
-:mod:`repoze.bfg` uses the WSGI protocol to handle request and
-responses.
+Fore-matter
+@@@@@@@@@@@
 
-:mod:`repoze.bfg` is developed as part of the `Repoze
-<http://repoze.org>`_ project by `Agendaless Consulting
-<http://agendaless.com>`_ and other contributors.  It is licensed
-under a `BSD-like license <http://repoze.org/license.html>`_.
+.. toctree::
+   :maxdepth: 1
+
+   copyright.rst
+   thanks.rst
+   conventions.rst
 
 Narrative Documentation
 @@@@@@@@@@@@@@@@@@@@@@@
@@ -49,68 +48,14 @@ Narrative Documentation
 Tutorials
 @@@@@@@@@
 
-ZODB + traversal Wiki Tutorial
-==============================
-
-Demonstrates how to build a :term:`traversal` based application using
-:term:`ZODB` and :term:`authentication`.  Good for people with prior
-Zope experience (or no experience at all).
-
 .. toctree::
    :maxdepth: 2
 
    tutorials/bfgwiki/index.rst
-
-SQLAlchemy + Url Dispatch Wiki Tutorial
-=======================================
-
-Demonstrates how to build a :term:`url dispatch` based application
-using :term:`SQLAlchemy` and :term:`authentication`.  Good for people
-with prior Pylons experience (or no experience at all).
-
-.. toctree::
-   :maxdepth: 2
-
    tutorials/bfgwiki2/index.rst
-
-:mod:`repoze.bfg` for Zope CMF Developers
-=========================================
-
-.. toctree::
-   :maxdepth: 2
-
-   tutorials/cmf/index.rst
-
-:mod:`repoze.bfg` on Google's App Engine
-========================================
-
-.. toctree::
-   :maxdepth: 2
-
    tutorials/gae/index.rst
-
-:mod:`repoze.bfg` under :term:`mod_wsgi`
-========================================
-
-.. toctree::
-   :maxdepth: 2
-
    tutorials/modwsgi/index.rst
-
-Using ZODB's :term:`ZEO` with :mod:`repoze.bfg`
-===============================================
-
-.. toctree::
-   :maxdepth: 2
-
    tutorials/zeo/index.rst
-
-Using ZODB Sessions in :mod:`repoze.bfg`
-========================================
-
-.. toctree::
-   :maxdepth: 2
-
    tutorials/zodbsessions/index.rst
 
 API documentation
@@ -141,23 +86,20 @@ API documentation
    api/wsgi
 
 ZCML Directives
-@@@@@@@@@@@@@@@
+@@@@@@@@@@@@@@@@
 
 .. toctree::
-   :maxdepth: 2
+   :maxdepth: 1
 
    zcml
 
-Glossary
-@@@@@@@@
+Glossary and Index
+@@@@@@@@@@@@@@@@@@
 
 .. toctree::
   :maxdepth: 1
 
   glossary
 
-Index
-@@@@@
-
 * :ref:`genindex`
 
diff --git a/docs/narr/configuration.rst b/docs/narr/configuration.rst
index 049be2ca3..73027e4c2 100644
--- a/docs/narr/configuration.rst
+++ b/docs/narr/configuration.rst
@@ -204,8 +204,8 @@ fragments, for example the ``/a/b/c`` portion of the URL
 traversal.
 
 .. note:: A useful analogy of how :mod:`repoze.bfg` :term:`traversal`
-  works is available within the section entitled
-  :ref:`traversal_behavior`.  You should probably go read it now.
+  works is available within the chapter section entitled
+  :ref:`traversal_behavior`.
 
 The results of a :term:`traversal` include a :term:`context` and a
 :term:`view name`.  The :term:`view name` is the *first* URL path
@@ -235,8 +235,6 @@ The object graph of our hello world application is very simple:
 there's exactly one object in our graph; the default :term:`root`
 object.
 
-Apologies for the digression; on with the tutorial.
-
 Relating Traversal to the Hello World Application
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
@@ -328,7 +326,6 @@ Beginning Configuration
 
 .. ignore-next-block
 .. code-block:: python
-   :linenos:
 
    config.begin()
 
@@ -449,7 +446,6 @@ Ending Configuration
 
 .. ignore-next-block
 .. code-block:: python
-   :linenos:
 
    config.end()
 
@@ -467,7 +463,6 @@ WSGI Application Creation
 
 .. ignore-next-block
 .. code-block:: python
-   :linenos:
 
    app = config.make_wsgi_app()
 
@@ -499,7 +494,6 @@ WSGI Application Serving
 
 .. ignore-next-block
 .. code-block:: python
-   :linenos:
 
    serve(app)
 
@@ -580,20 +574,20 @@ previously created ``helloworld.py``:
 .. code-block:: xml
    :linenos:
 
-    <configure xmlns="http://namespaces.repoze.org/bfg">
+   <configure xmlns="http://namespaces.repoze.org/bfg">
 
-      <include package="repoze.bfg.includes" />
+     <include package="repoze.bfg.includes" />
 
-      <view
-         view="helloworld.hello_world"
-         />
+     <view
+        view="helloworld.hello_world"
+        />
 
-      <view
-         name="goodbye"
-         view="helloworld.goodbye_world"
-         />
+     <view
+       name="goodbye"
+       view="helloworld.goodbye_world"
+       />
 
-    </configure>
+   </configure>
 
 This pair of files forms an application functionally equivalent to the
 application we created earlier.  Let's examine the differences between
@@ -641,7 +635,7 @@ which sits next to ``helloworld.py``.  Let's take a look at the
 .. code-block:: xml
    :linenos:
 
-    <configure xmlns="http://namespaces.repoze.org/bfg">
+   <configure xmlns="http://namespaces.repoze.org/bfg">
 
       <include package="repoze.bfg.includes" />
 
@@ -654,7 +648,7 @@ which sits next to ``helloworld.py``.  Let's take a look at the
          view="helloworld.goodbye_world"
          />
 
-    </configure>
+   </configure>
 
 The ``<configure>`` Tag
 ~~~~~~~~~~~~~~~~~~~~~~~
@@ -665,7 +659,9 @@ The ``configure.zcml`` ZCML file contains this bit of XML:
    :linenos:
 
     <configure xmlns="http://namespaces.repoze.org/bfg">
+
        <!-- other directives -->
+
     </configure>
 
 Because :term:`ZCML` is XML, and because XML requires a single root
@@ -683,9 +679,8 @@ The ``configure.zcml`` ZCML file contains this bit of XML within the
 ``<configure>`` root tag:
 
 .. code-block:: xml
-   :linenos:
 
-      <include package="repoze.bfg.includes" />
+   <include package="repoze.bfg.includes" />
 
 This singleton (self-closing) tag instructs ZCML to load a ZCML file
 from the Python package with the :term:`dotted Python name`
@@ -705,8 +700,8 @@ equivalently as:
 .. code-block:: xml
    :linenos:
 
-      <include package="repoze.bfg.includes" 
-               file="configure.zcml"/>
+   <include package="repoze.bfg.includes" 
+            file="configure.zcml"/>
 
 The ``<include>`` tag that includes the ZCML statements implied by the
 ``configure.zcml`` file from the Python package named
@@ -729,14 +724,14 @@ The ``configure.zcml`` ZCML file contains these bits of XML *after* the
 .. code-block:: xml
    :linenos:
 
-      <view
-         view="helloworld.hello_world"
-         />
+   <view
+     view="helloworld.hello_world"
+     />
 
-      <view
-         name="goodbye"
-         view="helloworld.goodbye_world"
-         />
+   <view
+     name="goodbye"
+     view="helloworld.goodbye_world"
+     />
 
 These ``<view>`` declaration tags direct :mod:`repoze.bfg` to create
 two :term:`view configuration` registrations.  The first ``<view>``
@@ -780,28 +775,28 @@ following ZCML orderings are completely equivalent:
   .. code-block:: xml
      :linenos:
 
-        <view
-           view="helloworld.hello_world"
-           />
+     <view
+       view="helloworld.hello_world"
+       />
 
-        <view
-           name="goodbye"
-           view="helloworld.goodbye_world"
-           />
+     <view
+       name="goodbye"
+       view="helloworld.goodbye_world"
+       />
 
 .. topic:: Goodbye Before Hello
 
   .. code-block:: xml
      :linenos:
 
-        <view
-           name="goodbye"
-           view="helloworld.goodbye_world"
-           />
+     <view
+       name="goodbye"
+       view="helloworld.goodbye_world"
+       />
 
-        <view
-           view="helloworld.hello_world"
-           />
+     <view
+       view="helloworld.hello_world"
+       />
 
 The ``<view>`` tag is an example of a :mod:`repoze.bfg` declaration
 tag.  Other such tags include ``<route>``, ``<scan>``, ``<notfound>``,
@@ -826,12 +821,12 @@ start.  For example, the following ZCML file has two conflicting
       <include package="repoze.bfg.includes" />
 
       <view
-         view="helloworld.hello_world"
-         />
+        view="helloworld.hello_world"
+        />
 
       <view
-         view="helloworld.hello_world"
-         />
+        view="helloworld.hello_world"
+        />
 
     </configure>
 
diff --git a/docs/narr/install.rst b/docs/narr/install.rst
index f23b3c819..e4eb284f9 100644
--- a/docs/narr/install.rst
+++ b/docs/narr/install.rst
@@ -7,11 +7,11 @@ Before You Install
 ------------------
 
 You will need `Python <http://python.org>`_ version 2.4 or better to
-run :mod:`repoze.bfg`.  It has been tested under Python 2.4.5, Python
-2.5.2 and Python 2.6.  Development of :mod:`repoze.bfg` is currently
-done primarily under Python 2.4 and Python 2.5.  :mod:`repoze.bfg`
-does *not* run under any version of Python before 2.4, and does *not*
-run under Python 3.X.
+run :mod:`repoze.bfg`.  It has been tested under Python 2.4.6, Python
+2.5.4 and Python 2.6.2, and Python 2.7a1.  Development of
+:mod:`repoze.bfg` is currently done primarily under Python 2.4 and
+Python 2.5.  :mod:`repoze.bfg` does *not* run under any version of
+Python before 2.4, and does *not* run under Python 3.X.
 
 .. sidebar:: You Don't Need A Compiler
 
@@ -21,24 +21,15 @@ run under Python 3.X.
    development tools installed on the target machine to install
    :mod:`repoze.bfg`.
 
-BFG is known to run properly on all popular Unix-like systems such as
-Linux, MacOS X, and FreeBSD.
+:mod:`repoze.bfg` is known to run properly on all popular Unix-like
+systems such as Linux, MacOS X, and FreeBSD.  :mod:`repoze.bfg` is
+also known to run on Windows systems.  However, none of its developers
+use Windows as a primary development platform.  It is also known to
+run on Google's App Engine.
 
-:mod:`repoze.bfg` is also known to run on Windows systems.  However,
-none of its developers use Windows as a primary development platform.
-Therefore, most of the platform-specific documentation (excepting this
-chapter) assumes you're using a UNIX system. If you're using a Windows
-system, you'll need to transliterate command lines in the
-documentation to their Windows equivalents.
-
-:mod:`repoze.bfg` is also known to run on Google's App Engine.
-
-It is not known whether :mod:`repoze.bfg` will or will not run under
-Jython or IronPython.
-
-.. note:: If you'd like to help make sure :mod:`repoze.bfg` keeps
-   running on your favorite alternate platform, we'd love to hear from
-   you.  Please contact us via the `repoze.dev maillist
+.. note:: If you'd like to help us make sure :mod:`repoze.bfg` runs on
+   your favorite alternate platform, we'd love to hear from you.
+   Please contact us via the `repoze.dev maillist
    <http://lists.repoze.org/listinfo/repoze-dev>`_ if you'd like to
    contribute.
 
@@ -61,9 +52,9 @@ For example, on an Ubuntu Linux system, to use the system package
 manager to install a Python 2.5 interpreter, use the following
 command:
 
-.. code-block:: bash
+.. code-block:: text
 
-  $ sudo apt-get install python2.5-dev
+   $ sudo apt-get install python2.5-dev
 
 Once these steps are performed, the Python interpreter will usually be
 invokable via ``python2.5`` from a shell prompt.
@@ -82,9 +73,9 @@ To compile software on your UNIX system, typically you need
 development tools.  Often these can be installed via the package
 manager.  For example, this works to do so on an Ubuntu Linux system:
 
-.. code-block:: bash
+.. code-block:: text
 
-  $ sudo apt-get install build-essential
+   $ sudo apt-get install build-essential
 
 On Mac OS X, installing XCode has much the same effect.
 
@@ -92,18 +83,19 @@ Once you've got development tools installed on your system, On the
 same system, to install a Python 2.5 interpreter from *source*, use
 the following commands:
 
-.. code-block:: bash
+.. code-block:: text
+   :linenos:
 
-  [chrism@vitaminf ~]$ cd ~
-  [chrism@vitaminf ~]$ mkdir tmp
-  [chrism@vitaminf ~]$ mkdir opt
-  [chrism@vitaminf ~]$ cd tmp
-  [chrism@vitaminf tmp]$ cd tmp
-  [chrism@vitaminf tmp]$ wget http://python.org/ftp/python/2.5.4/Python-2.5.4.tgz
-  [chrism@vitaminf tmp]$ tar xvzf Python-2.5.4.tgz
-  [chrism@vitaminf tmp]$ cd Python-2.5.4
-  [chrism@vitaminf Python-2.5.4]$ ./configure --prefix=$HOME/opt/Python-2.5.4
-  [chrism@vitaminf Python-2.5.4]$ make; make install
+   [chrism@vitaminf ~]$ cd ~
+   [chrism@vitaminf ~]$ mkdir tmp
+   [chrism@vitaminf ~]$ mkdir opt
+   [chrism@vitaminf ~]$ cd tmp
+   [chrism@vitaminf tmp]$ cd tmp
+   [chrism@vitaminf tmp]$ wget http://python.org/ftp/python/2.5.4/Python-2.5.4.tgz
+   [chrism@vitaminf tmp]$ tar xvzf Python-2.5.4.tgz
+   [chrism@vitaminf tmp]$ cd Python-2.5.4
+   [chrism@vitaminf Python-2.5.4]$ ./configure --prefix=$HOME/opt/Python-2.5.4
+   [chrism@vitaminf Python-2.5.4]$ make; make install
 
 Once these steps are performed, the Python interpreter will be
 invokable via ``$HOME/opt/Python-2.5.4/bin/python`` from a shell
@@ -135,13 +127,14 @@ ensure that :term:`setuptools` is installed.  Invoke ``import
 setuptools`` within the Python interpreter you'd like to run
 :mod:`repoze.bfg` under:
 
-.. code-block:: bash
+.. code-block:: text
+   :linenos:
 
-  [chrism@vitaminf bfg]$ python
-  Python 2.4.5 (#1, Aug 29 2008, 12:27:37) 
-  [GCC 4.0.1 (Apple Inc. build 5465)] on darwin
-  Type "help", "copyright", "credits" or "license" for more information.
-  >>> import setuptools
+   [chrism@vitaminf bfg]$ python
+   Python 2.4.5 (#1, Aug 29 2008, 12:27:37) 
+   [GCC 4.0.1 (Apple Inc. build 5465)] on darwin
+   Type "help", "copyright", "credits" or "license" for more information.
+   >>> import setuptools
 
 If ``import setuptools`` does not raise an ``ImportError``, it means
 that setuptools is already installed into your Python interpreter.  If
@@ -161,18 +154,18 @@ To install setuptools by hand, first download `ez_setup.py
 <http://peak.telecommunity.com/dist/ez_setup.py>`_ then invoke it
 using the Python interpreter you want to install setuptools into.
 
-.. code-block:: bash
+.. code-block:: text
 
-  $ sudo python ez_setup.py
+   $ sudo python ez_setup.py
 
 Once this command is invoked, setuptools should be installed on your
 system.  If the command fails due to permission errors, you may need
 to be the administrative user on your system to successfully invoke
 the script.  To remediate this, you may need to do:
 
-.. code-block:: bash
+.. code-block:: text
 
-  $ sudo python ez_setup.py
+   $ sudo python ez_setup.py
 
 Installing the ``virtualenv`` Package
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -182,17 +175,17 @@ Once you've got setuptools installed, you should install the
 into your setuptools-enabled Python interpreter, use the
 ``easy_install`` command.
 
-.. code-block:: bash
+.. code-block:: text
 
-  $ easy_install virtualenv
+   $ easy_install virtualenv
 
 This command should succeed, and tell you that the virtualenv package
 is now installed.  If it fails due to permission errors, you may need
 to install it as your system's administrative user.  For example:
 
-.. code-block:: bash
+.. code-block:: text
 
-  $ sudo easy_install virtualenv
+   $ sudo easy_install virtualenv
 
 Creating the Virtual Python Environment
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -201,7 +194,7 @@ Once the :term:`virtualenv` package is installed in your Python, you
 can actually create a virtual environment.  To do so, invoke the
 following:
 
-.. code-block:: bash
+.. code-block:: text
    :linenos:
 
    $ virtualenv --no-site-packages bfgenv
@@ -231,7 +224,7 @@ After you've got your ``bfgenv`` virtualenv installed, you may install
 :mod:`repoze.bfg` itself using the following commands from within the
 virtualenv (``bfgenv``) directory:
 
-.. code-block:: bash
+.. code-block:: text
    :linenos:
 
    $ bin/easy_install -i http://dist.repoze.org/bfg/1.1/simple repoze.bfg
@@ -250,33 +243,33 @@ Installing :mod:`repoze.bfg` on a Windows System
    pick the right download for Python 2.5 and install it using the
    same Python installation from the previous step.
 
-#. Install latest `setuptools` into the Python you
+#. Install latest :term:`setuptools` distribution into the Python you
    obtained/installed/found in the step above: download `ez_setup.py
    <http://peak.telecommunity.com/dist/ez_setup.py>`_ and run it using
    the ``python`` interpreter of your Python 2.5 installation using a
    command prompt:
 
-   .. code-block:: bat
+   .. code-block:: text
 
-    c:\> c:\Python25\python ez_setup.py
+      c:\> c:\Python25\python ez_setup.py
 
 #. Use that Python's `bin/easy_install` to install `virtualenv`:
 
-   .. code-block:: bat
+   .. code-block:: text
 
-    c:\> c:\Python25\Scripts\easy_install virtualenv
+      c:\> c:\Python25\Scripts\easy_install virtualenv
 
 #. Use that Python's virtualenv to make a workspace:
 
-   .. code-block:: bat
+   .. code-block:: text
 
-     c:\> c:\Python25\Scripts\virtualenv --no-site-packages bfgenv
+      c:\> c:\Python25\Scripts\virtualenv --no-site-packages bfgenv
 
 #. Switch to the ``bfgenv`` directory:
 
-   .. code-block:: bat
+   .. code-block:: text
 
-     c:\> cd bfgenv
+      c:\> cd bfgenv
 
 #. (Optional) Consider using ``bin\activate.bat`` to make your shell
    environment wired to use the virtualenv.
@@ -284,9 +277,9 @@ Installing :mod:`repoze.bfg` on a Windows System
 #. Use ``easy_install`` and point to the BFG "1.1" index to get BFG
    and its direct dependencies installed:
 
-   .. code-block:: bat
+   .. code-block:: text
 
-     c:\bfgenv> Scripts\easy_install -i http://dist.repoze.org/bfg/1.1/simple repoze.bfg
+      c:\bfgenv> Scripts\easy_install -i http://dist.repoze.org/bfg/1.1/simple repoze.bfg
 
 Installing :mod:`repoze.bfg` on Google App Engine
 -------------------------------------------------
diff --git a/docs/narr/introduction.rst b/docs/narr/introduction.rst
index fdc3ce77b..09b690a12 100644
--- a/docs/narr/introduction.rst
+++ b/docs/narr/introduction.rst
@@ -1,47 +1,95 @@
 :mod:`repoze.bfg` Introduction
 ==============================
 
-:mod:`repoze.bfg` is a Python web framework.  It is inspired by
-:term:`Zope`, :term:`Pylons`, and :term:`Django`.  :mod:`repoze.bfg`
-uses the :term:`WSGI` protocol to handle requests and responses.
-
-Similarities to Other Frameworks
---------------------------------
-
-.. sidebar:: Django's Authors Explain Why It Doesn't Use "MVC" Terminology
-
-  Django appears to be a MVC framework, but you call the Controller
-  the "view", and the View the "template". How come you don't use the
-  standard names?  Well, the standard names are debatable.
-
-  In our interpretation of MVC, the "view" describes the data that
-  gets presented to the user. It's not necessarily how the data looks,
-  but which data is presented. The view describes which data you see,
-  not how you see it. It's a subtle distinction.
-
-  So, in our case, a "view" is the Python callback function for a
-  particular URL, because that callback function describes which data
-  is presented.
-
-  Furthermore, it's sensible to separate content from presentation -
-  which is where templates come in. In Django, a "view" describes
-  which data is presented, but a view normally delegates to a
-  template, which describes how the data is presented.
+:mod:`repoze.bfg` is an open source Python web application framework.
+It is inspired by :term:`Zope`, :term:`Pylons`, and :term:`Django`.
+It uses the :term:`WSGI` protocol to handle requests and responses.
+
+:mod:`repoze.bfg` is written by Agendaless Consulting and a community
+of contributors.  It is developed primarily by people who come from
+the world of :term:`Zope` but for whom Zope as a web application
+development platform has lost some of its attraction.  Its authors
+also have experience developing applications using many other web
+frameworks.
 
-  Where does the "controller" fit in, then? In Django's case, it's
-  probably the framework itself: the machinery that sends a request to
-  the appropriate view, according to the Django URL configuration.
+The first release of :mod:`repoze.bfg` was made in July of 2008.
+Since its first release, it has undergone many improvements, and has
+gained features steadily.  Still, it strives to maintain the following
+attributes:
+
+Simplicity
+  :mod:`repoze.bfg` attempts to be a *"pay only for what you eat"*
+  framework in which you can be productive quickly with partial
+  knowledge.  We contrast this with *"pay up front for what anyone
+  might eventually want to eat"* frameworks, which tend to expect you
+  to understand a great many concepts and technologies fully before
+  you can be truly productive.  :mod:`repoze.bfg` doesn't force you to
+  use any particular technology to produce an application, and we try
+  to keep the core set of concepts you need to understand to a
+  minimum.
+
+Minimalism
+  :mod:`repoze.bfg` provides only the very basics: *URL to code
+  mapping*, *templating*, *security*, and *resources*.  There is not
+  much more to the framework than these pieces: you are expected to
+  provide the rest.
+
+Documentation
+  Because :mod:`repoze.bfg` is minimal, it's relatively easy to keep
+  its documentation up-to-date, which is helpful to bring new
+  developers up to speed.  It's our goal that nothing remain
+  undocumented about :mod:`repoze.bfg`.
+
+Speed
+  :mod:`repoze.bfg` is faster than many other popular Python web
+  frameworks for common tasks such as templating and simple response
+  generation.  The "hardware is cheap" mantra has its limits when
+  you're responsible for managing a great many machines: the fewer you
+  need, the less pain you'll have.
+
+Familiarity
+  As web developers, we've become accustomed to working in very
+  particular ways over the years.  This framework is a canonization of
+  practices that "fit our brains".
+
+Trustability
+  :mod:`repoze.bfg` is developed conservatively and tested
+  exhaustively.  *If it ain't tested, it's broke.* Every release of
+  :mod:`repoze.bfg` has 100% unit test converage.
+
+A Sense of Fun
+  Developing a :mod:`repoze.bfg` application should not feel foreign
+  or "enterprisey".  We like to keep things down-to-earth.
+
+Similarities to Other Web Frameworks
+------------------------------------
 
 :mod:`repoze.bfg` was inspired by :term:`Zope`, :term:`Pylons` and
 :term:`Django`.
 
+.. sidebar:: Django's Authors Explain Why It Doesn't Use "MVC" Terminology
+
+   Django appears to be a MVC framework, but you call the Controller
+   the "view", and the View the "template". How come you don't use the
+   standard names?  Well, the standard names are debatable.  In our
+   interpretation of MVC, the "view" describes the data that gets
+   presented to the user. It's not necessarily how the data looks, but
+   which data is presented. The view describes which data you see, not
+   how you see it. It's a subtle distinction.  So, in our case, a
+   "view" is the Python callback function for a particular URL,
+   because that callback function describes which data is presented.
+   Furthermore, it's sensible to separate content from presentation -
+   which is where templates come in. In Django, a "view" describes
+   which data is presented, but a view normally delegates to a
+   template, which describes how the data is presented.
+
 The :mod:`repoze.bfg` concept of :term:`traversal` is inspired by
 :term:`Zope`.  Additionally, :mod:`repoze.bfg` uses a :term:`Zope
 Component Architecture` :term:`application registry` internally, as
 does Zope 2, Zope 3, and :term:`Grok`.  Like Zope, :mod:`repoze.bfg`
 allows you to create applications which do not need to be forked or
-otherwise modified to be extended or overridden by a third party
-developer.
+otherwise modified in order to be extended or overridden by a third
+party developer.
 
 The :mod:`repoze.bfg` concept of :term:`URL dispatch` is inspired by
 the :term:`Routes` system used by :term:`Pylons`.  Like Pylons,
@@ -55,18 +103,18 @@ is dependent upon :term:`WSGI`.
 
 The Django docs explain that Django is not an "MVC"
 ("model/view/controller") framework in their `FAQ
-<http://www.djangoproject.com/documentation/faq/>`_.  The sidebar to
-the right has the Django authors' take on why "MVC" terminology
-doesn't match the web very well.  The concepts of :term:`view` and
-:term:`model` are used by :mod:`repoze.bfg` as they would be by
-Django.
+<http://www.djangoproject.com/documentation/faq/>`_.  The sidebar in
+this section describes the Django authors' take on why "MVC"
+terminology doesn't match the web very well.  The concepts of
+:term:`view` and :term:`model` are used by :mod:`repoze.bfg` as they
+would be by Django.
 
 The skeleton code generator of :mod:`repoze.bfg` generates a directory
 layout very similar to the directory layout suggested by the `Django
 Book <http://www.djangobook.com/>`_ .  
 
-Differences from Other Frameworks
----------------------------------
+Differences from Other Web Frameworks
+-------------------------------------
 
 Like :term:`Zope`, the :mod:`repoze.bfg` framework imposes more
 `control inversion <http://plope.com/control_inversion>`_ upon
@@ -121,152 +169,3 @@ relational database.  :mod:`repoze.bfg` makes no such assumption; it
 allows you to use a relational database but doesn't encourage or
 discourage an application developer about such a decision.
 
-Why?
-----
-
-*Familiarity*: As web developers, we've become accustomed to working
-in very particular ways over the years.  This framework is a
-canonization of practices that "fit our brains".
-
-*Simplicity*: :mod:`repoze.bfg` attempts to be a *"pay only for what
-you eat"* framework in which you can be productive quickly with
-partial knowledge.  We contrast this with *"pay up front for what
-anyone might eventually want to eat"* frameworks, which tend to expect
-you to understand a great many concepts and technologies fully before
-you can be truly productive.  :mod:`repoze.bfg` doesn't force you to
-use any particular technology to produce an application, and we try to
-keep the core set of concepts you need to understand to a minimum.
-
-*Minimalism*: :mod:`repoze.bfg` provides only the very basics: *URL to
-code mapping*, *templating*, *security*, and *resources*.  There is
-not much more to the framework than these pieces: you are expected to
-provide the rest.
-
-*Documentation*: Because :mod:`repoze.bfg` is minimal, it's relatively
-easy to keep its documentation up-to-date, which is helpful to bring
-new developers up to speed.  It's our goal that nothing remain
-undocumented about :mod:`repoze.bfg`.
-
-*Speed*: :mod:`repoze.bfg` is faster than many other popular Python
-web frameworks for common tasks such as templating and simple response
-generation.  The "hardware is cheap" mantra has its limits when you're
-responsible for managing a great many machines: the fewer you need,
-the less pain you'll have.
-
-It's Tested
------------
-
-*If it ain't tested, it's broke.* We strive to test :mod:`repoze.bfg`
-completely.  Below a run of the ``nosetests`` command configured to
-show code coverage information run against the :mod:`repoze.bfg`
-trunk shortly after the 1.2a1 release.
-
-.. code-block:: bash
-   :linenos:
-
-    [chrism@snowpro trunk]$ python setup.py nosetests --with-coverage
-    running nosetests
-    running egg_info
-    writing requirements to repoze.bfg.egg-info/requires.txt
-    writing repoze.bfg.egg-info/PKG-INFO
-    writing namespace_packages to repoze.bfg.egg-info/namespace_packages.txt
-    writing top-level names to repoze.bfg.egg-info/top_level.txt
-    writing dependency_links to repoze.bfg.egg-info/dependency_links.txt
-    writing entry points to repoze.bfg.egg-info/entry_points.txt
-    writing manifest file 'repoze.bfg.egg-info/SOURCES.txt'
-    running build_ext
-    ...........................................................................
-    ...........................................................................
-    ...........................................................................
-    ...........................................................................
-    ...........................................................................
-    ...........................................................................
-    ...........................................................................
-    ...........................................................................
-    ...........................................................................
-    ...........................................................................
-    .................................................
-    Name                                                   Stmts   Exec  Cover   Missing
-    ------------------------------------------------------------------------------------
-    repoze.bfg                                                 0      0   100%   
-    repoze.bfg.authentication                                198    198   100%   
-    repoze.bfg.authorization                                  51     51   100%   
-    repoze.bfg.chameleon_text                                 46     46   100%   
-    repoze.bfg.chameleon_zpt                                  39     39   100%   
-    repoze.bfg.compat                                          8      8   100%   
-    repoze.bfg.compat.pkgutil_26                               0      0   100%   
-    repoze.bfg.configuration                                 605    605   100%   
-    repoze.bfg.encode                                         49     49   100%   
-    repoze.bfg.events                                         22     22   100%   
-    repoze.bfg.exceptions                                      2      2   100%   
-    repoze.bfg.includes                                        1      1   100%   
-    repoze.bfg.interfaces                                     66     66   100%   
-    repoze.bfg.location                                       14     14   100%   
-    repoze.bfg.log                                             9      9   100%   
-    repoze.bfg.paster                                         58     58   100%   
-    repoze.bfg.path                                           38     38   100%   
-    repoze.bfg.registry                                       15     15   100%   
-    repoze.bfg.renderers                                      47     47   100%   
-    repoze.bfg.request                                        57     57   100%   
-    repoze.bfg.resource                                      127    127   100%   
-    repoze.bfg.router                                        109    109   100%   
-    repoze.bfg.scripting                                      12     12   100%   
-    repoze.bfg.security                                      123    123   100%   
-    repoze.bfg.settings                                       38     38   100%   
-    repoze.bfg.static                                         53     53   100%   
-    repoze.bfg.testing                                       282    282   100%   
-    repoze.bfg.tests                                           1      1   100%   
-    repoze.bfg.tests.fixtureapp                                1      1   100%   
-    repoze.bfg.tests.fixtureapp.models                         4      4   100%   
-    repoze.bfg.tests.fixtureapp.subpackage                     1      1   100%   
-    repoze.bfg.tests.fixtureapp.views                          4      4   100%   
-    repoze.bfg.tests.grokkedapp                               53     53   100%   
-    repoze.bfg.tests.grokkedapp.another                       37     37   100%   
-    repoze.bfg.tests.grokkedapp.subpackage                     3      3   100%   
-    repoze.bfg.tests.grokkedapp.subpackage.notinit             3      3   100%   
-    repoze.bfg.tests.grokkedapp.subpackage.subsubpackage       3      3   100%   
-    repoze.bfg.tests.routesapp                                 1      1   100%   
-    repoze.bfg.tests.routesapp.views                           4      4   100%   
-    repoze.bfg.tests.test_authentication                     487    487   100%   
-    repoze.bfg.tests.test_authorization                      132    132   100%   
-    repoze.bfg.tests.test_chameleon_text                     165    165   100%   
-    repoze.bfg.tests.test_chameleon_zpt                      150    150   100%   
-    repoze.bfg.tests.test_compat                               7      7   100%   
-    repoze.bfg.tests.test_configuration                     2277   2277   100%   
-    repoze.bfg.tests.test_encode                              47     47   100%   
-    repoze.bfg.tests.test_events                              80     80   100%   
-    repoze.bfg.tests.test_integration                         64     64   100%   
-    repoze.bfg.tests.test_location                            34     34   100%   
-    repoze.bfg.tests.test_log                                 11     11   100%   
-    repoze.bfg.tests.test_paster                             111    111   100%   
-    repoze.bfg.tests.test_path                               122    122   100%   
-    repoze.bfg.tests.test_registry                            34     34   100%   
-    repoze.bfg.tests.test_renderers                          150    150   100%   
-    repoze.bfg.tests.test_request                            138    138   100%   
-    repoze.bfg.tests.test_resource                           352    352   100%   
-    repoze.bfg.tests.test_router                             494    494   100%   
-    repoze.bfg.tests.test_scripting                           47     47   100%   
-    repoze.bfg.tests.test_security                           315    315   100%   
-    repoze.bfg.tests.test_settings                           138    138   100%   
-    repoze.bfg.tests.test_static                             126    126   100%   
-    repoze.bfg.tests.test_testing                            562    562   100%   
-    repoze.bfg.tests.test_threadlocal                         74     74   100%   
-    repoze.bfg.tests.test_traversal                          926    926   100%   
-    repoze.bfg.tests.test_url                                224    224   100%   
-    repoze.bfg.tests.test_urldispatch                        192    192   100%   
-    repoze.bfg.tests.test_view                               407    407   100%   
-    repoze.bfg.tests.test_wsgi                                99     99   100%   
-    repoze.bfg.tests.test_zcml                               781    781   100%   
-    repoze.bfg.threadlocal                                    26     26   100%   
-    repoze.bfg.traversal                                     187    187   100%   
-    repoze.bfg.url                                            76     76   100%   
-    repoze.bfg.urldispatch                                   101    101   100%   
-    repoze.bfg.view                                          120    120   100%   
-    repoze.bfg.wsgi                                           26     26   100%   
-    repoze.bfg.zcml                                          299    299   100%   
-    ------------------------------------------------------------------------------------
-    TOTAL                                                  11765  11765   100%   
-    ----------------------------------------------------------------------
-    Ran 799 tests in 2.080s
-
-    OK
diff --git a/docs/narr/router.rst b/docs/narr/router.rst
index 09b931627..48a068626 100644
--- a/docs/narr/router.rst
+++ b/docs/narr/router.rst
@@ -1,9 +1,7 @@
 .. _router_chapter:
 
-How :mod:`repoze.bfg` Processes A Request
-=========================================
-
-.. image:: router.png
+Request Processing
+==================
 
 Once a :mod:`repoze.bfg` application is up and running, it is ready to
 accept requests and return responses.
@@ -93,9 +91,12 @@ processing?
    attributes are used to generate a WSGI response.  The response is
    sent back to the upstream WSGI server.
 
+.. image:: router.png
+
 This is a very high-level overview that leaves out various details.
 For more detail about subsystems invoked by the BFG router (like
 traversal, URL dispatch, views, and events), see
 :ref:`url_mapping_chapter`, :ref:`traversal_chapter`,
 :ref:`urldispatch_chapter`, :ref:`views_chapter`, and
 :ref:`events_chapter`.
+
diff --git a/docs/thanks.rst b/docs/thanks.rst
new file mode 100644
index 000000000..6270e8a36
--- /dev/null
+++ b/docs/thanks.rst
@@ -0,0 +1,17 @@
+Author Thanks
+=============
+
+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.
+
+Special thanks to Guido van Rossum and Tim Peters for Python.
+
+Special thanks also to Tricia for putting up with me.
+
diff --git a/docs/zcml.rst b/docs/zcml.rst
index efca070bc..78f4fc344 100644
--- a/docs/zcml.rst
+++ b/docs/zcml.rst
@@ -1,12 +1,12 @@
 .. _zcml_directives:
 
 ZCML Directives
-===============
+----------------
 
 :term:`ZCML` is an XML dialect that may be used by a :mod:`repoze.bfg`
 application to perform :term:`declarative configuration`.  Each
 :term:`ZCML directive` supplied by :mod:`repoze.bfg` is documented
-below.
+in this chapter.
 
 .. _configure_directive: