Commit from paper.

4 files changed, 99 insertions, 92 deletions

diff --git a/docs/authorintro.rst b/docs/authorintro.rst
index 101130358..98ec24d92 100644
--- a/docs/authorintro.rst
+++ b/docs/authorintro.rst
@@ -42,21 +42,27 @@ such as HTTP, and you can usually skip such descriptions without
 becoming "blocked," although you may lack some fundamental
 understanding of how it works "under the hood" as a result.
 
+.. index::
+   single: repoze.zope2
+   single: Zope 3
+   single: Zope 2
+
 The Genesis of :mod:`repoze.bfg`
 --------------------------------
 
 I wrote :mod:`repoze.bfg` after many years of writing applications
 using :term:`Zope`.  Zope provided me with a lot of mileage: it wasn't
-until almost a decade of succesfully creating applications using Zope
+until almost a decade of succesfully creating applications using it
 that I decided to write a different web framework.  Although
 :mod:`repoze.bfg` takes inspiration from a variety of web frameworks,
 it owes more of its core design to Zope than any other.
 
-The "Repoze" brand existed before :mod:`repoze.bfg`.  One of the first
-packages developed as part of the Repoze brand was a package named
-:mod:`repoze.zope2`.  This was a package that allowed Zope 2
-applications to run under a :term:`WSGI` server without modification.
-Zope 2 did not have reasonable WSGI support at the time.
+The Repoze "brand" existed before :mod:`repoze.bfg` was created.  One
+of the first packages developed as part of the Repoze brand was a
+package named :mod:`repoze.zope2`.  This was a package that allowed
+Zope 2 applications to run under a :term:`WSGI` server without
+modification.  Zope 2 did not have reasonable WSGI support at the
+time.
 
 During the development of the :mod:`repoze.zope2` package, I found
 that replicating the Zope 2 "publisher" -- the machinery that maps
@@ -76,12 +82,11 @@ frameworks offer much along the axes of traversal, contextual
 declarative security, or application extensibility; these were
 features I had become accustomed to as a Zope developer.
 
-I decided that in the long term, creating a simpler, legacy-free
-framework that retained features I had become accustomed to when
-developing Zope applications was a more reasonable idea than
-continuing to use any Zope publisher or living with the limitations
-and unfamiliarities of a different framework.  The result is what is
-now :mod:`repoze.bfg`.
+I decided that in the long term, creating a simpler framework that
+retained features I had become accustomed to when developing Zope
+applications was a more reasonable idea than continuing to use any
+Zope publisher or living with the limitations and unfamiliarities of a
+different framework.  The result is what is now :mod:`repoze.bfg`.
 
 It is immodest to say so, but I believe :mod:`repoze.bfg` has turned
 out to be the very best Python web framework available today, bar
diff --git a/docs/copyright.rst b/docs/copyright.rst
index 59fe2e013..e3b8e00f9 100644
--- a/docs/copyright.rst
+++ b/docs/copyright.rst
@@ -9,6 +9,8 @@ by Chris McDonough
 
 Copyright |copy| 2008-2010, Agendaless Consulting.
 
+ISBN-10: 0615345379
+
 ISBN-13: 978-0-615-34537-6
 
 First print publishing: 2010
diff --git a/docs/narr/install.rst b/docs/narr/install.rst
index 1028e7d72..87df63882 100644
--- a/docs/narr/install.rst
+++ b/docs/narr/install.rst
@@ -14,12 +14,12 @@ run :mod:`repoze.bfg`.
 
 .. sidebar:: Python Versions
 
-    :mod:`repoze.bfg` has been tested under Python 2.4.6, Python 2.5.4
-    and Python 2.6.2, and Python 2.7a1.  To ensure backwards
-    compatibility, 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.
+    As of this writing, :mod:`repoze.bfg` has been tested under Python
+    2.4.6, Python 2.5.4 and Python 2.6.2, and Python 2.7a1.  To ensure
+    backwards compatibility, 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 yet run under Python 3.X.
 
 :mod:`repoze.bfg` is known to run on all popular Unix-like systems
 such as Linux, MacOS X, and FreeBSD as well as on Windows platforms.
@@ -45,15 +45,15 @@ system's package manager is slightly different, but the "flavor" of
 them is usually the same.
 
 For example, on an Ubuntu Linux system, to use the system package
-manager to install a Python 2.5 interpreter, use the following
+manager to install a Python 2.6 interpreter, use the following
 command:
 
 .. code-block:: text
 
-   $ sudo apt-get install python2.5-dev
+   $ sudo apt-get install python2.6-dev
 
 Once these steps are performed, the Python interpreter will usually be
-invokable via ``python2.5`` from a shell prompt.
+invokable via ``python2.6`` from a shell prompt.
 
 Source Compile Method
 +++++++++++++++++++++
@@ -73,10 +73,11 @@ manager.  For example, this works to do so on an Ubuntu Linux system:
 
    $ sudo apt-get install build-essential
 
-On Mac OS X, installing XCode has much the same effect.
+On Mac OS X, installing `XCode
+<http://developer.apple.com/tools/xcode/>`_ has much the same effect.
 
 Once you've got development tools installed on your system, On the
-same system, to install a Python 2.5 interpreter from *source*, use
+same system, to install a Python 2.6 interpreter from *source*, use
 the following commands:
 
 .. code-block:: text
@@ -87,23 +88,23 @@ the following commands:
    [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
+          http://www.python.org/ftp/python/2.6.4/Python-2.6.4.tgz
+   [chrism@vitaminf tmp]$ tar xvzf Python-2.6.4.tgz
+   [chrism@vitaminf tmp]$ cd Python-2.6.4
+   [chrism@vitaminf Python-2.6.4]$ ./configure \
+           --prefix=$HOME/opt/Python-2.6.4
+   [chrism@vitaminf Python-2.6.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
+invokable via ``$HOME/opt/Python-2.6.4/bin/python`` from a shell
 prompt.
 
 If You Don't Yet Have A Python Interpreter (Windows)
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 If your Windows system doesn't have a Python interpreter, you'll need
-to install it by downloading a Python 2.4, 2.5 or 2.6-series
-interpreter executable from `python.org's download section
+to install it by downloading a Python 2.6-series interpreter
+executable from `python.org's download section
 <http://python.org/download/>`_ (the files labeled "Windows
 Installer").  Once you've downloaded it, double click on the
 executable and accept the defaults during the installation process.
@@ -118,14 +119,14 @@ extensions <http://sourceforge.net/projects/pywin32/files/>`_.
 Installing :mod:`repoze.bfg` on a UNIX System
 ---------------------------------------------
 
-It is best practice to install :mod:`repoze.bfg` into a
-:term:`virtualenv` in order to obtain isolation from any "system"
-packages you've got installed in your Python version. Using a
-virtualenv will also prevent :mod:`repoze.bfg` from globally
-installing versions of packages that are not compatible with your
-system Python.
+It is best practice to install :mod:`repoze.bfg` into a "virtual"
+Python environment in order to obtain isolation from any "system"
+packages you've got installed in your Python version.  This can be
+done by using the :term:`virtualenv` package.  Using a virtualenv will
+also prevent :mod:`repoze.bfg` from globally installing versions of
+packages that are not compatible with your system Python.
 
-To set up a virtualenv to install :mod:`repoze.bfg` within, first
+To set up a virtualenv in which to install :mod:`repoze.bfg`, first
 ensure that :term:`setuptools` is installed.  Invoke ``import
 setuptools`` within the Python interpreter you'd like to run
 :mod:`repoze.bfg` under:
@@ -138,14 +139,16 @@ setuptools`` within the Python interpreter you'd like to run
    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
-``import setuptools`` fails, you will need to install setuptools
-manually.
+If running ``import setuptools`` does not raise an ``ImportError``, it
+means that setuptools is already installed into your Python
+interpreter.  If ``import setuptools`` fails, you will need to install
+setuptools manually.  Note that above we're using a Python 2.4-series
+interpreter on Mac OS X; your output may differ if you're using a
+later Python version or a different platform.
 
 If you are using a "system" Python (one installed by your OS
 distributor or a 3rd-party packager such as Fink or MacPorts), you can
-usually install a setuptools package using your system's package
+usually install the setuptools package by using your system's package
 manager.  If you cannot do this, or if you're using a self-installed
 version of Python, you will need to install setuptools "by hand".
 Installing setuptools "by hand" is always a reasonable thing to do,
@@ -154,7 +157,8 @@ setuptools for installation.
 
 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.
+using the Python interpreter into which you want to install
+setuptools.
 
 .. code-block:: text
 
@@ -247,35 +251,35 @@ downloads and installs a number of dependencies.
 Installing :mod:`repoze.bfg` on a Windows System
 -------------------------------------------------
 
-#. Install, or find `Python 2.5
-   <http://python.org/download/releases/2.5.4/>`_ for your system.
+#. Install, or find `Python 2.6
+   <http://python.org/download/releases/2.6.4/>`_ for your system.
 
 #. Install the `Python for Windows extensions
    <http://sourceforge.net/projects/pywin32/files/>`_.  Make sure to
-   pick the right download for Python 2.5 and install it using the
+   pick the right download for Python 2.6 and install it using the
    same Python installation from the previous step.
 
 #. 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
+   the ``python`` interpreter of your Python 2.6 installation using a
    command prompt:
 
    .. code-block:: text
 
-      c:\> c:\Python25\python ez_setup.py
+      c:\> c:\Python26\python ez_setup.py
 
 #. Use that Python's `bin/easy_install` to install `virtualenv`:
 
    .. code-block:: text
 
-      c:\> c:\Python25\Scripts\easy_install virtualenv
+      c:\> c:\Python26\Scripts\easy_install virtualenv
 
 #. Use that Python's virtualenv to make a workspace:
 
    .. code-block:: text
 
-      c:\> c:\Python25\Scripts\virtualenv --no-site-packages bfgenv
+      c:\> c:\Python26\Scripts\virtualenv --no-site-packages bfgenv
 
 #. Switch to the ``bfgenv`` directory:
 
@@ -286,8 +290,8 @@ Installing :mod:`repoze.bfg` on a Windows System
 #. (Optional) Consider using ``bin\activate.bat`` to make your shell
    environment wired to use the virtualenv.
 
-#. Use ``easy_install`` and point to the :mod:`repoze.bfg` "current"
-   index to get BFG and its direct dependencies installed:
+#. Use ``easy_install`` pointed at the "current" index to get
+   :mod:`repoze.bfg` and its direct dependencies installed:
 
    .. code-block:: text
 
@@ -318,7 +322,7 @@ One caveat exists to using :mod:`repoze.bfg` under Jython: the
 :term:`Chameleon` templating engine, which is the default templating
 engine for :mod:`repoze.bfg` does not work on non-CPython platforms.
 
-The :mod:`repoze.bfg.jinja2` distribution provides templating for
+The ``repoze.bfg.jinja2`` distribution provides templating for
 :mod:`repoze.bfg` using the :term:`Jinja2` templating system.  You may
 install it like so using the ``easy_install`` command for Jython:
 
diff --git a/docs/narr/introduction.rst b/docs/narr/introduction.rst
index de1ef8b92..dfb841117 100644
--- a/docs/narr/introduction.rst
+++ b/docs/narr/introduction.rst
@@ -39,17 +39,17 @@ applications.
    facilities that fits your application requirements.
 
 The first release of :mod:`repoze.bfg` was made in July of 2008.
-Since its first release, we've tried to ensure that BFG maintains the
+Since its first release, we've tried to ensure that it maintains the
 following attributes:
 
 Simplicity
   :mod:`repoze.bfg` attempts to be a *"pay only for what you eat"*
   framework which delivers results even if you have only partial
-  knowledge.  Other frameworks may 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.
+  knowledge.  Other frameworks may expect you to understand 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.
 
 A Sense of Fun
   Developing a :mod:`repoze.bfg` application should not feel
@@ -94,6 +94,28 @@ This book usually refers to the framework by its full package name,
 just "BFG" (the "repoze-dot" dropped) in conversation.
 
 .. index::
+   single: Repoze
+   single: Agendaless Consulting
+   pair: repoze; namespace package
+
+What Is Repoze?
+---------------
+
+:mod:`repoze.bfg` is a member of the collection of software published
+under the :term:`Repoze` "brand".  :term:`Repoze` software is written
+by :term:`Agendaless Consulting` and a community of contributors.  The
+`Repoze website <http://repoze.org>`_ describes the Repoze brand in
+more detail.  Software authored that uses this brand is usually placed
+into a ``repoze`` namespace package.  This namespace consists of a
+number of packages.  Each package is useful in isolation.  The
+``repoze`` namespace package represents that the software is written
+by a notional community rather than representing a collection of
+software that is meant to be used as a unit.  For example, even though
+``repoze.bfg`` shares the same namespace as another popular Repoze
+package, ``repoze.who``, these two packages are otherwise unrelated
+and can be used separately.
+
+.. index::
    single: repoze.bfg and other frameworks
    single: Zope
    single: Pylons
@@ -148,10 +170,11 @@ Like :term:`Pylons`, but unlike :term:`Zope`, a :mod:`repoze.bfg`
 application developer may use completely imperative code to perform
 common framework configuration tasks such as adding a view or a route.
 In Zope, :term:`ZCML` is typically required for similar purposes.  In
-:term:`Grok`, :term:`decorator` objects and class-level declarations
-are used for this purpose.  :mod:`repoze.bfg` *supports* :term:`ZCML`
-and supports decorator-based configuration, but does not require
-either. See :ref:`configuration_narr` for more information.
+:term:`Grok`, a Zope-based web framework, :term:`decorator` objects
+and class-level declarations are used for this purpose.
+:mod:`repoze.bfg` *supports* :term:`ZCML` and supports decorator-based
+configuration, but does not require either. See
+:ref:`configuration_narr` for more information.
 
 Also unlike :term:`Zope` and unlike other "full-stack" frameworks such
 as :term:`Django`, :mod:`repoze.bfg` makes no assumptions about which
@@ -163,30 +186,3 @@ you want to store your application's data in a relational database.
 :mod:`repoze.bfg` makes no such assumption; it allows you to use a
 relational database but doesn't encourage or discourage the decision.
 
-.. index::
-   single: Repoze
-   single: Agendaless Consulting
-   pair: repoze; namespace package
-
-What Is Repoze?
----------------
-
-:mod:`repoze.bfg` is a member of the collection of software published
-under the :term:`Repoze` "brand".  :term:`Repoze` software is written
-by :term:`Agendaless Consulting` and a community of contributors.  The
-`Repoze website <http://repoze.org>`_ describes the Repoze brand in
-more detail.  Software authored that uses this brand is usually placed
-into a ``repoze`` namespace package.  This namespace consists of a
-number of packages.  Each package is useful in isolation.  The
-``repoze`` namespace package represents that the software is written
-by a notional community rather than representing a collection of
-software that is meant to be used as a unit.  For example, even though
-``repoze.bfg`` shares the same namespace as another popular Repoze
-package, ``repoze.who``, these two packages are otherwise unrelated
-and can be used separately.
-
-.. index::
-   single: repoze.zope2
-   single: Zope 3
-   single: Zope 2
-