Roles, refresh.

1 files changed, 46 insertions, 29 deletions

diff --git a/docs/tutorials/bfgwiki/basiclayout.rst b/docs/tutorials/bfgwiki/basiclayout.rst
index d373624de..84f6e493e 100644
--- a/docs/tutorials/bfgwiki/basiclayout.rst
+++ b/docs/tutorials/bfgwiki/basiclayout.rst
@@ -17,9 +17,9 @@ directory as a Python package.
 Configuration With ``configure.zcml``
 --------------------------------------
 
-:mod:`repoze.bfg` uses a markup language syntactically the same as
-Zope's implementation of :term:`ZCML`, but using a different default
-XML namespace.  Our sample ZCML file looks like the following:
+The ``bfg_zodb`` template uses :term:`ZCML` to perform system
+configuration.  The ZCML file generated by the template looks like the
+following:
 
    .. literalinclude:: src/basiclayout/tutorial/configure.zcml
       :linenos:
@@ -56,10 +56,11 @@ XML namespace.  Our sample ZCML file looks like the following:
 Content Models with ``models.py``
 ---------------------------------
 
-:mod:`repoze.bfg` often uses the word *model* when talking about
-content resources arranged in a hierarchical *object graph*.  The
-``models.py`` file is where the ``bfg_zodb`` Paster template put the
-classes that implement our models.
+:mod:`repoze.bfg` often uses the word :term:`model` when talking about
+content resources arranged in the hierarchical *object graph*
+consulted by :term:`traversal`.  The ``models.py`` file is where the
+``bfg_zodb`` Paster template put the classes that implement our model
+objects.
 
 Here is the source for ``models.py``:
 
@@ -67,11 +68,14 @@ Here is the source for ``models.py``:
       :linenos:
       :language: py
 
-#. *Lines 3-4*.  The ``MyModel`` class we referred to in the ZCML is
-   implemented here.  It is persistent (via PersistentMapping).  The
+#. *Lines 3-4*.  The ``MyModel`` class we referred to in the ZCML file
+   named ``configure.zcml`` is implemented here.  Instances of this
+   class will be capable of being persisted in :term:`ZODB` because
+   the class inherits from the
+   :class:`persistint.mapping.PersistentMapping` class.  The
    ``__parent__`` and ``__name__`` are important parts of the
-   traversal protocol.  By default, have these as ``None`` indicating
-   that this is the :term:`root` object.
+   :term:`traversal` protocol.  By default, have these as ``None``
+   indicating that this is the :term:`root` object.
 
 #. *Lines 6-12*.  ``appmaker`` is used to return the *application
    root* object.  It is called on *every request* to the
@@ -87,31 +91,44 @@ Here is the source for ``models.py``:
 App Startup with ``run.py``
 ---------------------------
 
-How does a :mod:`repoze.bfg` application start up?  When you run under
-``paster`` using the ``tutorial.ini`` generated config file, the
-application area points at an entry point.  Our entry point happens to
-be in ``run.py`` and its ``app`` function:
+When you run the application using the ``paster`` command using the
+``tutorial.ini`` generated config file, the application configuration
+points at an Setuptools *entry point* described as
+``egg:tutorial#app``.  In our application, because the application's
+``setup.py`` file says so, this entry point happens to be the ``app``
+function within the file named ``run.py``:
 
    .. literalinclude:: src/basiclayout/tutorial/run.py
       :linenos:
       :language: py
 
-#. *Line 11*.  After importing our application, get the ``appmaker``
-   function described above.
+#. *Lines 1-3*.  Perform some dependency imports.
 
-#. *Line 12*. Get the ZODB configuration from the ``tutorial.ini``
-   file's ``[app:main]`` section.  This will be a URI (something like
-   ``file:///path/to/Data.fs``).
+#. *Line 11*. Get the ZODB configuration from the ``tutorial.ini``
+   file's ``[app:main]`` section represented by the ``settings``
+   dictionary passed to our ``app`` function.  This will be a URI
+   (something like ``file:///path/to/Data.fs``).
 
-#. Line *16*. We create a "finder" object using the
-   ``PersistentApplicationFinder`` helper class, passing it the ZODB
-   URI and our appmaker.
+#. Line *14*. We create a "finder" object using the
+   :class:`repoze.zodbconn.finder.PersistentApplicationFinder` helper
+   class, passing it the ZODB URI and the "appmaker" we've imported
+   from ``models.py``.
 
-#. *Lines 17 - 18*.  We create a :term:`root factory` using the finder.
+#. *Lines 15 - 16*.  We create a :term:`root factory` which uses the
+   finder to return a ZODB root object.
 
-#. Line *19*.  We construct a :term:`Configurator` with a
-   :term:`root factory` and the settings keywords parsed by
-   PasteDeploy.  The root factory is named ``get_root``.  We then use
-   the ``make_wsgi_app`` method of the :term:`Configurator` to return
-   a :term:`WSGI` application.
+#. Line *17*.  We construct a :term:`Configurator` with a :term:`root
+   factory` and the settings keywords parsed by PasteDeploy.  The root
+   factory is named ``get_root``.
+
+# *Lines 18-20*.  Begin configuration using the
+   :meth:`repoze.bfg.configuration.Configurator.begin` method, load
+   the ``configure.zcml`` file from our package using the
+   :meth:`repoze.bfg.configuration.Configurator.load_zcml` method, and
+   end configuration using the
+   :meth:`repoze.bfg.configuration.Configurator.end` method.
+
+# *Line 21*.  Use the
+   :meth:`repoze.bfg.configuration.Configurator.make_wsgi_app` method
+   to return a :term:`WSGI` application.