Edit.

1 files changed, 47 insertions, 39 deletions

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: