De-stiltify.

2 files changed, 71 insertions, 51 deletions

diff --git a/docs/narr/configuration.rst b/docs/narr/configuration.rst
index 0584e8671..edb3950e3 100644
--- a/docs/narr/configuration.rst
+++ b/docs/narr/configuration.rst
@@ -1,56 +1,59 @@
+.. index::
+   single: frameworks vs. libraries
+   single: framework
+
 .. _configuration_narr:
 
 Creating Your First :mod:`repoze.bfg` Application
 =================================================
 
-The majority of the logic in any web application is completely
+Most of the logic in a web application is completely
 application-specific.  For example, the content of a web page served
 by one web application might be a representation of the contents of an
 accounting ledger, while the content of of a web page served by
-another might be a listing of songs.  These applications obviously
-will not serve the same set of customers.  However, both the
+another might be a listing of songs.  These applications probably
+won't serve the same set of customers.  However, both the
 ledger-serving and song-serving applications can be written using
 :mod:`repoze.bfg`, because :mod:`repoze.bfg` is a very general
 *framework* which can be used to create all kinds of web applications.
+As a framework, the primary job of :mod:`repoze.bfg` is to make it
+easier for a developer to create an arbitrary web application.
 
 .. sidebar:: Frameworks vs. Libraries
 
    A *framework* differs from a *library* in one very important way:
    library code is always *called* by code that you write, while a
    framework always *calls* code that you write.  Using a set of
-   libraries to create an application is often initially easier than
-   using a framework to create an application, because the developer
-   can choose to cede control to library code he has not authored
-   selectively. When using a framework, the developer is typically
-   required to cede a greater portion of control to code he has not
-   authored: code that resides in the framework itself.  You needn't
-   use a framework at all to create a web application using Python.  A
-   rich set of libraries already exists for the platform.  In
-   practice, however, using an existing framework to create an
-   application is often more practical than rolling your own via a set
-   of libraries if the framework provides a set of facilities and
-   assumptions that fit your application requirements.
-
-As a framework, the primary job of :mod:`repoze.bfg` is to make it
-easier for a developer to create an arbitrary web application.  Each
-deployment of an application written using :mod:`repoze.bfg` implies a
-specific *configuration* of the framework itself.  For example, a
-song-serving application might plug code into the framework that
-manages songs, while the ledger- serving application might plug in
-code that manages accounting information.  :mod:`repoze.bfg` refers to
-the way in which code is plugged in to it for a specific deployment as
-"configuration".
+   libraries to create an application is usually easier than using a
+   framework initially, because you can choose to cede control to
+   library code you have not authored very selectively. But when you
+   use a framework, you are required to cede a greater portion of
+   control to code you have not authored: code that resides in the
+   framework itself.  You needn't use a framework at all to create a
+   web application using Python.  A rich set of libraries already
+   exists for the platform.  In practice, however, using a framework
+   to create an application is often more practical than rolling your
+   own via a set of libraries if the framework provides a set of
+   facilities that fits your application requirements.
+
+Each deployment of an application written using :mod:`repoze.bfg`
+implies a specific *configuration* of the framework itself.  For
+example, a song-serving application might plug code into the framework
+that manages songs, while the ledger- serving application might plug
+in code that manages accounting information.  :mod:`repoze.bfg` refers
+to the way in which code is plugged in to it for a specific
+application as "configuration".
 
 Most people understand "configuration" as coarse knobs that inform the
 high-level operation of a specific application deployment.  For
 instance, it's easy to think of the values implied by a ``.ini`` file
 which is parsed at application startup time as "configuration".
-:mod:`repoze.bfg` extends this pattern all the way out to application
-development, using the term "configuration" to express standardized
-methods which can be used to plug code into a deployment of the
-framework itself.  When you plug code into the :mod:`repoze.bfg`
-framework, you are indeed "configuring" :mod:`repoze.bfg` for the
-purpose of creating a particular application deployment.
+:mod:`repoze.bfg` extends this pattern out to application development,
+using the term "configuration" to express standardized ways that code
+gets plugged into a deployment of the framework itself.  When you plug
+code into the :mod:`repoze.bfg` framework, you are "configuring"
+:mod:`repoze.bfg` for the purpose of creating a particular application
+deployment.
 
 There are a number of different mechanisms you may use to configure
 :mod:`repoze.bfg` to create an application: *imperative* configuration
@@ -67,7 +70,7 @@ Hello World, Configured Imperatively
 
 Experienced Python programmers may find the "imperative" configuration
 mechanism fits the way they already do things. This is the
-configuration mode in which developers cede the least amount of
+configuration mode in which a developer cedes the least amount of
 control to the framework.  It is often the easiest configuration mode
 to understand.
 
diff --git a/docs/narr/introduction.rst b/docs/narr/introduction.rst
index 497b09b40..898b67655 100644
--- a/docs/narr/introduction.rst
+++ b/docs/narr/introduction.rst
@@ -1,3 +1,9 @@
+.. index::
+   single: Agendaless Consulting
+   single: Pylons
+   single: Django
+   single: Zope
+
 :mod:`repoze.bfg` Introduction
 ==============================
 
@@ -5,12 +11,10 @@
 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.
+:mod:`repoze.bfg` is written by :term:`Agendaless Consulting` and a
+community of contributors.  It is developed primarily by people who
+come from the world of :term:`Zope`.  Its authors also have experience
+developing applications using many other web frameworks.
 
 The first release of :mod:`repoze.bfg` was made in July of 2008.
 Since its first release, it has undergone many improvements, and has
@@ -19,14 +23,16 @@ 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.
+  framework in which you can be productive quickly with only partial
+  knowledge.  Some other frameworks 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.
+
+A Sense of Fun
+  Developing a :mod:`repoze.bfg` application should not feel
+  "enterprisey".  We like to keep things down-to-earth.
 
 Minimalism
   :mod:`repoze.bfg` provides only the very basics: *URL to code
@@ -57,12 +63,13 @@ Trustability
   exhaustively.  *If it ain't tested, it's broke.* Every release of
   :mod:`repoze.bfg` has 100% statement coverage via unit tests.
 
-A Sense of Fun
-  Developing a :mod:`repoze.bfg` application should not feel foreign
-  or "enterprisey".  We like to keep things down-to-earth.
-
 .. index::
    single: similarities to other frameworks
+   single: Grok
+   single: Zope
+   single: Pylons
+   single: Django
+   single: MVC
 
 Similarities to Other Web Frameworks
 ------------------------------------
@@ -114,10 +121,15 @@ 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/>`_ .  
+Book <http://www.djangobook.com/>`_ .
 
 .. index::
    single: differences from other frameworks
+   single: Grok
+   single: Zope
+   single: Pylons
+   single: Django
+   single: control inversion
 
 Differences from Other Web Frameworks
 -------------------------------------
@@ -174,6 +186,11 @@ 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.
 
+.. index::
+   single: Repoze
+   single: Agendaless Consulting
+   pair: repoze; namespace package
+
 What Is Repoze?
 ---------------