de-zcml-ify various chapters and move ZCML to the declarative chapter

1 files changed, 5 insertions, 286 deletions

diff --git a/docs/narr/firstapp.rst b/docs/narr/firstapp.rst
index 67dd6b8fb..9be087036 100644
--- a/docs/narr/firstapp.rst
+++ b/docs/narr/firstapp.rst
@@ -17,8 +17,8 @@ explain in more detail how the application works.
 
 .. _helloworld_imperative:
 
-Hello World, Goodbye World (Imperative)
----------------------------------------
+Hello World, Goodbye World
+--------------------------
 
 Here's one of the very simplest :mod:`pyramid` applications,
 configured imperatively:
@@ -369,295 +369,14 @@ Our hello world application is one of the simplest possible
 that it's configured imperatively because the full power of Python is
 available to us as we perform configuration tasks.
 
-.. index::
-   single: helloworld (declarative)
-
-.. _helloworld_declarative:
-
-Hello World, Goodbye World (Declarative)
-----------------------------------------
-
-Another almost entirely equivalent mode of application configuration
-exists named *declarative* configuration.  :mod:`pyramid` can be
-configured for the same "hello world" application "declaratively", if
-so desired.
-
-To do so, first, create a file named ``helloworld.py``:
-
-.. code-block:: python
-   :linenos:
-
-   from pyramid.configuration import Configurator
-   from pyramid.response import Response
-   from paste.httpserver import serve
-
-   def hello_world(request):
-       return Response('Hello world!')
-
-   def goodbye_world(request):
-       return Response('Goodbye world!')
-
-   if __name__ == '__main__':
-       config = Configurator()
-       config.begin()
-       config.load_zcml('configure.zcml')
-       config.end()
-       app = config.make_wsgi_app()
-       serve(app, host='0.0.0.0')
-
-Then create a file named ``configure.zcml`` in the same directory as
-the previously created ``helloworld.py``:
-
-.. code-block:: xml
-   :linenos:
-
-   <configure xmlns="http://pylonshq.com/pyramid">
-
-     <include package="pyramid.includes" />
-
-     <view
-        view="helloworld.hello_world"
-        />
-
-     <view
-       name="goodbye"
-       view="helloworld.goodbye_world"
-       />
-
-   </configure>
-
-This pair of files forms an application functionally equivalent to the
-application we created earlier in :ref:`helloworld_imperative`.  We can run
-it the same way.
-
-.. code-block:: bash
-
-   $ python helloworld.py
-   serving on 0.0.0.0:8080 view at http://127.0.0.1:8080
-
-Let's examine the differences between the code in that section and the code
-above.  In :ref:`helloworld_imperative_appconfig`, we had the following lines
-within the ``if __name__ == '__main__'`` section of ``helloworld.py``:
-
-.. code-block:: python
-   :linenos:
-
-   if __name__ == '__main__':
-       config = Configurator()
-       config.begin()
-       config.add_view(hello_world)
-       config.add_view(goodbye_world, name='goodbye')
-       config.end()
-       app = config.make_wsgi_app()
-       serve(app, host='0.0.0.0')
-
-In our "declarative" code, we've added a call to the
-:meth:`pyramid.configuration.Configurator.load_zcml` method with
-the value ``configure.zcml``, and we've removed the lines which read
-``config.add_view(hello_world)`` and ``config.add_view(goodbye_world,
-name='goodbye')``, so that it now reads as:
-
-.. code-block:: python
-   :linenos:
-
-   if __name__ == '__main__':
-       config = Configurator()
-       config.begin()
-       config.load_zcml('configure.zcml')
-       config.end()
-       app = config.make_wsgi_app()
-       serve(app, host='0.0.0.0')
-
-Everything else is much the same.
-
-The ``config.load_zcml('configure.zcml')`` line tells the configurator
-to load configuration declarations from the ``configure.zcml`` file
-which sits next to ``helloworld.py``.  Let's take a look at the
-``configure.zcml`` file now:
-
-.. code-block:: xml
-   :linenos:
-
-   <configure xmlns="http://pylonshq.com/pyramid">
-
-      <include package="pyramid.includes" />
-
-      <view
-         view="helloworld.hello_world"
-         />
-
-      <view
-         name="goodbye"
-         view="helloworld.goodbye_world"
-         />
-
-   </configure>
-
-We already understand what the view code does, because the application
-is functionally equivalent to the application described in
-:ref:`helloworld_imperative`, but use of :term:`ZCML` is new.  Let's
-break that down tag-by-tag.
-
-The ``<configure>`` Tag
-~~~~~~~~~~~~~~~~~~~~~~~
-
-The ``configure.zcml`` ZCML file contains this bit of XML:
-
-.. code-block:: xml
-   :linenos:
-
-    <configure xmlns="http://pylonshq.com/pyramid">
-
-       <!-- other directives -->
-
-    </configure>
-
-Because :term:`ZCML` is XML, and because XML requires a single root
-tag for each document, every ZCML file used by :mod:`pyramid` must
-contain a ``configure`` container directive, which acts as the root
-XML tag.  It is a "container" directive because its only job is to
-contain other directives.
-
-See also :ref:`configure_directive` and :ref:`word_on_xml_namespaces`.
-
-The ``<include>`` Tag
-~~~~~~~~~~~~~~~~~~~~~
-
-The ``configure.zcml`` ZCML file contains this bit of XML within the
-``<configure>`` root tag:
-
-.. code-block:: xml
-
-   <include package="pyramid.includes" />
-
-This self-closing tag instructs :mod:`pyramid` to load a ZCML file
-from the Python package with the :term:`dotted Python name`
-``pyramid.includes``, as specified by its ``package`` attribute.
-This particular ``<include>`` declaration is required because it
-actually allows subsequent declaration tags (such as ``<view>``, which
-we'll see shortly) to be recognized.  The ``<include>`` tag
-effectively just includes another ZCML file, causing its declarations
-to be executed.  In this case, we want to load the declarations from
-the file named ``configure.zcml`` within the
-:mod:`pyramid.includes` Python package.  We know we want to load
-the ``configure.zcml`` from this package because ``configure.zcml`` is
-the default value for another attribute of the ``<include>`` tag named
-``file``.  We could have spelled the include tag more verbosely, but
-equivalently as:
-
-.. code-block:: xml
-   :linenos:
-
-   <include package="pyramid.includes" 
-            file="configure.zcml"/>
-
-The ``<include>`` tag that includes the ZCML statements implied by the
-``configure.zcml`` file from the Python package named
-:mod:`pyramid.includes` is basically required to come before any
-other named declaration in an application's ``configure.zcml``.  If it
-is not included, subsequent declaration tags will fail to be
-recognized, and the configuration system will generate an error at
-startup.  However, the ``<include package="pyramid.includes"/>``
-tag needs to exist only in a "top-level" ZCML file, it needn't also
-exist in ZCML files *included by* a top-level ZCML file.
-
-See also :ref:`include_directive`.
-
-The ``<view>`` Tag
-~~~~~~~~~~~~~~~~~~
-
-The ``configure.zcml`` ZCML file contains these bits of XML *after* the
-``<include>`` tag, but *within* the ``<configure>`` root tag:
-
-.. code-block:: xml
-   :linenos:
-
-   <view
-     view="helloworld.hello_world"
-     />
-
-   <view
-     name="goodbye"
-     view="helloworld.goodbye_world"
-     />
-
-These ``<view>`` declaration tags direct :mod:`pyramid` to create
-two :term:`view configuration` registrations.  The first ``<view>``
-tag has an attribute (the attribute is also named ``view``), which
-points at a :term:`dotted Python name`, referencing the
-``hello_world`` function defined within the ``helloworld`` package.
-The second ``<view>`` tag has a ``view`` attribute which points at a
-:term:`dotted Python name`, referencing the ``goodbye_world`` function
-defined within the ``helloworld`` package.  The second ``<view>`` tag
-also has an attribute called ``name`` with a value of ``goodbye``.
-
-These effect of the ``<view>`` tag declarations we've put into our
-``configure.zcml`` is functionally equivalent to the effect of lines
-we've already seen in an imperatively-configured application.  We're
-just spelling things differently, using XML instead of Python.
-
-In our previously defined application, in which we added view
-configurations imperatively, we saw this code:
-
-.. ignore-next-block
-.. code-block:: python
-   :linenos:
-
-   config.add_view(hello_world)
-   config.add_view(goodbye_world, name='goodbye')
-
-Each ``<view>`` declaration tag encountered in a ZCML file effectively
-invokes the :meth:`pyramid.configuration.Configurator.add_view`
-method on the behalf of the developer.  Various attributes can be
-specified on the ``<view>`` tag which influence the :term:`view
-configuration` it creates.
-
-Since the relative ordering of calls to
-:meth:`pyramid.configuration.Configurator.add_view` doesn't matter
-(see the sidebar entitled *View Dispatch and Ordering* within
-:ref:`adding_configuration`), the relative order of ``<view>`` tags in
-ZCML doesn't matter either.  The following ZCML orderings are
-completely equivalent:
-
-.. topic:: Hello Before Goodbye
-
-  .. code-block:: xml
-     :linenos:
-
-     <view
-       view="helloworld.hello_world"
-       />
-
-     <view
-       name="goodbye"
-       view="helloworld.goodbye_world"
-       />
-
-.. topic:: Goodbye Before Hello
-
-  .. code-block:: xml
-     :linenos:
-
-     <view
-       name="goodbye"
-       view="helloworld.goodbye_world"
-       />
-
-     <view
-       view="helloworld.hello_world"
-       />
-
-We've now configured a :mod:`pyramid` helloworld application
-declaratively.  More information about this mode of configuration is
-available in :ref:`declarative_configuration` and within
-:ref:`zcml_reference`.
+An example of using *declarative* configuration to perform the same task is
+available within :ref:`declarative_configuration`.
 
 References
 ----------
 
 For more information about the API of a :term:`Configurator` object,
-see :class:`pyramid.configuration.Configurator` .  The equivalent
-ZCML declaration tags are introduced in :ref:`zcml_reference`.
+see :class:`pyramid.configuration.Configurator` .
 
 For more information about :term:`view configuration`, see
 :ref:`views_chapter`.