- Added manual index entries to generated index.

24 files changed, 469 insertions, 1 deletions

diff --git a/docs/narr/configuration.rst b/docs/narr/configuration.rst
index 738295842..9a7379c3e 100644
--- a/docs/narr/configuration.rst
+++ b/docs/narr/configuration.rst
@@ -57,6 +57,9 @@ There are a number of different mechanisms you may use to configure
 and *declarative* configuration.  We'll examine both modes in the
 sections which follow.
 
+.. index::
+   pair: imperative; helloworld
+
 .. _helloworld_imperative:
 
 Hello World, Configured Imperatively
@@ -175,6 +178,9 @@ but return a response with the body ``Hello world!``; the
 ``goodbye_world`` view callable returns a response with the body
 ``Goodbye world!``.
 
+.. index::
+   pair: traversal; introduction
+
 .. _traversal_intro:
 
 An Introduction to Traversal
@@ -259,6 +265,10 @@ sole possible URL that will resolve to the ``goodbye_world`` in this
 application the URL ``'/goodbye'`` because it is the only URL that
 will resolve to the :term:`view name` of ``goodbye``.
 
+.. index::
+   pair: imperative; configuration
+   single: Configurator
+
 .. _helloworld_imperative_appconfig:
 
 Application Configuration
@@ -458,6 +468,11 @@ registry, meaning that code which attempts to use the application
 registry :term:`thread local` will no longer obtain the registry
 associated with the configurator.
 
+.. index::
+   single: make_wsgi_app
+   pair: WSGI; application
+   triple: WSGI; application; creation
+
 WSGI Application Creation
 ~~~~~~~~~~~~~~~~~~~~~~~~~
 
@@ -515,6 +530,10 @@ a good deal of what's going on "under the hood" when we configure a
 :mod:`repoze.bfg` application imperatively.  However, another mode of
 configuration exists named *declarative* configuration.
 
+.. index::
+   pair: helloworld; declarative
+   single: helloworld
+
 .. _helloworld_declarative:
 
 Hello World, Configured Declaratively
@@ -804,6 +823,9 @@ tag.  Other such tags include ``<route>``, ``<scan>``, ``<notfound>``,
 "macro" which calls methods on the
 :class:`repoze.bfg.configuration.Configurator` object on your behalf.
 
+.. index::
+   pair: ZCML; conflict detection
+
 ZCML Conflict Detection
 ~~~~~~~~~~~~~~~~~~~~~~~
 
diff --git a/docs/narr/environment.rst b/docs/narr/environment.rst
index 5f3dc345c..e56c2602f 100644
--- a/docs/narr/environment.rst
+++ b/docs/narr/environment.rst
@@ -1,3 +1,20 @@
+.. index::
+   single: environment variables
+   single: settings
+   single: reload
+   single: configure.zcml
+   single: configure_zcml
+   single: debug_authorization
+   single: reload_resources
+   single: debug_notfound
+   single: debug_all
+   single: reload_all
+   pair: debug; settings
+   pair: reload; settings
+   pair: environment; variables
+   pair: ini file; settings
+   pair: PasteDeploy; settings
+  
 .. _environment_chapter:
 
 Environment Variables and ``.ini`` File Settings
@@ -107,6 +124,9 @@ with ``reload_``). on in one fell swoop, you can use
 effect settings that do not start with ``reload_*`` such as
 ``debug_notfound``.
 
+.. index:: 
+   pair: reload_templates; reload_resources
+
 Understanding the Distinction Between ``reload_templates`` and ``reload_resources``
 -----------------------------------------------------------------------------------
 
diff --git a/docs/narr/events.rst b/docs/narr/events.rst
index b2d2f20b5..2cbbe572d 100644
--- a/docs/narr/events.rst
+++ b/docs/narr/events.rst
@@ -1,3 +1,11 @@
+.. index::
+   single: event
+   single: events
+   single: subscriber
+   single: INewRequest
+   single: INewResponse
+   pair: subscriber; ZCML directive
+
 .. _events_chapter:
 
 Using Events
diff --git a/docs/narr/extending.rst b/docs/narr/extending.rst
index c757dde99..0f9bc433d 100644
--- a/docs/narr/extending.rst
+++ b/docs/narr/extending.rst
@@ -10,6 +10,9 @@ source code that makes up the application.  The behavior of a
 :mod:`repoze.bfg` application that obeys these constraints can be
 *overridden* or *extended* without modification.
 
+.. index::
+   triple: building; extensible; application
+
 Rules for Building An Extensible Application
 --------------------------------------------
 
@@ -41,6 +44,9 @@ declarations made using the ZCML ``<view>`` directive (or the
 repoze bfg using the :term:`pkg_resources` API such as static files
 and templates.
 
+.. index::
+   pair: ZCML; granularity
+
 ZCML Granularity
 ~~~~~~~~~~~~~~~~
 
@@ -70,6 +76,9 @@ disuse *all* your ZCML, choosing instead to copy and paste it into his
 own package, if necessary.  However, doing so is considerate, and
 allows for the best reusability.
 
+.. index::
+   pair: extending existing; application
+
 Extending an Existing Application
 ---------------------------------
 
@@ -163,6 +172,9 @@ something like this:
   ``configure.zcml`` file.  See :ref:`environment_chapter` for more
   information about this setting.
 
+.. index::
+   pair: overriding; views
+
 .. _overriding_views:
 
 Overriding Views
@@ -188,6 +200,9 @@ A similar pattern can be used to *extend* the application with
 existing model type and make sure the URLs it implies are available on
 some other page rendering.
 
+.. index::
+   pair: overriding; routes
+
 .. _overriding_routes:
 
 Overriding Routes
@@ -202,6 +217,9 @@ declarations when performing an override.  Typically, this means
 and changing them as necessary.  Then disinclude any ZCML from the
 original application which contains the original declarations.
 
+.. index::
+   pair: overriding; resources
+
 .. _overriding_resources:
 
 Overriding Resources
@@ -216,6 +234,9 @@ other resources by using :term:`ZCML` ``<resource>`` declarations.  Add
 such ``<resource>`` declarations to your override package's
 ``configure.zcml`` to perform overrides.
 
+.. index::
+   pair: ZCML; inclusion
+
 Dealing With ZCML Inclusions
 ----------------------------
 
diff --git a/docs/narr/hooks.rst b/docs/narr/hooks.rst
index 6bfd99e52..990290744 100644
--- a/docs/narr/hooks.rst
+++ b/docs/narr/hooks.rst
@@ -6,6 +6,9 @@ Using Hooks
 "Hooks" can be used to influence the behavior of the
 :mod:`repoze.bfg` framework in various ways.
 
+.. index::
+   pair: not found view; changing
+
 .. _changing_the_notfound_view:
 
 Changing the Not Found View
@@ -70,6 +73,9 @@ Here's some sample code that implements a minimal NotFound view:
    ``debug_notfound`` environment setting is true than it is when it
    is false.
 
+.. index::
+   pair: forbidden view; changing
+
 .. _changing_the_forbidden_view:
 
 Changing the Forbidden View
@@ -148,6 +154,9 @@ Here's some sample code that implements a minimal forbidden view:
    an alternate forbidden view.  For example, it would make sense to
    return a response with a ``403 Forbidden`` status code.
 
+.. index::
+   pair: traverser; changing
+
 .. _changing_the_traverser:
 
 Changing the Traverser
@@ -242,6 +251,9 @@ wild" within `repoze.bfg.traversalwrapper
 <http://pypi.python.org/pypi/repoze.bfg.traversalwrapper>`_ and
 `repoze.bfg.metatg <http://svn.repoze.org/repoze.bfg.metatg/trunk/>`_.
 
+.. index::
+   pair: url generator; changing
+
 Changing How :mod:`repoze.bfg.url.model_url` Generates a URL
 ------------------------------------------------------------
 
diff --git a/docs/narr/hybrid.rst b/docs/narr/hybrid.rst
index a08425a5a..14cb1d4ab 100644
--- a/docs/narr/hybrid.rst
+++ b/docs/narr/hybrid.rst
@@ -100,6 +100,9 @@ code just won't have any ``<route>`` declarations.  Instead, its ZCML
 above will match the URL ``/a/b/c/foobar`` or ``/foobar``, etc,
 assuming that no view is named "a", "b", or "c" during traversal.
 
+.. index::
+   single: hybrid mode application
+
 Hybrid Applications
 -------------------
 
@@ -199,6 +202,10 @@ It's :term:`view name` will be looked for during traversal.  So if our
 URL is "http://example.com/one/two/a/another", the ``.views.another``
 view will be called.
 
+.. index::
+   pair: route; factory
+   single: route factory
+
 Route Factories
 ---------------
 
@@ -218,6 +225,9 @@ In this way, each route can use a different factory, making it
 possible to traverse different graphs based on some routing parameter
 within the same application.
 
+.. index::
+   pair: subpath; route
+
 .. _star_subpath:
 
 Using ``*subpath`` in a Route Path
@@ -453,6 +463,9 @@ you must the special ``*traverse`` token to the route's "path"., e.g.:
      route_name="abc"
      />
 
+.. index::
+   pair: route; ordering
+
 Route Ordering
 ~~~~~~~~~~~~~~
 
diff --git a/docs/narr/install.rst b/docs/narr/install.rst
index 4fa0ef1d8..667b08a7b 100644
--- a/docs/narr/install.rst
+++ b/docs/narr/install.rst
@@ -3,6 +3,9 @@
 Installing :mod:`repoze.bfg`
 ============================
 
+.. index::
+   pair: install; preparation
+
 Before You Install
 ------------------
 
@@ -112,6 +115,9 @@ executable and accept the defaults during the installation process.
 You may also need to download and install the `Python for Windows
 extensions <http://sourceforge.net/projects/pywin32/files/>`_.
 
+.. index::
+   pair: installing; UNIX
+
 Installing :mod:`repoze.bfg` on a UNIX System
 ---------------------------------------------
 
@@ -165,6 +171,9 @@ the script.  To remediate this, you may need to do:
 
    $ sudo python ez_setup.py
 
+.. index::
+   pair: installing; virtualenv
+
 Installing the ``virtualenv`` Package
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
@@ -185,6 +194,9 @@ to install it as your system's administrative user.  For example:
 
    $ sudo easy_install virtualenv
 
+.. index::
+   pair: creating; virtualenv
+
 Creating the Virtual Python Environment
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
@@ -228,6 +240,9 @@ virtualenv (``bfgenv``) directory:
 This command will take longer than the previous ones to complete, as it
 downloads and installs a number of dependencies.
 
+.. index::
+   pair: installing; Windows
+
 Installing :mod:`repoze.bfg` on a Windows System
 -------------------------------------------------
 
@@ -277,6 +292,9 @@ Installing :mod:`repoze.bfg` on a Windows System
 
       c:\bfgenv> Scripts\easy_install -i http://dist.repoze.org/bfg/1.1/simple repoze.bfg
 
+.. index::
+   pair: installing; Google App Engine
+
 Installing :mod:`repoze.bfg` on Google App Engine
 -------------------------------------------------
 
diff --git a/docs/narr/introduction.rst b/docs/narr/introduction.rst
index 6b5494d76..2331a50c0 100644
--- a/docs/narr/introduction.rst
+++ b/docs/narr/introduction.rst
@@ -61,6 +61,9 @@ 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
+
 Similarities to Other Web Frameworks
 ------------------------------------
 
@@ -113,6 +116,9 @@ 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/>`_ .  
 
+.. index::
+   single: differences from other frameworks
+
 Differences from Other Web Frameworks
 -------------------------------------
 
diff --git a/docs/narr/models.rst b/docs/narr/models.rst
index fdd8af9bc..0369ab178 100644
--- a/docs/narr/models.rst
+++ b/docs/narr/models.rst
@@ -8,6 +8,9 @@ traverse when :term:`traversal` is used.  A model instance is also
 generated as a result of :term:`url dispatch`.  A model instance is
 exposed to :term:`view` code as the :term:`context` of a view.
 
+.. index::
+   pair: model; constructor
+
 Defining a Model Constructor
 ----------------------------
 
@@ -30,6 +33,9 @@ A model constructor may be essentially any Python object which is
 callable, and which returns a model instance.  In the above example,
 the ``BlogEntry`` class can be "called", returning a model instance.
 
+.. index::
+   pair: model; interfaces
+
 Model Instances Which Implement Interfaces
 ------------------------------------------
 
@@ -132,6 +138,13 @@ See the :ref:`views_chapter` for more information about why providing
 models with an interface can be an interesting thing to do with regard
 to :term:`view` lookup.
 
+.. index::
+   single: model graph
+   single: traversal graph
+   single: object graph
+   single: container nodes
+   single: leaf nodes
+
 Defining a Graph of Model Instances for Traversal
 -------------------------------------------------
 
@@ -156,6 +169,9 @@ policy on model instance nodes in the graph:
 See :ref:`traversal_chapter` for more information about how traversal
 works against model instances.
 
+.. index::
+   pair: location-aware; model
+
 .. _location_aware:
 
 Location-Aware Model Instances
@@ -229,6 +245,8 @@ and so on.
    to every path and URL generated (as opposed to a single leading
    slash or empty tuple element).
 
+.. index::
+   pair: model; API functions
 
 :mod:`repoze.bfg` API Functions That Act Against Models
 -------------------------------------------------------
diff --git a/docs/narr/project.rst b/docs/narr/project.rst
index 2fe5489e2..681fba7a6 100644
--- a/docs/narr/project.rst
+++ b/docs/narr/project.rst
@@ -20,6 +20,9 @@ extended with new code and an application that lives inside a package
 can be distributed more easily than one which does not live within a
 package.
 
+.. index::
+   pair: project; creating
+
 .. _creating_a_project:
 
 Creating the Project
@@ -99,6 +102,10 @@ application's Python code and templates.
    name during ``paster create`` by adding the project name to the
    command line, e.g. ``paster create -t bfg_starter MyProject``.
 
+.. index::
+   single: paster templates
+   single: project templates
+
 .. _additional_paster_templates:
 
 Additional Paster Templates
@@ -142,6 +149,9 @@ This will install your application's :term:`package` into the
 interpreter so it can be found and run as a :term:`WSGI` application
 inside a WSGI server.
 
+.. index::
+   pair: running; tests
+
 Running The Tests For Your Application
 --------------------------------------
 
@@ -176,6 +186,9 @@ Here's sample output from a test run:
 The tests are found in the ``tests.py`` module in your ``paster
 create`` -generated project.  One sample test exists.
 
+.. index::
+   single: interactive shell
+
 The Interactive Shell
 ---------------------
 
@@ -311,6 +324,9 @@ something in your browser like what is displayed below:
 That's the page shown by default when you visit an unmodified ``paster
 create``-generated application.
 
+.. index::
+   single: project structure
+
 The Project Structure
 ---------------------
 
@@ -362,6 +378,10 @@ describe, run, and test your application.
 
 We won't describe the ``CHANGES.txt`` or ``README.txt`` files.
 
+.. index::
+   single: PasteDeploy
+   single: ini file
+
 .. _MyProject_ini:
 
 ``MyProject.ini``
@@ -466,6 +486,9 @@ See the :term:`PasteDeploy` documentation for more information about
 other types of things you can put into this ``.ini`` file, such as
 other applications, :term:`middleware` and alternate servers.
 
+.. index::
+   single: setup.py
+
 ``setup.py``
 ~~~~~~~~~~~~
 
@@ -541,6 +564,9 @@ tarball to other people who want to use your application.
    you rerun ``setup.py sdist``, all files checked into the version
    control system will be included in the tarball.
 
+.. index::
+   single: package
+
 The ``myproject`` :term:`Package`
 ---------------------------------
 
@@ -573,6 +599,9 @@ These are purely conventions established by the ``paster`` template:
 :mod:`repoze.bfg` doesn't insist that you name things in any
 particular way.
 
+.. index::
+   single: configure.zcml
+
 ``configure.zcml``
 ~~~~~~~~~~~~~~~~~~
 
@@ -626,6 +655,9 @@ the :term:`application registry`. It looks like so:
 
 #. Line 17 ends the ``configure`` root tag.
 
+.. index::
+   single: views.py
+
 ``views.py``
 ~~~~~~~~~~~~
 
@@ -667,6 +699,9 @@ views, renderers, and templates relate and cooperate.
    set your project's ``reload_templates`` to ``false`` to increase
    the speed at which templates may be rendered.
 
+.. index::
+   single: models.py
+
 .. _modelspy_project_section:
 
 ``models.py``
@@ -695,6 +730,9 @@ make any assumption about which sort of datastore you'll want to use,
 so the sample application uses an instance of
 :class:`myproject.models.MyModel` to represent the root.
 
+.. index::
+   single: run.py
+
 ``run.py``
 ~~~~~~~~~~
 
@@ -739,6 +777,9 @@ renderers.
 This directory contains static resources which support the
 ``mytemplate.pt`` template.  It includes CSS and images.
 
+.. index::
+   single: tests.py
+
 ``tests.py``
 ~~~~~~~~~~~~
 
diff --git a/docs/narr/resources.rst b/docs/narr/resources.rst
index 53d01c920..ce3c746cd 100644
--- a/docs/narr/resources.rst
+++ b/docs/narr/resources.rst
@@ -1,3 +1,6 @@
+.. index::
+   single: resources
+
 .. _resources_chapter:
 
 Resources
@@ -70,6 +73,10 @@ Package names often contain dots.  For example, ``repoze.bfg`` is a
 package.  Resource names usually look a lot like relative UNIX file
 paths.
 
+.. index::
+   single: overriding resources
+   pair: overriding; resources
+
 .. _overriding_resources_section:
 
 Overriding Resources
@@ -142,6 +149,9 @@ hammer" way to do the same thing is explained in
 replace a :term:`view` wholesale rather than resources that might be
 used by a view.
 
+.. index::
+   single: override_resource
+
 .. _override_resource:
 
 The ``override_resource`` API
@@ -227,6 +237,9 @@ templates and static files.  Any software which uses the
 :func:`pkg_resources.get_resource_string` APIs will obtain an
 overridden file when an override is used.
 
+.. index::
+   pair: ZCML directive; resource
+
 .. _resource_zcml_directive:
 
 The ``resource`` ZCML Directive
diff --git a/docs/narr/router.rst b/docs/narr/router.rst
index 48a068626..98752216a 100644
--- a/docs/narr/router.rst
+++ b/docs/narr/router.rst
@@ -1,3 +1,7 @@
+.. index::
+   single: request processing
+   single: request
+
 .. _router_chapter:
 
 Request Processing
diff --git a/docs/narr/scanning.rst b/docs/narr/scanning.rst
index 2226b557f..4aceb926b 100644
--- a/docs/narr/scanning.rst
+++ b/docs/narr/scanning.rst
@@ -23,6 +23,10 @@ For example:
   registry` if the package the code lives in is run through a
   :term:`scan`.
 
+.. index::
+   single: decorator
+   single: scan
+
 Decorations and Code Scanning
 -----------------------------
 
@@ -84,6 +88,12 @@ Scanning for :term:`configuration decoration` is performed via the
 ``<scan>`` :term:`ZCML declaration`.  See
 :ref:`config_mode_equivalence` for examples.
 
+.. index::
+   pair: configuration mode; equivalence
+   single: add_view
+   single: bfg_view
+   pair: ZCML directive; view
+
 .. _config_mode_equivalence:
 
 Configuration Mode Equivalence
diff --git a/docs/narr/security.rst b/docs/narr/security.rst
index 0d1e3295d..36469def0 100644
--- a/docs/narr/security.rst
+++ b/docs/narr/security.rst
@@ -12,6 +12,9 @@ appropriate level of access with respect to a specific
 Authorization is enabled by modifying your application to include a
 :term:`authentication policy` and :term:`authorization policy`.
 
+.. index::
+   pair: enabling; authorization policy
+
 Enabling an Authorization Policy Imperatively
 ---------------------------------------------
 
@@ -62,6 +65,9 @@ It is also possible to construct your own custom authentication policy
 or authorization policy: see :ref:`creating_an_authentication_policy`
 and :ref:`creating_an_authorization_policy`.
 
+.. index::
+   triple: enabling; authorization policy; via ZCML
+
 Enabling an Authorization Policy Via ZCML
 -----------------------------------------
 
@@ -103,6 +109,10 @@ authentication policy ZCML directives that should prove useful.  See
 :ref:`authentication_policies_directives_section` and
 :ref:`authorization_policies_directives_section` for more information.
 
+.. index::
+   single: permissions
+   single: protecting views
+
 Protecting Views with Permissions
 ---------------------------------
 
@@ -146,6 +156,9 @@ Permission names are usually just strings.  They hold no special
 significance to the system.  You can name permissions whatever you
 like.
 
+.. index::
+   pair: assigning; ACL
+
 .. _assigning_acls:
 
 Assigning ACLs to your Model Objects
@@ -201,6 +214,9 @@ individual model instances with an ACL (as opposed to just decorating
 their class) in applications such as "CMS" systems where fine-grained
 access is required on an object-by-object basis.
 
+.. index::
+   single: ACE
+
 Elements of an ACL
 ------------------
 
@@ -287,6 +303,10 @@ view permission.  On the other hand, if you have an ACL like this:
 The authorization policy will deny Everyone the view permission, even
 though later in the ACL is an ACE that allows everyone.
 
+.. index::
+   single: prinicpal
+   pair: special; principal names
+
 Special Principal Names
 -----------------------
 
@@ -308,6 +328,9 @@ ACLs, e.g. :data:`repoze.bfg.security.Everyone`.
   This object is actually a string "under the hood"
   (``system.Authenticated``).
 
+.. index::
+   pair: special; permission names
+
 Special Permissions
 -------------------
 
@@ -325,6 +348,9 @@ module.  These can be imported for use in ACLs.
   known authorization policies, has the effect of indicating that a
   given principal "has" any permission asked for by the system.
 
+.. index::
+   pair: special; ACE
+
 Special ACEs
 ------------
 
@@ -352,6 +378,9 @@ authorization policy is in effect might look like so:
 
    __acl__ = [ (Allow, 'fred', 'view'), DENY_ALL ]
 
+.. index::
+   single: ACL inheritance
+
 ACL Inheritance
 ---------------
 
@@ -361,6 +390,9 @@ consulted for an ACL.  If that object does not have an ACL, *its*
 parent is consulted for an ACL, ad infinitum, until we've reached the
 root and there are no more parents left.
 
+.. index::
+   pair: location-aware; security
+
 Location-Awareness
 ------------------
 
@@ -384,6 +416,9 @@ root object's ``__parent__`` is ``None``.
 See :ref:`location_module` for documentations of functions which use
 location-awareness.  See also :ref:`location_aware`.
 
+.. index::
+   pair: forbidden view; changing
+
 Changing the Forbidden View
 ---------------------------
 
@@ -394,6 +429,9 @@ of the box", this forbidden view is very plain.  See
 instructions on how to create a custom forbidden view and arrange for
 it to be called when view authorization is denied.
 
+.. index::
+   pair: debugging; authorization failures
+
 .. _debug_authorization_section:
 
 Debugging View Authorization Failures
@@ -440,6 +478,9 @@ denied or allowed.  Introspecting this information in the debugger or
 via print statements when a call to
 :func:`repoze.bfg.security.has_permission` fails is often useful.
 
+.. index::
+   pair: ZCML directive; authentication policy
+
 .. _authentication_policies_directives_section:
 
 Built-In Authentication Policy ZCML Directives
@@ -516,6 +557,9 @@ An example of its usage, with all attributes fully expanded:
 See :ref:`repozewho1authenticationpolicy_directive` for detailed
 information.
 
+.. index::
+   pair: ZCML directive; authorization policy
+
 .. _authorization_policies_directives_section:
 
 Built-In Authorization Policy ZCML Directives
@@ -538,6 +582,9 @@ In other words, it has no configuration attributes; its existence in a
 
 See :ref:`aclauthorizationpolicy_directive` for detailed information.
 
+.. index::
+   pair: creating; authentication policy
+
 .. _creating_an_authentication_policy:
 
 Creating Your Own Authentication Policy
@@ -578,6 +625,9 @@ After you do so, you can pass an instance of such a class into the
 :class:`repoze.bfg.configuration.Configurator` class at configuration
 time as ``authentication_policy`` to use it.
 
+.. index::
+   pair: creating; authorization policy
+
 .. _creating_an_authorization_policy:
 
 Creating Your Own Authorization Policy
diff --git a/docs/narr/startup.rst b/docs/narr/startup.rst
index 4e806ec17..960e2aa1d 100644
--- a/docs/narr/startup.rst
+++ b/docs/narr/startup.rst
@@ -17,6 +17,9 @@ This chapter explains what happens between the time you press the
 myproject/MyProject.ini`` and the the time the line ``serving on
 0.0.0.0:6543 ...`` is output to your console.
 
+.. index::
+   single: startup process
+
 The Startup Process
 -------------------
 
diff --git a/docs/narr/templates.rst b/docs/narr/templates.rst
index 1ea8da369..ac44b64da 100644
--- a/docs/narr/templates.rst
+++ b/docs/narr/templates.rst
@@ -7,6 +7,9 @@ information that is static.  :mod:`repoze.bfg` offers a number of ways
 to perform templating tasks "out of the box", and provides alternative
 templating language support via add-on "bindings" packages.
 
+.. index::
+   triple: Chameleon; ZPT; templates
+
 .. _chameleon_zpt_templates:
 
 Templating With :term:`Chameleon` ZPT Page Templates
@@ -90,6 +93,10 @@ changing the content-type and status:
        response.status_int = 204
        return response
 
+.. index::
+   single: templates used as renderers
+   pair: renderers; template
+
 Templates Used as Renderers
 ---------------------------
 
@@ -141,6 +148,9 @@ renderer configuration can be done imperatively and via :term:`ZCML`.
 See :ref:`views_which_use_a_renderer`.  See also
 :ref:`built_in_renderers`.
 
+.. index::
+   single: sample template
+
 A Sample Template
 -----------------
 
@@ -175,6 +185,9 @@ of keywords passed in to it via
 attribute-based syntax (e.g. ``tal:content`` and ``tal:replace``) also
 works in these templates.
 
+.. index::
+   single: ZPT macros
+
 Using ZPT Macros in :mod:`repoze.bfg`
 -------------------------------------
 
@@ -235,6 +248,9 @@ And ``templates/mytemplate.pt`` might look like so:
       </span>
     </html>
 
+.. index::
+   pair: Chameleon; text templates
+
 .. _chameleon_text_templates:
 
 Templating with :term:`Chameleon` Text Templates
@@ -269,6 +285,9 @@ place; see :ref:`chameleon_text_module` for the API description.
 A Chameleon text template can also be used as a :term:`renderer`.  See
 :ref:`built_in_renderers` for more information.
 
+.. index::
+   pair: template renderer; side effects
+
 Side Effects of Rendering a Chameleon Template
 ----------------------------------------------
 
@@ -295,6 +314,9 @@ should cause it to ignore these files.  Here's the contents of my
    *.cache
    *.pt.py
 
+.. index::
+   pair: template; automatic reloading
+
 .. _reload_templates_section:
 
 Automatically Reloading Templates
@@ -327,6 +349,9 @@ application's configuration section, e.g.::
   use = egg:MyProject#app
   reload_templates = true
 
+.. index::
+   pair: template; internationalization
+
 :term:`Chameleon` Template Internationalization
 -----------------------------------------------
 
@@ -335,6 +360,9 @@ See `the internationalization chapter
 documentation for information about supporting internationalized units
 of text within :term:`Chameleon` templates.
 
+.. index::
+   single: other templating languages
+
 Templating with other Templating Languages
 ------------------------------------------
 
@@ -374,6 +402,11 @@ template resource overriding capability explained in
 possible to use any template using that language as a
 :term:`renderer`.
 
+.. index::
+   single: template system bindings
+   single: Jinja2
+   single: Genshi
+
 .. _available_template_system_bindings:
 
 Available Add-On Template System Bindings
diff --git a/docs/narr/threadlocals.rst b/docs/narr/threadlocals.rst
index a799e2d03..4600b7a88 100644
--- a/docs/narr/threadlocals.rst
+++ b/docs/narr/threadlocals.rst
@@ -1,3 +1,8 @@
+.. index::
+   single: thread local variables
+   single: get_current_request
+   single: get_current_registry
+
 .. _threadlocals_chapter:
 
 Thread Locals
diff --git a/docs/narr/traversal.rst b/docs/narr/traversal.rst
index 3476622d5..e59212728 100644
--- a/docs/narr/traversal.rst
+++ b/docs/narr/traversal.rst
@@ -13,6 +13,11 @@ Python class or any :term:`interface` attached to it).  If
 :mod:`repoze.bfg` finds a :term:`view` for the context, it calls it
 and returns a response to the user.
 
+.. index::
+   single: object graph
+   single: traversal graph
+   single: model graph
+
 The Object Graph
 ----------------
 
@@ -55,6 +60,9 @@ concept of :term:`model` objects used by many other frameworks (and
 :mod:`repoze.bfg` APIs often refers to them as "models", as well).
 They are typically instances of Python classes.
 
+.. index::
+   single: traversal behavior
+
 .. _traversal_behavior:
 
 :mod:`repoze.bfg` Traversal Behavior
@@ -240,6 +248,9 @@ code to execute:
 In either case, the result is returned upstream via the :term:`WSGI`
 protocol.
 
+.. index::
+   pair: traversal; example
+
 A Traversal Example
 -------------------
 
@@ -361,6 +372,9 @@ There are two special cases:
   views that may have the same names as model instance names in the
   graph unambiguously.
 
+.. index::
+   pair: traversal; side-effects
+
 .. _traversal_related_side_effects:
 
 Traversal-Related Side Effects
@@ -402,6 +416,9 @@ will be a sequence representing the ordered set of names that were
 used to traverse to the virtual root object.  See
 :ref:`vhosting_chapter` for more information about virtual roots.
 
+.. index::
+   pair: debugging; not found errors
+
 .. _debug_notfound_section:
 
 :exc:`NotFound` Errors
@@ -416,6 +433,9 @@ be printed to ``stderr``, and the browser representation of the error
 will include the same information.  See :ref:`environment_chapter` for
 more information about how and where to set these values.
 
+.. index::
+   pair: traversal; unicode
+
 Traversal and Unicode
 ---------------------
 
diff --git a/docs/narr/unittesting.rst b/docs/narr/unittesting.rst
index 316142c08..d032e3a36 100644
--- a/docs/narr/unittesting.rst
+++ b/docs/narr/unittesting.rst
@@ -1,3 +1,7 @@
+.. index::
+   single: unit testing
+   single: integration testing
+
 .. _unittesting_chapter:
 
 Unit and Integration Testing
@@ -51,6 +55,11 @@ integration tests easier to write.  The facilities become particularly
 useful when your code calls into :mod:`repoze.bfg` -related framework
 functions.
 
+.. index::
+   pair: test; setup
+   pair: test; tear down
+   single: unittest
+
 .. _test_setup_and_teardown:
 
 Test Set Up and Tear Down
@@ -151,6 +160,10 @@ method within the ``setUp`` of a unit test, then subsequently call its
 anything if the application you're testing does not call any
 ``get_current*`` function.
 
+.. index::
+   single: repoze.bfg.testing
+   pair: Configurator; testing
+
 Using the ``Configurator`` and ``repoze.bfg.testing`` APIs in Unit Tests
 ------------------------------------------------------------------------
 
@@ -282,6 +295,9 @@ representing "dummy" implementations of a request and a model.
 See also the various methods of the :term:`Configurator` documented in
 :ref:`configuration_module` that begin with the ``testing_`` prefix.
 
+.. index::
+   pair: creating; integration tests
+
 .. _integration_tests:
 
 Creating Integration Tests
diff --git a/docs/narr/urldispatch.rst b/docs/narr/urldispatch.rst
index 2d74bfbca..728795e7f 100644
--- a/docs/narr/urldispatch.rst
+++ b/docs/narr/urldispatch.rst
@@ -1,3 +1,6 @@
+.. index::
+   single: url dispatch
+
 .. _urldispatch_chapter:
 
 URL Dispatch
@@ -53,6 +56,9 @@ error to the user's browser when no routes match.
 .. note:: See :ref:`modelspy_project_section` for an example of a
           simple root factory callable that will use traversal.
 
+.. index::
+   single: add_route
+
 The ``add_route`` Configurator Method
 -------------------------------------
 
@@ -65,6 +71,9 @@ registry`.  Here's an example:
 
    config.add_route('myroute', '/prefix/:one/:two')
 
+.. index::
+   single: ZCML directive; route
+
 Configuring a Route via ZCML
 ----------------------------
 
@@ -85,6 +94,9 @@ documentation.
 .. note:: The documentation that follows in this chapter assumes that
    :term:`ZCML` will be used to perform route configuration.
 
+.. index::
+   pair: URL dispatch; matchdict
+
 The Matchdict
 -------------
 
@@ -95,6 +107,9 @@ matched, a dictionary is placed on the request named ``matchdict``
 with the values that match patterns in the ``path`` element.  If the
 URL pattern does not match, no matchdict is generated.
 
+.. index::
+   pair: URL dispatch; path pattern syntax
+
 .. _route_path_pattern_syntax:
 
 Path Pattern Syntax
@@ -204,6 +219,9 @@ Will generate the following matchdict:
 
    {'traverse':(u'La Pe\xf1a', u'a', u'b', u'c')}
 
+.. index::
+   triple: ZCML directive; route; examples
+
 ``<route>`` Statement Examples
 ------------------------------
 
@@ -419,6 +437,9 @@ In this case in particular, when a user visits
 Article class and it will have an ``article`` attribute with the value
 of ``something``.
 
+.. index::
+   pair: URL dispatch; catching root URL
+
 Catching the Root URL
 ---------------------
 
@@ -446,6 +467,9 @@ Or provide the literal string ``/`` as the path:
        view=".views.root_view"
        />
 
+.. index::
+   pair: URL dispatch; generating route URLs
+
 Generating Route URLs
 ---------------------
 
@@ -467,6 +491,9 @@ hostname implied ``http:/example.com``).  See the
 :func:`repoze.bfg.url.route_url` API documentation for more
 information.
 
+.. index::
+   pair: URL dispatch; slash-redirecting
+
 Redirecting to Slash-Appended Routes
 ------------------------------------
 
@@ -574,6 +601,9 @@ Then in the ``configure.zcml`` of your package, inject the following:
 This will cause the DBSession to be removed whenever the WSGI
 environment is destroyed (usually at the end of every request).
 
+.. index::
+   pair: URL dispatch; security
+
 .. _using_security_with_urldispatch:
 
 Using :mod:`repoze.bfg` Security With URL Dispatch
diff --git a/docs/narr/urlmapping.rst b/docs/narr/urlmapping.rst
index e5933ae1e..1f094d452 100644
--- a/docs/narr/urlmapping.rst
+++ b/docs/narr/urlmapping.rst
@@ -29,6 +29,9 @@ potentially heterogeneous items, or if you need to attach
 "instance-level" security (akin to "row-level" security in relational
 parlance) declarations to :term:`model` instances.
 
+.. index::
+   triple: differences; URL dispatch; traversal
+
 Differences Between Traversal and URL Dispatch
 ----------------------------------------------
 
diff --git a/docs/narr/vhosting.rst b/docs/narr/vhosting.rst
index 964741080..80336fe82 100644
--- a/docs/narr/vhosting.rst
+++ b/docs/narr/vhosting.rst
@@ -3,6 +3,9 @@
 Virtual Hosting
 ===============
 
+.. index::
+   pair: virtual hosting; URL prefix
+
 Hosting an Application Under a URL Prefix
 -----------------------------------------
 
@@ -63,6 +66,9 @@ setting in a :term:`mod_wsgi` configuration does the work for you:
 In the above configuration, we root a :mod:`repoze.bfg` application at
 ``/bfgapp`` within the Apache configuration.
 
+.. index::
+   pair: virtual hosting; virtual root
+
 Virtual Root Support
 --------------------
 
diff --git a/docs/narr/views.rst b/docs/narr/views.rst
index 1a507f432..b25756fd9 100644
--- a/docs/narr/views.rst
+++ b/docs/narr/views.rst
@@ -38,6 +38,11 @@ adding a ``<route>`` statement to :term:`ZCML` used by your
 application.  See :ref:`urldispatch_chapter` for more information on
 mapping URLs to views using routes.
 
+.. index::
+   pair: view; calling convention
+   single: view function
+   pair: view; function
+
 .. _function_as_view:
 
 Defining a View as a Function
@@ -56,6 +61,11 @@ implemented as a function:
    def hello_world(request):
        return Response('Hello world!')
 
+.. index::
+   pair: view; calling convention
+   single: view class
+   pair: view; class
+
 .. _class_as_view:
 
 Defining a View as a Class 
@@ -100,6 +110,9 @@ represent the method expected to return a response, you can use an
 ``attr`` value as part of view configuration.  See
 :ref:`view_configuration`.
 
+.. index::
+   pair: view; calling convention
+
 .. _request_and_context_view_definitions:
 
 Request-And-Context View Definitions
@@ -167,6 +180,9 @@ view code itself.
 No matter which view calling convention is used, the view always has
 access to the context via ``request.context``.
 
+.. index::
+   pair: view; response
+
 .. _the_response:
 
 View Responses
@@ -203,6 +219,10 @@ to construct a response.  The associated renderer can be varied for a
 view by changing the ``renderer`` attribute in the view's
 configuration.  See :ref:`views_which_use_a_renderer`.
 
+.. index::
+   single: renderer
+   pair: view; renderer
+
 .. _views_which_use_a_renderer:
 
 Writing Views Which Use a Renderer
@@ -259,6 +279,10 @@ class as a response, no renderer will be employed.
 Additional renderers can be added to the system as necessary via a
 ZCML directive (see :ref:`adding_and_overriding_renderers`).
 
+.. index::
+   single: view configuration
+   pair: view; configuration
+
 .. _view_configuration:
 
 View Configuration: Mapping Views to URLs
@@ -270,6 +294,9 @@ method, by adding ``view`` declarations using :term:`ZCML` or by using
 the :class:`repoze.bfg.view.bfg_view` decorator.  Each method is
 explained below.
 
+.. index::
+   triple: zcml; view; configuration
+
 .. _mapping_views_to_urls_using_zcml_section:
 
 View Configuration Via ZCML
@@ -342,6 +369,9 @@ apply for the class which is named.
 
 See :ref:`view_directive` for complete ZCML directive documentation.
 
+.. index::
+   triple: view; bfg_view; decorator
+
 .. _mapping_views_to_urls_using_a_decorator_section:
 
 View Configuration Using the ``@bfg_view`` Decorator
@@ -638,6 +668,10 @@ could be spelled equivalently as the below:
           version 1.1.  Previously it could only be used as a class or
           function decorator.
 
+.. index::
+   single: add_view
+   triple: imperative; adding; view
+
 View Configuration Using the ``add_view`` Method of a Configurator
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
@@ -645,6 +679,9 @@ See the :meth:`repoze.bfg.configuration.Configurator.add_view` method
 within :ref:`configuration_module` for the arguments to configure a
 view imperatively.
 
+.. index::
+   pair: view; lookup ordering
+
 .. _view_lookup_ordering:
 
 View Lookup Ordering
@@ -703,6 +740,9 @@ to convert non-response return values from a view.
 The value of the ``attr`` attribute represents the attribute name
 looked up on the view object to return a response.
 
+.. index::
+   pair: model; interfaces
+
 .. _using_model_interfaces:
 
 Using Model Interfaces
@@ -790,6 +830,9 @@ view registered for the context's class will "win".
 See :term:`Interface` in the glossary to find more information about
 interfaces.
 
+.. index::
+   pair: renderers; built-in
+
 .. _built_in_renderers:
 
 Built-In Renderers
@@ -799,6 +842,9 @@ Several built-in "renderers" exist in :mod:`repoze.bfg`.  These
 renderers can be used in the ``renderer`` attribute of view
 configurations.
 
+.. index::
+   pair: renderer; string
+
 ``string``: String Renderer
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
@@ -832,6 +878,9 @@ representing the ``str()`` serialization of the return value:
 
    {'content': 'Hello!'}
 
+.. index::
+   pair: renderer; JSON
+
 ``json``: JSON Renderer
 ~~~~~~~~~~~~~~~~~~~~~~~
 
@@ -883,6 +932,9 @@ Views which use the JSON renderer can vary non-body response
 attributes by attaching properties to the request.  See
 :ref:`response_request_attrs`.
 
+.. index::
+   pair: renderer; chameleon
+
 .. _chameleon_template_renderers:
 
 ``*.pt`` or ``*.txt``: Chameleon Template Renderers
@@ -958,6 +1010,11 @@ Views with use a Chameleon renderer can vary response attributes by
 attaching properties to the request.  See
 :ref:`response_request_attrs`.
 
+.. index::
+   pair: renderer; response attributes
+   pair: renderer; changing headers
+   triple: headers; changing; renderer
+
 .. _response_request_attrs:
 
 Varying Attributes of Rendered Responses
@@ -999,6 +1056,9 @@ callable to influence automatically constructed response attributes.
   achieved by returning various values in the ``response_headerlist``,
   this is purely a convenience.
 
+.. index::
+   pair: renderers; adding
+
 .. _adding_and_overriding_renderers:
 
 Adding and Overriding Renderers
@@ -1147,6 +1207,9 @@ tag):
 
 See also :ref:`renderer_directive`.
 
+.. index::
+   pair: view; security
+
 .. _view_security_section:
 
 View Security
@@ -1188,6 +1251,9 @@ user does not possess the ``add`` permission relative to the current
    authenticate.  Use this kind of package to ask the user for
    authentication credentials.
 
+.. index::
+   pair: view; http redirect
+
 Using a View to Do A HTTP Redirect
 ----------------------------------
 
@@ -1207,6 +1273,9 @@ Webob :term:`Response` interface; any can be returned as the response
 from a view.  See :term:`WebOb` for the documentation for this module;
 it includes other response types for ``Unauthorized``, etc.
 
+.. index::
+   triple: view; zcml; static resource
+
 .. _static_resources_section:
 
 Serving Static Resources Using a ZCML Directive
@@ -1275,6 +1344,9 @@ See :ref:`static_directive` for detailed information.
 .. note:: The ``<static>`` ZCML directive is new in :mod:`repoze.bfg`
    1.1.
 
+.. index::
+   pair: generating; static resource
+
 .. _generating_static_resource_urls:
 
 Generating Static Resource URLs
@@ -1342,6 +1414,9 @@ URLs will continue to resolve properly after the rename.
 .. note:: The :func:`repoze.bfg.url.static_url` API is new in
    :mod:`repoze.bfg` 1.1.
 
+.. index::
+   pair: view; static resource
+
 Serving Static Resources Using a View
 -------------------------------------
 
@@ -1409,6 +1484,9 @@ In this case, ``.models.Root`` refers to the class of which your
    ``/static/foo.js``.  See :ref:`traversal_chapter` for information
    about "goggles" (``@@``).
 
+.. index::
+   triple: exceptions; special; view
+
 Special Exceptions
 ------------------
 
@@ -1434,6 +1512,9 @@ In all cases, the message provided to the exception constructor is
 made available to the view which :mod:`repoze.bfg` invokes as
 ``request.environ['repoze.bfg.message']``.
 
+.. index::
+   triple: view; forms; unicode
+
 Using Views to Handle Form Submissions (Unicode and Character Set Issues)
 -------------------------------------------------------------------------
 
diff --git a/docs/narr/webob.rst b/docs/narr/webob.rst
index c4bd568c7..91413efd0 100644
--- a/docs/narr/webob.rst
+++ b/docs/narr/webob.rst
@@ -36,6 +36,9 @@ document.  The `reference documentation
 <http://pythonpaste.org/webob/reference.html>`_ shows many examples of
 creating requests.
 
+.. index::
+   single: request object
+
 Request
 ~~~~~~~
 
@@ -155,6 +158,9 @@ If it is set, then ``req.POST``, ``req.GET``, ``req.params``, and
 corresponding ``req.str_*`` (like ``req.str_POST``) that is always
 ``str`` and never unicode.
 
+.. index::
+   single: response object
+
 Response
 ~~~~~~~~
 
@@ -222,6 +228,9 @@ Here's the highlights:
     ``conditional_response=True`` when instantiating (or set that
     attribute later).  It can also do HEAD and Range requests.
 
+.. index::
+   pair: response; headers
+
 Headers
 +++++++
 
@@ -249,7 +258,10 @@ The status defaults to ``'200 OK'``.  The content_type does not
 default to anything, though if you subclass ``Response`` and set
 ``default_content_type`` you can override this behavior.
 
-Exceptions
+.. index::
+   pair: WebOb; exceptions
+
+xceptions
 ++++++++++
 
 To facilitate error responses like 404 Not Found, the module
@@ -290,6 +302,9 @@ The exceptions are still WSGI applications, but you cannot set
 attributes like ``content_type``, ``charset``, etc. on these exception
 objects.
 
+.. index::
+   pair: WebOb; multidict
+
 Multidict
 +++++++++