Reduce overall book size by not giving each ZCML directive its own chapter.

6 files changed, 88 insertions, 90 deletions

diff --git a/docs/api.rst b/docs/api.rst
new file mode 100644
index 000000000..2bd5fca01
--- /dev/null
+++ b/docs/api.rst
@@ -0,0 +1,31 @@
+API Documentation
+=================
+
+Comprehensive reference material for every public API exposed by
+:mod:`repoze.bfg` is available within this chapter.  The API
+documentation is organized alphabetically by module name.
+
+.. toctree::
+   :maxdepth: 1
+
+   api/authorization
+   api/authentication
+   api/chameleon_text
+   api/chameleon_zpt
+   api/configuration
+   api/events
+   api/exceptions
+   api/interfaces
+   api/location
+   api/paster
+   api/router
+   api/scripting
+   api/security
+   api/settings
+   api/testing
+   api/threadlocal
+   api/traversal
+   api/url
+   api/view
+   api/wsgi
+
diff --git a/docs/authorintro.rst b/docs/authorintro.rst
index 53d62834d..4355fc125 100644
--- a/docs/authorintro.rst
+++ b/docs/authorintro.rst
@@ -1,16 +1,17 @@
-Author Introduction
-===================
+=====================
+ Author Introduction
+=====================
 
 Welcome to "The :mod:`repoze.bfg` Web Application Framework".  In this
-introduction, I'll describe this book, I'll provide some context
-regarding the genesis of :mod:`repoze.bfg`, and I'll thank some
-important people.
+introduction, I'll describe the audience for this book, I'll describe
+the book content, I'll provide some context regarding the genesis of
+:mod:`repoze.bfg`, and I'll thank some important people.
 
 I hope you enjoy both this book and the software it documents.  I've
 had a blast writing both.
 
 Audience
---------
+========
 
 This book is aimed primarily at a reader that has the following
 attributes:
@@ -44,17 +45,36 @@ structures. As a result, you can usually avoid becoming "blocked"
 while you read this book even if you don't yet deeply understand web
 technologies.
 
-Book Style
-----------
+.. index::
+   single: book content overview
+
+Book Content
+============
+
+This book is divided into three major parts: a narrative documentation
+part, a tutorial part, and an API documentation part.
+
+Narrative Documentation
+
+  This is documentation which describes :mod:`repoze.bfg` concepts in
+  narrative form, written in a largely conversational tone.  Each
+  narrative documentation chapter describes an isolated
+  :mod:`repoze.bfg` concept.  You should be able to get useful
+  information out of the narrative chapters if you read them
+  out-of-order, or when you need only a reminder about a particular
+  topic while you're developing an application.
+
+Tutorials
+
+  Each tutorial builds a sample application or implements a concept
+  and describes the concept in terms of the example.  You should read
+  the tutorials if you want a guided tour of :mod:`repoze.bfg`.
+
+Reference
 
-This book is not the kind of book that imposes upon the reader by
-describing concepts in terms of a single manufactured sample
-application; in particular, its narrative does not build a small
-application into a larger one as the book progresses.  As a result,
-you should be able to get useful information out of the book if you
-neglect to read it from cover-to-cover, if you read it out-of-order,
-or when you need only a reminder about a particular topic while you're
-developing an application.
+  The API documentation is reference material related to the
+  :mod:`repoze.bfg` API.  Use it while you're developing a
+  :mod:`repoze.bfg` application.
 
 .. index::
    single: repoze.zope2
@@ -62,7 +82,7 @@ developing an application.
    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
@@ -109,7 +129,7 @@ a cohesive whole that is reliable, down-to-earth, flexible, speedy,
 and well-documented.
 
 Thanks
-------
+======
 
 This book is dedicated to my grandmother, Dorothy Phillips, who gave
 me my first typewriter (a Royal), and my mother, Donelle Duffy, who
diff --git a/docs/index.rst b/docs/index.rst
index 9535a2815..3f5f81cfd 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -61,45 +61,6 @@ Narrative documentation in chapter form explaining how to use
    narr/router
    narr/threadlocals
 
-API documentation
-=================
-
-Per-module :mod:`repoze.bfg` API documentation.
-
-.. toctree::
-   :maxdepth: 2
-
-   api/authorization
-   api/authentication
-   api/chameleon_text
-   api/chameleon_zpt
-   api/configuration
-   api/events
-   api/exceptions
-   api/interfaces
-   api/location
-   api/paster
-   api/router
-   api/scripting
-   api/security
-   api/settings
-   api/testing
-   api/threadlocal
-   api/traversal
-   api/url
-   api/view
-   api/wsgi
-
-ZCML Directives
-===============
-
-Documentation for each :mod:`repoze.bfg` :term:`ZCML directive`.
-
-.. toctree::
-   :maxdepth: 1
-
-   zcml
-
 Tutorials
 =========
 
@@ -119,6 +80,18 @@ applications to various platforms.
    tutorials/zodbsessions/index.rst
    tutorials/catalog/index.rst
 
+Reference Material
+==================
+
+Reference material includes API documentation and documentation of
+every :mod:`repoze.bfg` :term:`ZCML directive`.
+
+.. toctree::
+   :maxdepth: 2
+
+   api
+   zcml
+
 Detailed Change History
 =======================
 
diff --git a/docs/latexindex.rst b/docs/latexindex.rst
index 89563b779..4000ea077 100644
--- a/docs/latexindex.rst
+++ b/docs/latexindex.rst
@@ -62,39 +62,13 @@ Tutorials
    tutorials/zodbsessions/index.rst
    tutorials/catalog/index.rst
 
-API documentation
-@@@@@@@@@@@@@@@@@
-
-.. toctree::
-   :maxdepth: 2
-
-   api/authorization
-   api/authentication
-   api/chameleon_text
-   api/chameleon_zpt
-   api/configuration
-   api/events
-   api/exceptions
-   api/interfaces
-   api/location
-   api/paster
-   api/router
-   api/scripting
-   api/security
-   api/settings
-   api/testing
-   api/threadlocal
-   api/traversal
-   api/url
-   api/view
-   api/wsgi
-
-ZCML Directives
-@@@@@@@@@@@@@@@@
+Reference material
+@@@@@@@@@@@@@@@@@@
 
 .. toctree::
    :maxdepth: 1
 
+   api
    zcml
 
 .. backmatter::
diff --git a/docs/narr/contextfinding.rst b/docs/narr/contextfinding.rst
index 74d9e3cc5..a31d0dc19 100644
--- a/docs/narr/contextfinding.rst
+++ b/docs/narr/contextfinding.rst
@@ -24,9 +24,9 @@ finding` and :term:`view lookup`.
   the :mod:`repoze.bfg` view lookup subsystem is provided with a
   :term:`request`, a :term:`context` and a :term:`view name`.  It is
   then responsible for finding and invoking a :term:`view callable`.
-  A view callable is a specific bit of code that receives the
-  :term:`request` and which returns a :term:`response`, written and
-  registered by the application developer.
+  A view callable is a specific bit of code written and registered by
+  the application developer which receives the :term:`request` and
+  which returns a :term:`response`.
 
 These two subsystems are are used by :mod:`repoze.bfg` serially:
 first, a :term:`context finding` subsystem does its job.  Then the
diff --git a/docs/zcml.rst b/docs/zcml.rst
index be82741aa..995b1bed9 100644
--- a/docs/zcml.rst
+++ b/docs/zcml.rst
@@ -1,7 +1,7 @@
 .. _zcml_directives:
 
 ZCML Directives
-----------------
+===============
 
 :term:`ZCML` is an XML dialect that may be used by a :mod:`repoze.bfg`
 application to perform :term:`declarative configuration`.  Each