Fux bigs.

2 files changed, 34 insertions, 28 deletions

diff --git a/docs/glossary.rst b/docs/glossary.rst
index 1dd5fa821..b6e6e6eef 100644
--- a/docs/glossary.rst
+++ b/docs/glossary.rst
@@ -59,13 +59,13 @@ Glossary
   Traversal
     The act of descending "down" a graph of model objects from a root
     model in order to find a :term:`context`.  The :mod:`repoze.bfg`
-    *router* performs traversal of model objects.  See the
+    :term:`router` performs traversal of model objects.  See the
     :ref:`traversal_chapter` chapter for more information.
   Router
     The :term:`WSGI` application created when you start a
     :mod:`repoze.bfg` application.  The router intercepts requests,
     invokes traversal, calls view functions, and returns responses to
-    the WSGI server.
+    the WSGI server on behalf of your :mod:`repoze.bfg` application.
   URL dispatch
     An alternative to graph traversal as a mechanism for locating a
     :term:`context` for a :term:`view`.  When you use :term:`Routes`
diff --git a/docs/narr/startup.rst b/docs/narr/startup.rst
index a0ca8354f..bfb8ab70d 100644
--- a/docs/narr/startup.rst
+++ b/docs/narr/startup.rst
@@ -60,7 +60,7 @@ press ``return`` after running ``paster serve MyProject.ini``.
 #. The application's *constructor* (named by the entry point reference
    or dotted Python name on the ``use=`` line) is passed the key/value
    parameters mentioned within the section in which it's defined.  The
-   constructor is meant to return :term:`router` instance.
+   constructor is meant to return a :term:`router` instance.
 
    For ``repoze.bfg`` applications, the constructor will be a function
    named ``app`` in the ``run.py`` file within the :term:`package` in
@@ -72,14 +72,14 @@ press ``return`` after running ``paster serve MyProject.ini``.
       :linenos:
 
    Note that the constructor function accepts a ``global_config``
-   argument (which are the key/value pairs mentioned in the
-   ``[DEFAULT]`` section of the configuration file.  It also accepts a
-   ``**kw`` argument, which collects arbitrary key/value pairs.  The
-   arbitrary key/value pairs received by this function in ``**kw``
-   will be composed of all the key/value pairs that are present in the
-   ``[app:main]`` section (except for the ``use=`` setting) when this
-   function is called by the :term:`PasteDeploy` framework when you
-   run ``paster serve``.
+   argument (which is a dictionary of key/value pairs mentioned in the
+   ``[DEFAULT]`` section of the configuration file).  It also accepts
+   a ``**kw`` argument, which collects another set of arbitrary
+   key/value pairs.  The arbitrary key/value pairs received by this
+   function in ``**kw`` will be composed of all the key/value pairs
+   that are present in the ``[app:main]`` section (except for the
+   ``use=`` setting) when this function is called by the
+   :term:`PasteDeploy` framework when you run ``paster serve``.
 
    Our generated ``MyProject.ini`` file looks like so:
 
@@ -108,12 +108,15 @@ press ``return`` after running ``paster serve MyProject.ini``.
    ``get_options`` is a function imported from a :mod:`repoze.bfg`
    package which allows the user to pass framework-related (as opposed
    to application-related) options to an application constructor.  It
-   picks off framework-related options from the ``*kw`` dict passed in
-   to the constructor.  We actually use a framework option named
-   ``reload_templates`` in our configuration.  Note that we make no
-   use of this option in our application, but the fact that we use
+   picks off framework-related options from the ``**kw`` dictionary
+   passed in to the constructor.  We actually use a framework option
+   named ``reload_templates`` in our configuration.  Note that we make
+   no use of this option in our application, but the fact that we use
    ``get_options`` to parse the ``*kw`` dict, and subsequently pass
    along the result as the ``options`` argument to ``make_app``.
+   ``reload_templates`` has special meaning to the framework: if it's
+   ``true``, we will cause templates to be automatically reloaded by
+   the application when they are changed.
 
    ``get_root`` is the first argument to ``make_app``, and it is a
    callable that is invoked on every request to retrieve the
@@ -129,26 +132,28 @@ press ``return`` after running ``paster serve MyProject.ini``.
    application, you can pass an optional ``filename=`` paramter to
    make_app (e.g. ``make_app(get_root, myproject,
    filename='meta.zcml', options=options``).  If the filename is
-   absolute, the package is ignored.
+   absolute, the ``package`` argument is ignored.
 
-#. The ``make_app`` function does its work.  It parses the ZCML
-   represented by the application registry file (or may obtain the
-   application registry from a previously cached pickle file,
+#. The ``make_app`` function does its work.  It finds and parses the
+   ZCML represented by the application registry file (or may obtain
+   the application registry from a previously cached pickle file,
    e.g. ``configure.zcml.cache``).  If it fails to parse one or more
-   ZCML files, a ``XMLConfigurationError`` is raised.  If it succeeds,
-   the :term:`application registry` is created, a :term:`router`
-   instance is created, and the router is associated with the
-   application registry.  The router represents your application; the
-   settings in this application registry will be used for your
-   application.
+   ZCML files, a ``XMLConfigurationError`` is raised (or possibly
+   another error if the ZCML file just doesn't exist).  If it
+   succeeds, an :term:`application registry` is created, representing
+   the view registrations (and other registrations) for your
+   application.  A :term:`router` instance is created, and the router
+   is associated with the application registry.  The router represents
+   your application; the settings in the application registry that is
+   created will be used for your application.
 
 #. A ``WSGIApplicationCreatedEvent`` event is emitted (see
    :ref:`events_chapter` for more informations about events).
 
 #. Assuming there were no errors, our ``myproject`` ``app`` function
    returns the router instance created by ``make_app`` back to
-   PasteDeploy.  As far as PasteDeploy is concerned, it is just
-   another WSGI application.
+   PasteDeploy.  As far as PasteDeploy is concerned, it is "just
+   another WSGI application".
 
 #. PasteDeploy starts the WSGI *server* defined within the
    ``[server:main]`` section.  In our case, this is the "CherryPy"
@@ -158,7 +163,8 @@ press ``return`` after running ``paster serve MyProject.ini``.
    threads (``numthreads = 4``), which means it will handle four
    simultaneous requests before needing to put a request in a wait
    queue.  The server code itself is what prints `serving on
-   0.0.0.0:6543 view at http://127.0.0.1:6543``.
+   0.0.0.0:6543 view at http://127.0.0.1:6543``.  The server serves
+   the application.
 
 #.  The application is running.