More pass overhaul based on making contextfinding explicit within doc…

…umentation.

docs/authorintro.rst

@@ -34,13 +34,15 @@ will be slightly harder, and it will take a little longer, but you'd
 be hard-pressed to find a better "first language."
 
 Web technology familiarity is assumed in various places within the
-book.  For example, the book describes various interactions in terms
-of the HTTP protocol, but it does not describe how the HTTP protocol
-works in detail.  Like any good framework, though, :mod:`repoze.bfg`
-shields you from needing to know the gory details of web protocols
-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.
+book.  For example, the book doesn't try to define common web-related
+concepts like "URL" or "query string."  Likewise, the book describes
+various interactions in terms of the HTTP protocol, but it does not
+describe how the HTTP protocol works in detail.  Like any good web
+framework, though, :mod:`repoze.bfg` shields you from needing to know
+most of the gory details of web protocols and low-level data
+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.
 
 .. index::
    single: repoze.zope2

docs/index.rst

@@ -43,7 +43,7 @@ Narrative documentation in chapter form explaining how to use
    narr/firstapp
    narr/project
    narr/startup
-   narr/urlmapping
+   narr/contextfinding
    narr/views
    narr/static
    narr/webob

docs/latexindex.rst

@@ -30,7 +30,7 @@ Narrative Documentation
    narr/configuration
    narr/firstapp
    narr/project
-   narr/urlmapping
+   narr/contextfinding
    narr/views
    narr/static
    narr/webob

docs/narr/urlmapping.rst → docs/narr/contextfinding.rst

@@ -1,38 +1,40 @@
 .. index::
-   triple: differences; URL dispatch; traversal
-   pair: mapping; URLs
+   pair: finding; context
 
-.. _urlmapping_chapter:
+.. _contextfinding_chapter:
 
-Mapping URLs to Code
---------------------
+Context Finding
+---------------
 
-In order for a web application to perform any useful action, it needs
-some way of finding and invoking code written by the application
-developer based on parameters present in the :term:`request`.
+In order for a web application to perform any useful action, the web
+framework must provide a mechanism to find and invoke code written by
+the application developer based on parameters present in the
+:term:`request`.
 
-:mod:`repoze.bfg` uses two separate but cooperating subsystems to
-ultimately find and invoke code written by the application developer:
-:term:`context finding` and :term:`view lookup` .
+:mod:`repoze.bfg` uses two separate but cooperating subsystems to find
+and invoke code written by the application developer: :term:`context
+finding` and :term:`view lookup`.
 
-- A :mod:`repoze.bfg` "context finding" subsystem is given a
+- A :mod:`repoze.bfg` :term:`context finding` subsystem is given a
   :term:`request`; it is responsible for finding a :term:`context`
   object and a :term:`view name` based on information present in the
   request.
 
-- The :mod:`repoze.bfg` view lookup subsystem is provided with a
-  :term:`request`, a :term:`context` and a :term:`view name`, and is
-  responsible for finding and invoking a :term:`view callable`.  A
-  view callable is a specific bit of code that receives the
+- Using the context and view name provided by :term:`context finding`,
+  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.
 
-These two subsystems are are used by :mod:`repoze.bfg` serially: a
-:term:`context finding` subsystem does its job, then the result of
-context finding is passed to the :term:`view lookup` subsystem.  The
-view lookup system finds a :term:`view callable` written by an
-application developer, and invokes it.  A view callable returns a
-:term:`response`.  The response is returned to the requesting user.
+These two subsystems are are used by :mod:`repoze.bfg` serially:
+first, a :term:`context finding` subsystem does its job.  Then the
+result of context finding is passed to the :term:`view lookup`
+subsystem.  The view lookup system finds a :term:`view callable`
+written by an application developer, and invokes it.  A view callable
+returns a :term:`response`.  The response is returned to the
+requesting user.
 
 .. sidebar::  What Good is A Context Finding Subsystem?
 
@@ -42,20 +44,21 @@ application developer, and invokes it.  A view callable returns a
    into a single step.  In these systems, a URL can map *directly* to
    a view callable.  This makes them simpler to understand than
    systems which use distinct subsystems to locate a context and find
-   a view.  However, explicitly using a context finding step provides
-   extra flexibility.  For example, it makes it possible to protect
-   your application with declarative context-sensitive instance-level
+   a view.  However, explicitly finding a context provides extra
+   flexibility.  For example, it makes it possible to protect your
+   application with declarative context-sensitive instance-level
    :term:`authorization`, which is not well-supported in frameworks
    that do not provide a notion of a context.
 
-There are two separate context finding subsystems in
-:mod:`repoze.bfg`: :term:`traversal` and :term:`URL dispatch`.  The
-subsystems are documented within this chapter.  They can be used
-separately or they can be combined.
+This chapter documents :term:`context finding`.  There are two
+separate :term:`context finding` subsystems in :mod:`repoze.bfg`:
+:term:`traversal` and :term:`URL dispatch`.  The subsystems are
+documented within this chapter.  They can be used separately or they
+can be combined.
 
-There is only one view lookup subsystem present in :mod:`repoze.bfg`.
-It is not documented within this chapter.  Instead, it is documented
-within :ref:`views_chapter`.
+There is only one :term:`view lookup` subsystem present in
+:mod:`repoze.bfg`.  Where appropriate, within this chapter, we
+describe how view lookup interacts with context finding.
 
 .. toctree::
    :maxdepth: 2

docs/narr/firstapp.rst

@@ -10,10 +10,10 @@ explain in more detail how the application works.
 .. note::
 
    If you're a "theory-first" kind of person, you might choose to read
-   :ref:`urlmapping_chapter` and :ref:`views_chapter` to augment your
-   understanding before diving into the code that follows, but it's
-   not necessary if -- like many programmers -- you're willing to "go
-   with the flow".
+   :ref:`contextfinding_chapter` and :ref:`views_chapter` to augment
+   your understanding before diving into the code that follows, but
+   it's not necessary if -- like many programmers -- you're willing to
+   "go with the flow".
 
 .. _helloworld_imperative:
 

docs/narr/hooks.rst

@@ -163,9 +163,9 @@ Changing the Traverser
 ----------------------
 
 The default :term:`traversal` algorithm that BFG uses is explained in
-:ref:`how_bfg_traverses`.  Though it is rarely necessary, this default
-algorithm can be swapped out selectively for a different traversal
-pattern via configuration.
+:ref:`traversal_algorithm`.  Though it is rarely necessary, this
+default algorithm can be swapped out selectively for a different
+traversal pattern via configuration.
 
 Use an ``adapter`` stanza in your application's ``configure.zcml`` to
 change the default traverser:

docs/narr/introduction.rst

@@ -14,8 +14,8 @@ 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 probably
-won't serve the same set of customers.  However, both the
-ledger-serving and song-serving applications can be written using
+won't serve the same set of customers.  However, both a ledger-serving
+application and a song-serving application might be written using
 :mod:`repoze.bfg` because it is a very general open source Python web
 *framework*.  As a framework, the primary job of :mod:`repoze.bfg` is
 to make it easier for a developer to create arbitrary web
@@ -90,8 +90,8 @@ Openness
   <http://repoze.org/license.html>`_.
 
 This book usually refers to the framework by its full package name,
-:mod:`repoze.bfg`.  However, it is often referred to colloquially as
-just "BFG" (the "repoze-dot" dropped) in conversation.
+:mod:`repoze.bfg`.  However, it is often referred to as just "BFG"
+(the "repoze-dot" dropped) in conversation.
 
 .. index::
    single: Repoze
@@ -181,7 +181,7 @@ as :term:`Django`, :mod:`repoze.bfg` makes no assumptions about which
 persistence mechanisms you should use to build an application.  Zope
 applications are typically reliant on :term:`ZODB`; :mod:`repoze.bfg`
 allows you to build :term:`ZODB` applications, but it has no reliance
-on the ZODB package.  Likewise, :term:`Django` tends to assume that
+on the ZODB software.  Likewise, :term:`Django` tends to assume that
 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.

docs/narr/router.rst

@@ -102,7 +102,6 @@ processing?
 This is a very high-level overview that leaves out various details.
 For more detail about subsystems invoked by the BFG router such as
 traversal, URL dispatch, views, and event processing, see
-:ref:`urlmapping_chapter`, :ref:`traversal_chapter`,
-:ref:`urldispatch_chapter`, :ref:`views_chapter`, and
+:ref:`contextfinding_chapter`, :ref:`views_chapter`, and
 :ref:`events_chapter`.
 

docs/narr/security.rst

@@ -15,7 +15,7 @@ Here's how it works at a high level:
   :term:`context finding`.  A context is located differently depending
   on whether the application uses :term:`traversal` or :term:`URL
   dispatch`, but a context is ultimately found in either case.  See
-  :ref:`urlmapping_chapter` for more information about context
+  :ref:`contextfinding_chapter` for more information about context
   finding.
 
 - A :term:`view callable` is located by :term:`view lookup` using the