simplify

2 files changed, 23 insertions, 26 deletions

diff --git a/docs/glossary.rst b/docs/glossary.rst
index 0a1c363f4..3fa2b0261 100644
--- a/docs/glossary.rst
+++ b/docs/glossary.rst
@@ -592,8 +592,9 @@ Glossary
      declaration` required by your application.
 
    declarative configuration
-     The configuration mode in which you use :term:`ZCML` to make a set of
-     :term:`configuration declaration` statements.  See :term:`pyramid_zcml`.
+     The configuration mode in which you use the combination of
+     :term:`configuration decorator` decorations and a :term:`scan` to
+     configure your Pyramid application.
 
    Not Found view
       An :term:`exception view` invoked by :app:`Pyramid` when the
diff --git a/docs/narr/configuration.rst b/docs/narr/configuration.rst
index 6360dc574..4c2870562 100644
--- a/docs/narr/configuration.rst
+++ b/docs/narr/configuration.rst
@@ -23,6 +23,10 @@ standardized ways that code gets plugged into a deployment of the framework
 itself.  When you plug code into the :app:`Pyramid` framework, you are
 "configuring" :app:`Pyramid` to create a particular application.
 
+There are two ways to configure a :app:`Pyramid` application:
+:term:`imperative configuration` and :term:`declarative configuration`.  Both
+are described below.
+
 .. index::
    single: imperative configuration
 
@@ -31,8 +35,9 @@ itself.  When you plug code into the :app:`Pyramid` framework, you are
 Imperative Configuration
 ------------------------
 
-Here's one of the simplest :app:`Pyramid` applications, configured
-imperatively:
+"Imperative configuration" just means configuration done by Python
+statements, one after the next.  Here's one of the simplest :app:`Pyramid`
+applications, configured imperatively:
 
 .. code-block:: python
    :linenos:
@@ -64,19 +69,17 @@ including conditionals, can be employed in this mode of configuration.
 
 .. _decorations_and_code_scanning:
 
-Configuration Decorations and Code Scanning
--------------------------------------------
+Declarative Configuration
+-------------------------
 
-A different mode of configuration gives more *locality of reference* to a
-:term:`configuration declaration`.  It's sometimes painful to have all
-configuration done in imperative code, because often the code for a single
-application may live in many files.  If the configuration is centralized in
-one place, you'll need to have at least two files open at once to see the
-"big picture": the file that represents the configuration, and the file that
-contains the implementation objects referenced by the configuration.  To
-avoid this, :app:`Pyramid` allows you to insert :term:`configuration
-decoration` statements very close to code that is referred to by the
-declaration itself.  For example:
+It's sometimes painful to have all configuration done by imperative code,
+because often the code for a single application may live in many files.  If
+the configuration is centralized in one place, you'll need to have at least
+two files open at once to see the "big picture": the file that represents the
+configuration, and the file that contains the implementation objects
+referenced by the configuration.  To avoid this, :app:`Pyramid` allows you to
+insert :term:`configuration decoration` statements very close to code that is
+referred to by the declaration itself.  For example:
 
 .. code-block:: python
    :linenos:
@@ -135,6 +138,9 @@ the scanner, a set of calls are made to a :term:`Configurator` on your
 behalf: these calls replace the need to add imperative configuration
 statements that don't live near the code being configured.
 
+The combination of :term:`configuration decoration` and the invocation of a
+:term:`scan` is collectively known as :term:`declarative configuration`.
+
 In the example above, the scanner translates the arguments to
 :class:`~pyramid.view.view_config` into a call to the
 :meth:`pyramid.config.Configurator.add_view` method, effectively:
@@ -145,13 +151,3 @@ In the example above, the scanner translates the arguments to
 
    config.add_view(hello)
 
-Declarative Configuration
--------------------------
-
-A third mode of configuration can be employed when you create a
-:app:`Pyramid` application named *declarative configuration*.  This mode uses
-an XML language known as :term:`ZCML` to represent configuration statements
-rather than Python.  ZCML is not built-in to Pyramid, but almost everything
-that can be configured imperatively can also be configured via ZCML if you
-install the :term:`pyramid_zcml` package.
-