Edit.

8 files changed, 104 insertions, 77 deletions

diff --git a/docs/api/paster.rst b/docs/api/paster.rst
index 52b3048c1..66049ac64 100644
--- a/docs/api/paster.rst
+++ b/docs/api/paster.rst
@@ -3,6 +3,11 @@
 :mod:`repoze.bfg.paster`
 ---------------------------
 
-.. automodule:: repoze.bfg.paster
+.. module:: repoze.bfg.paster
 
-  .. autofunction:: get_app(config_file, name)
+.. function:: get_app(config_file, name)
+
+    Return the WSGI application named ``name`` in the PasteDeploy
+    config file ``config_file``.
+
+     
diff --git a/docs/api/template.rst b/docs/api/template.rst
index 026f1673a..763dc9dfe 100644
--- a/docs/api/template.rst
+++ b/docs/api/template.rst
@@ -55,6 +55,3 @@ statement, e.g.:
 
   .. autofunction:: render_template_to_response
 
-.. note:: For backwards compatibility purposes, these functions may
-          also be imported from ``repoze.bfg.template``.
-
diff --git a/docs/glossary.rst b/docs/glossary.rst
index c8e978bd8..08844c953 100644
--- a/docs/glossary.rst
+++ b/docs/glossary.rst
@@ -45,10 +45,12 @@ Glossary
     used; in its place is a dot.
   View
     A "view" is a callable which returns a response object.  It should
-    accept two values: :term:`context` and :term:`request`.  A view is
-    the primary mechanism by which a developer writes user interface
-    code within :mod:`repoze.bfg`.  See :ref:`views_chapter` for more
-    information about :mod:`repoze.bfg` views.
+    accept two values: :term:`context` and :term:`request`.  An
+    alternate calling convention allows a view to be defined as a a
+    callable which only accepts a single ``request`` argument.  A view
+    is the primary mechanism by which a developer writes user
+    interface code within :mod:`repoze.bfg`.  See :ref:`views_chapter`
+    for more information about :mod:`repoze.bfg` views.
   View name
     The "URL name" of a view, e.g ``index.html``.  If a view is
     configured without a name, its name is considered to be the empty
@@ -61,9 +63,11 @@ Glossary
   Model
     An object representing data in the system.  If :mod:`traversal` is
     used, a model is a node in the object graph traversed by the
-    system.  If :mod:`url dispatch` is used, a model is generated for
-    each request.  A model instance becomes the :term:`context` of a
-    :term:`view`.
+    system.  When traversal is used, a model instance becomes the
+    :term:`context` of a :term:`view`.  If :mod:`url dispatch` is
+    used, a single :term:`context` (which isn't really a model,
+    because it contains no data except security elements) is generated
+    for each request and is used as the context of a view.
   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`
@@ -87,7 +91,7 @@ Glossary
     :term:`URL dispatch` based on URL data; if it's found via
     traversal, it's usually a :term:`model` object that is part of an
     object graph; if it's found via :term:`URL dispatch`, it's a
-    manufactured context object that contains routing information.  A
+    manufactured context object that contains security information.  A
     context becomes the subject of a :term:`view`, and typically has
     security information attached to it.  See the
     :ref:`traversal_chapter` chapter and the
@@ -248,6 +252,10 @@ Glossary
     graph traversal when deciding which *view* should be called.  See
     :ref:`urldispatch_chapter` for more information about Routes integration 
     in bfg.
+  Route
+    A single pattern matched by the :term:`Routes` subsystem, which
+    generally resolves to a :term:`root factory` (and then ultimately
+    a :term:`view`).  See also :term:`url dispatch`.
   ZCML
     `Zope Configuration Markup Language
     <http://www.muthukadan.net/docs/zca.html#zcml>`_, the XML dialect
@@ -362,8 +370,9 @@ Glossary
     root factory to :mod:`repoze.bfg` within a call to
     ``repoze.bfg.router.make_app``; however, an application's root
     factory may be passed to ``make_app`` as ``None``, in which case
-    the application performs no graph traversal and uses :term:`URL
-    dispatch` for all URL-to-view code mappings.
+    the application uses a default root object (this pattern is often
+    used in application which use :term:`URL dispatch` for all
+    URL-to-view code mappings).
   SQLAlchemy
     `SQLAlchemy' <http://www.sqlalchemy.org/>`_ is an object
     relational mapper used in tutorials within this documentation.
diff --git a/docs/narr/views.rst b/docs/narr/views.rst
index 296ed674f..2b465b1d1 100644
--- a/docs/narr/views.rst
+++ b/docs/narr/views.rst
@@ -103,7 +103,7 @@ following types work as views in this style:
           return Response('OK')
 
 #. Arbitrary callables that have a ``__call__`` method that accepts
-  ``self, request``, e.g.::
+   ``self, request``, e.g.::
 
       from webob import Response
 
diff --git a/docs/tutorials/bfgwiki2/authorization.rst b/docs/tutorials/bfgwiki2/authorization.rst
index 9988602d5..4ee4e6ac4 100644
--- a/docs/tutorials/bfgwiki2/authorization.rst
+++ b/docs/tutorials/bfgwiki2/authorization.rst
@@ -16,10 +16,14 @@ to our application.
 Adding A Root Factory
 ---------------------
 
-We're going to start to use a custom *root factory* within our
-``run.py`` file in order to be able to attach security declarations to
-a :term:`context` object.  When we do this, we can begin to make use
-of the declarative security features of :mod:`repoze.bfg`.
+We're going to start to use a custom :term:`root factory` within our
+``run.py`` file.  The objects generated by the root factory will be
+used as the :term:`context` of each of request to our application.  In
+order for BFG declarative security to work properly, the context
+object generated during a request must be decorated with security
+declarations; when we begin to use a custom root factory to generate
+our contexts, we can begin to make use of the declarative security
+features of :mod:`repoze.bfg`.
 
 Let's modify our ``run.py``, passing in a :term:`root factory` as the
 first argument to ``repoze.bfg.router.make_app``.  We'll point it at a
@@ -32,25 +36,25 @@ statements to your ``models.py`` file:
    from repoze.bfg.security import Everyone
 
    class RootFactory(object):
-    __acl__ = [ (Allow, Everyone, 'view'), (Allow, 'editor', 'edit') ]
-    def __init__(self, environ):
-        self.__dict__.update(environ['bfg.routes.matchdict'])
-
-Defining a root factory allows us to use declarative security features
-of :mod:`repoze.bfg`.  The ``RootFactory`` class we added will be used
-to construct each of the ``context`` objects.  The context is attached
-to our request as the ``context`` attribute.  All of our ``context``
-objects will possess an ``__acl__`` attribute that allows "Everyone"
-(a special principal) to view all pages, while allowing only a user
-named ``editor`` to edit and add pages.  The ``__acl__`` attribute
-attached to a context is interpreted specially by :mod:`repoze.bfg` as
-an access control list during view execution.  See
-:ref:`assigning_acls` for more information about what an :term:`ACL`
-represents.
+       __acl__ = [ (Allow, Everyone, 'view'), (Allow, 'editor', 'edit') ]
+       def __init__(self, environ):
+           self.__dict__.update(environ['bfg.routes.matchdict'])
+
+The ``RootFactory`` class we've just added will be used by BFG to
+construct a ``context`` object.  The context is attached to our
+request as the ``context`` attribute.
+
+All of our context objects will possess an ``__acl__`` attribute that
+allows "Everyone" (a special principal) to view all pages, while
+allowing only a user named ``editor`` to edit and add pages.  The
+``__acl__`` attribute attached to a context is interpreted specially
+by :mod:`repoze.bfg` as an access control list during view execution.
+See :ref:`assigning_acls` for more information about what an
+:term:`ACL` represents.
 
 .. note: Although we don't use the functionality here, the ``factory``
-   used to create route contexts may differ per-route instead of
-   globally via a ZCML directive.  See the ``factory`` attribute in
+   used to create route contexts may differ per-route as opposed to
+   globally.  See the ``factory`` attribute in
    :ref:`route_zcml_directive` for more info.
 
 Configuring a ``repoze.bfg`` Authentication Policy
@@ -71,22 +75,25 @@ the policy, and pass it as the ``authentication_policy`` argument to
 the ``make_app`` function.  The first positional argument of an
 ``AuthTktAuthenticationPolicy`` is a secret used to encrypt cookie
 data.  Its second argument ("callback") should be a callable that
-accepts a userid.  If the userid exists in the system, the callback
-should return a sequence of group identifiers (or an empty sequence if
-the user isn't a member of any groups).  If the userid *does not*
-exist in the system, the callback should return ``None``.  We'll use
-"dummy" data to represent user and groups sources.
-
-We'll also use the opportunity to pass our ``RootFactory`` in as the
-first argument to ``make_app``.  When we're done, your application's
-``run.py`` will look like this.
+accepts a userid (usually a string).  If the userid exists in the
+system, the callback should return a sequence of group identifiers (or
+an empty sequence if the user isn't a member of any groups).  If the
+userid *does not* exist in the system, the callback should return
+``None``.  We'll use "dummy" data to represent user and groups sources
+within ``run.py``.  In a "real" application this information would
+almost certainly come from some database.
+
+We'll also use the opportunity to pass the ``RootFactory`` we created
+in the step above in as the first argument to ``make_app``.  When
+we're done, your application's ``run.py`` will look like this.
 
 .. literalinclude:: src/authorization/tutorial/run.py
    :linenos:
    :language: python
 
-BFG's ``make_app`` callable also can accept an authorization policy
-parameter.  We don't need to specify one, we'll use the default.
+BFG's ``make_app`` callable also can accept an "authorization_policy"
+parameter.  We don't need to specify one, because we'll be using the
+default; it is the policy that scans the context for ACLs.
 
 Adding Login and Logout Views
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -160,13 +167,14 @@ Changing ``configure.zcml``
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 Change your application's ``configure.zcml`` to add a ``forbidden``
-stanza which points at our login view.  This configures our login view
-to show up when BFG detects that a view invocation can not be
-authorized.  Also, add ``permission`` attributes with the value
-``edit`` to the ``edit_page`` and ``add_page`` routes.  This indicates
-that the views which these routes reference cannot be invoked without
-the authenticated user possessing the ``edit`` permission.  When
-you're done, your ``configure.zcml`` will look like so:
+stanza which points at our login view.  This configures our newly
+created login view to show up when BFG detects that a view invocation
+can not be authorized.  Also, add ``permission`` attributes with the
+value ``edit`` to the ``edit_page`` and ``add_page`` routes.  This
+indicates that the views which these routes reference cannot be
+invoked without the authenticated user possessing the ``edit``
+permission with respect to the current context.  When you're done,
+your ``configure.zcml`` will look like so:
 
 .. literalinclude:: src/authorization/tutorial/configure.zcml
    :linenos:
diff --git a/docs/tutorials/bfgwiki2/background.rst b/docs/tutorials/bfgwiki2/background.rst
index 097298d1b..934fbcd42 100644
--- a/docs/tutorials/bfgwiki2/background.rst
+++ b/docs/tutorials/bfgwiki2/background.rst
@@ -13,6 +13,6 @@ To code along with this tutorial, the developer will need a UNIX
 machine with development tools (Mac OS X with XCode, any Linux or BSD
 variant, etc) *or* he will need a Windows system of any kind.
 
-This tutorial is known to work under :mod:`repoze.bfg` version 0.9.
+This tutorial is known to work under :mod:`repoze.bfg` version 1.0.
 
 Have fun!
diff --git a/docs/tutorials/bfgwiki2/definingmodels.rst b/docs/tutorials/bfgwiki2/definingmodels.rst
index 0ba2b6f5d..5e9078ce8 100644
--- a/docs/tutorials/bfgwiki2/definingmodels.rst
+++ b/docs/tutorials/bfgwiki2/definingmodels.rst
@@ -4,7 +4,7 @@ Defining Models
 
 The first change we'll make to our bone-stock paster-generated
 application will be to define a :term:`model` constructor representing
-a wiki page.   We'll do this inside our ``models.py`` file.
+a wiki page.  We'll do this inside our ``models.py`` file.
 
 Making Edits to ``models.py``
 -----------------------------
diff --git a/docs/tutorials/bfgwiki2/definingviews.rst b/docs/tutorials/bfgwiki2/definingviews.rst
index df19a21c2..515090e91 100644
--- a/docs/tutorials/bfgwiki2/definingviews.rst
+++ b/docs/tutorials/bfgwiki2/definingviews.rst
@@ -4,9 +4,18 @@ Defining Views
 
 Views in a :term:`url dispatch` -based BFG application are typically
 simple Python functions that accept a single parameter:
-::term:`request`.  A view is assumed to return a :term:`response`
+:term:`request`.  A view is assumed to return a :term:`response`
 object.
 
+.. note:: A BFG view can also be defined as callable which accepts
+   *two* arguments: a :term:`context` and ` :term:`request`.  You'll
+   see that two-argument pattern used in other BFG tutorials and
+   applications.  Either calling convention will work in any
+   application.  In :term:`url dispatch` based applications, however,
+   the context object is rarely used in the view body itself, so
+   within this tutorial we define views as callables that accept only
+   a request to avoid the noise.
+
 The request passed to every view that is called as the result of a
 route match has an attribute named ``matchdict`` that contains the
 elements placed into the URL by the ``path`` of a ``route`` statement.
@@ -19,13 +28,12 @@ request passed to the view would have a ``one`` key withe the value
 Declaring Dependencies in Our ``setup.py`` File
 ===============================================
 
-Our application will depend on packages which are not dependencies of
-the original "tutorial" application as it was generated by the
-``paster create`` command.  We'll add these dependencies to our
-``tutorial`` package's ``setup.py`` file by assigning these
-dependencies to both the ``install_requires`` and the
-``tests_require`` parameters to the ``setup`` function.  In
-particular, we require the ``docutils`` package.
+The view code in our application will depend a package which is not a
+dependency of the original "tutorial" application as it was generated
+by the ``paster create`` command.  We need to add a dependency on the
+``docutils`` package to our ``tutorial`` package's ``setup.py`` file
+by assigning this dependency to the ``install_requires`` parameter in
+the ``setup`` function.
 
 Our resulting ``setup.py`` should look like so:
 
@@ -36,15 +44,16 @@ Our resulting ``setup.py`` should look like so:
 Adding View Functions
 =====================
 
-We'll get rid of our ``my_view`` view in our ``views.py`` file.  It's
-only an example and isn't relevant to our application.
+We'll get rid of our ``my_view`` view function in our ``views.py``
+file.  It's only an example and isn't relevant to our application.
 
 Then we're going to add four :term:`view` functions to our
 ``views.py`` module.  One view (named ``view_wiki``) will display the
 wiki itself (it will answer on the root URL), another named
 ``view_page`` will display an individual page, another named
 ``add_page`` will allow a page to be added, and a final view named
-``edit_page`` will allow a page to be edited.
+``edit_page`` will allow a page to be edited.  We'll describe each one
+briefly and show the resulting ``views.py`` file afterwards.
 
 .. note::
 
@@ -67,7 +76,6 @@ API to construct a URL to the ``FrontPage`` page
 (e.g. ``http://localhost:6543/FrontPage``), and will use it as the
 "location" of the HTTPFound response, forming an HTTP redirect.
 
-
 The ``view_page`` view function
 -------------------------------
 
@@ -236,8 +244,8 @@ Mapping Views to URLs in ``configure.zcml``
 ===========================================
 
 The ``configure.zcml`` file contains ``route`` declarations (and a
-lone ``view`` declaration) which serve to map URLs (via :term:`url
-dispatch`) to view functions.  First, we’ll get rid of the existing
+lone ``view`` declaration) which serve to map URLs via :term:`url
+dispatch` to view functions.  First, we’ll get rid of the existing
 ``route`` created by the template using the name ``home``. It’s only
 an example and isn’t relevant to our application. We'll leave the
 static ``view`` declaration as it is, since we are going to use it to
@@ -292,12 +300,12 @@ commits and aborts of our database connection in view code.
 Adding an Element to the Pipeline
 ---------------------------------
 
-Let's add a piece of middleware to the WSGI pipeline.
-"egg:Paste#evalerror" middleware which displays debuggable errors in
-the browser while you're developing (not recommeded for deployment).
-Let's insert evalerror into the pipeline right above
-"egg:repoze.tm2#tm", making our resulting ``tutorial.ini`` file look
-like so:
+Let's add a piece of middleware to the WSGI pipeline.  We'll add
+``egg:Paste#evalerror`` middleware which displays debuggable errors in
+the browser while you're developing (this is *not* recommeded for
+deployment as it is a security risk).  Let's insert evalerror into the
+pipeline right above "egg:repoze.tm2#tm", making our resulting
+``tutorial.ini`` file look like so:
 
 .. literalinclude:: src/views/tutorial.ini
    :linenos: