Wording changes.

2 files changed, 47 insertions, 39 deletions

diff --git a/docs/narr/extending.rst b/docs/narr/extending.rst
index fee8737f8..93c4fe9d6 100644
--- a/docs/narr/extending.rst
+++ b/docs/narr/extending.rst
@@ -5,21 +5,21 @@ Extending An Existing :mod:`repoze.bfg` Application
 
 If the developer of a :mod:`repoze.bfg` has obeyed certain constraints
 while building the application, a third party should be able to change
-the behavior of that application without touching the actual source
-code that makes up the application.  The behavior of a
+the behavior of that application without needing to modify the actual
+source code that makes up the application.  The behavior of a
 :mod:`repoze.bfg` application that obeys these constraints can be
-*extended* or *changed* without modification.
+*overridden* or *extended* without modification.
 
 Rules for Building An Extensible Application
 --------------------------------------------
 
 There's only one rule you need to obey if you want to build an
-application that is extensible using :mod:`repoze.bfg`: you must not
-use the ``@bfg_view`` decorator (or any other decorator meant to be
-detected via the ZCML ``<scan>`` directive) to associate a view with a
-context.  Instead, you must use :term:`ZCML` for this
-purpose. :term:`ZCML` statements that belong to an application can be
-"overridden" by integrators as necessary, but decorators cannot.
+extensible :mod:`repoze.bfg` application: you must not use the
+``@bfg_view`` decorator or any other decorator meant to be detected
+via the ZCML ``<scan>`` directive.  Instead, you must use :term:`ZCML`
+for the equivalent purpose. :term:`ZCML` statements that belong to an
+application can be "overridden" by integrators as necessary, but
+decorators which perform the same tasks cannot.
 
 It's also often helpful for third party application "extenders" (aka
 "integrators") if the ZCML that composes the configuration for an
@@ -42,10 +42,10 @@ declarations out of the decorators and into :term:`ZCML`.  Once this
 is done, you should be able to extend or modify the application like
 any other.
 
-To extend or change the behavior of an existing application, you will
-need to write some :term:`ZCML`, and perhaps some implementations of
-the types of things you'd like to override (such as views), which are
-referred to within that ZCML.
+To extend or override the behavior of an existing application, you
+will need to write some :term:`ZCML`, and perhaps some implementations
+of the types of things you'd like to override (such as views), which
+are referred to within that ZCML.
 
 The general pattern for extending an application looks something like this:
 
@@ -60,38 +60,44 @@ The general pattern for extending an application looks something like this:
 
 - Change the ``configure.zcml`` in the new package to include the
   original :mod:`repoze.bfg` application's ``configure.zcml`` via an
-  include statement, e.g.  ``<include
-  package="theoriginalapplication"/>``.
+  include statement, e.g.  ``<include package="theoriginalapp"/>``.
+  Alternately, instead of including the "main" ``configure.zcml`` of
+  the original application include only specific ZCML files from the
+  original application using the ``file`` attribute of the
+  ``<include>`` statement, e.g. ``<include package="theoriginalapp"
+  file="views.zcml"/>``.
 
 - On a line in the new package's ``configure.zcml`` file that falls
-  after (XML-ordering-wise) the ``include`` of the original package,
-  put an ``includeOverride`` statement that includes another ZCML file
-  within the new package (for example ``<includeOverride
-  file="overrides.zcml"/>``.
+  after (XML-ordering-wise) the all ``include`` statements of original
+  package ZCML, put an ``includeOverrides`` statement which identifies
+  *another* ZCML file within the new package (for example
+  ``<includeOverrides file="overrides.zcml"/>``.
 
 - Create an ``overrides.zcml`` file within the new package.  The
   statements in the ``overrides.zcml`` file will override any ZCML
   statements made within the original application (such as views).
 
 - Create Python files containing views (and other overridden elements,
-  such as templates) as necessary, and wire these up, either extending
-  or overriding the original view registrations from the base
-  application within the ``overrides.zcml`` file.  The ZCML ``<view>``
-  statements you make which *modify* behavior will usually have the
-  same ``for`` and ``name`` (and ``request_type`` if used) as the
-  original, and will be in a form like::
+  such as templates) as necessary, and wire these up using ZCML
+  registrations within the ``overrides.zcml`` file.  These
+  registrations may extend or override the original view
+  registrations.
+
+  The ZCML ``<view>`` statements you make which *override* application
+  behavior will usually have the same ``for`` and ``name`` (and
+  ``request_type`` if used) as the original.  These ``<view>>``
+  statements will point at "new" view code.  The new view code itself
+  will usually be cut-n-paste copies of view callables from the
+  original application with slight tweaks.  For example::
 
     <view for="theoriginalapplication.models.SomeModel"
           name="theview"
           view=".views.a_view_that_does_something_slightly_different"
      />
 
-  Views which modify the behavior of an application will usually be
-  cut-n-paste copies of view callables from the original application
-  with slight tweaks.
-
-  A similar pattern can be used to extend the application.  Just
-  register a new view against some existing model type.
+  A similar pattern can be used to *extend* the application.  Just
+  register a new view against some existing model type and make sure
+  the URLs it implies are available on some other page rendering.
 
 - Change the Paste ``.ini`` file that starts up the original
   application.  Add a ``configure_zcml`` statement within the
diff --git a/docs/narr/vhosting.rst b/docs/narr/vhosting.rst
index 14b9a2199..4546446be 100644
--- a/docs/narr/vhosting.rst
+++ b/docs/narr/vhosting.rst
@@ -57,14 +57,16 @@ Virtual root support is useful when you'd like to host some model in a
 that does not include the model path itself.  For example, you might
 want to serve the object at the traversal path ``/cms`` as an
 application reachable via ``http://example.com/`` (as opposed to
-``http://example.com/cms``). To specify a virtual root, cause an
-environment variable to be inserted into the WSGI environ named
-``HTTP_X_VHM_ROOT`` with a value that is the absolute pathname to the
-model object in the traversal graph that should behave as the "root"
-model.  As a result, the traversal machinery will respect this value
-during traversal (prepending it to the PATH_INFO before traversal
-starts), and the ``repoze.bfg.url.model_url`` API will generate the
-"correct" virtually-rooted URLs.
+``http://example.com/cms``).
+
+To specify a virtual root, cause an environment variable to be
+inserted into the WSGI environ named ``HTTP_X_VHM_ROOT`` with a value
+that is the absolute pathname to the model object in the traversal
+graph that should behave as the "root" model.  As a result, the
+traversal machinery will respect this value during traversal
+(prepending it to the PATH_INFO before traversal starts), and the
+``repoze.bfg.url.model_url`` API will generate the "correct"
+virtually-rooted URLs.
 
 An example of an Apache ``mod_proxy`` configuration that will host the
 ``/cms`` subobject as ``http://www.example.com/`` using this facility