Merge remote-tracking branch 'refs/remotes/Pylons/master'

1 files changed, 83 insertions, 86 deletions

diff --git a/docs/narr/configuration.rst b/docs/narr/configuration.rst
index 6360dc574..cde166b21 100644
--- a/docs/narr/configuration.rst
+++ b/docs/narr/configuration.rst
@@ -3,25 +3,26 @@
 
 .. _configuration_narr:
 
-Application Configuration 
+Application Configuration
 =========================
 
-Each deployment of an application written using :app:`Pyramid` implies a
-specific *configuration* of the framework itself.  For example, an
-application which serves up MP3 files for your listening enjoyment might plug
-code into the framework that manages song files, while an application that
-manages corporate data might plug in code that manages accounting
-information.  The way in which code is plugged in to :app:`Pyramid` for a
-specific application is referred to as "configuration".
-
-Most people understand "configuration" as coarse settings that inform the
-high-level operation of a specific application deployment.  For instance,
-it's easy to think of the values implied by a ``.ini`` file parsed at
-application startup time as "configuration".  :app:`Pyramid` extends this
-pattern to application development, using the term "configuration" to express
-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.
+Most people already understand "configuration" as settings that influence the
+operation of an application.  For instance, it's easy to think of the values in
+a ``.ini`` file parsed at application startup time as "configuration". However,
+if you're reasonably open-minded, it's easy to think of *code* as configuration
+too.  Since Pyramid, like most other web application platforms, is a
+*framework*, it calls into code that you write (as opposed to a *library*,
+which is code that exists purely for you to call).  The act of plugging
+application code that you've written into :app:`Pyramid` is also referred to
+within this documentation as "configuration"; you are configuring
+:app:`Pyramid` to call the code that makes up your application.
+
+.. seealso::
+   For information on ``.ini`` files for Pyramid applications see the
+   :ref:`startup_chapter` chapter.
+
+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,13 +32,14 @@ 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:
 
-   from paste.httpserver import serve
+   from wsgiref.simple_server import make_server
    from pyramid.config import Configurator
    from pyramid.response import Response
 
@@ -48,14 +50,15 @@ imperatively:
        config = Configurator()
        config.add_view(hello_world)
        app = config.make_wsgi_app()
-       serve(app, host='0.0.0.0')
+       server = make_server('0.0.0.0', 8080, app)
+       server.serve_forever()
 
 We won't talk much about what this application does yet.  Just note that the
 "configuration' statements take place underneath the ``if __name__ ==
 '__main__':`` stanza in the form of method calls on a :term:`Configurator`
-object (e.g. ``config.add_view(...)``).  These statements take place one
-after the other, and are executed in order, so the full power of Python,
-including conditionals, can be employed in this mode of configuration.
+object (e.g., ``config.add_view(...)``).  These statements take place one after
+the other, and are executed in order, so the full power of Python, including
+conditionals, can be employed in this mode of configuration.
 
 .. index::
    single: view_config
@@ -64,19 +67,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:
@@ -88,70 +89,66 @@ declaration itself.  For example:
    def hello(request):
        return Response('Hello')
 
-The mere existence of configuration decoration doesn't cause any
-configuration registration to be performed.  Before it has any effect on the
-configuration of a :app:`Pyramid` application, a configuration decoration
-within application code must be found through a process known as a
-:term:`scan`.
+The mere existence of configuration decoration doesn't cause any configuration
+registration to be performed.  Before it has any effect on the configuration of
+a :app:`Pyramid` application, a configuration decoration within application
+code must be found through a process known as a :term:`scan`.
 
 For example, the :class:`pyramid.view.view_config` decorator in the code
-example above adds an attribute to the ``hello`` function, making it
-available for a :term:`scan` to find it later.
-
-A :term:`scan` of a :term:`module` or a :term:`package` and its subpackages
-for decorations happens when the :meth:`pyramid.config.Configurator.scan`
-method is invoked: scanning implies searching for configuration declarations
-in a package and its subpackages.  For example:
-
-.. topic:: Starting A Scan
-
-   .. code-block:: python
-      :linenos:
-
-      from paste.httpserver import serve
-      from pyramid.response import Response
-      from pyramid.view import view_config
-     
-      @view_config()
-      def hello(request):
-          return Response('Hello')
-
-      if __name__ == '__main__':
-          from pyramid.config import Configurator
-          config = Configurator()
-          config.scan()
-          app = config.make_wsgi_app()
-          serve(app, host='0.0.0.0')
+example above adds an attribute to the ``hello`` function, making it available
+for a :term:`scan` to find it later.
+
+A :term:`scan` of a :term:`module` or a :term:`package` and its subpackages for
+decorations happens when the :meth:`pyramid.config.Configurator.scan` method is
+invoked: scanning implies searching for configuration declarations in a package
+and its subpackages.  For example:
+
+.. code-block:: python
+   :linenos:
+
+   from wsgiref.simple_server import make_server
+   from pyramid.config import Configurator
+   from pyramid.response import Response
+   from pyramid.view import view_config
+
+   @view_config()
+   def hello(request):
+       return Response('Hello')
+
+   if __name__ == '__main__':
+       config = Configurator()
+       config.scan()
+       app = config.make_wsgi_app()
+       server = make_server('0.0.0.0', 8080, app)
+       server.serve_forever()
 
 The scanning machinery imports each module and subpackage in a package or
-module recursively, looking for special attributes attached to objects
-defined within a module.  These special attributes are typically attached to
-code via the use of a :term:`decorator`.  For example, the
+module recursively, looking for special attributes attached to objects defined
+within a module.  These special attributes are typically attached to code via
+the use of a :term:`decorator`.  For example, the
 :class:`~pyramid.view.view_config` decorator can be attached to a function or
 instance method.
 
-Once scanning is invoked, and :term:`configuration decoration` is found by
-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.
+Once scanning is invoked, and :term:`configuration decoration` is found by 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:
 
-.. ignore-next-block
 .. code-block:: python
-   :linenos:
 
    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.
+Summary
+-------
 
+There are two ways to configure a :app:`Pyramid` application: declaratively and
+imperatively.  You can choose the mode with which you're most comfortable; both
+are completely equivalent.  Examples in this documentation will use both modes
+interchangeably.