Latex rendering.

Documentation licensing.

4 files changed, 192 insertions, 304 deletions

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`.
+