IForbiddenAppFactory -> IForbiddenResponseFactory.

1 files changed, 23 insertions, 19 deletions

diff --git a/docs/narr/hooks.rst b/docs/narr/hooks.rst
index aefa95046..6428408e8 100644
--- a/docs/narr/hooks.rst
+++ b/docs/narr/hooks.rst
@@ -124,40 +124,44 @@ sample code that implements a minimal NotFound application factory:
    ``debug_notfound`` environment setting is true than it is when it
    is false.
 
-Changing the Forbidden Application
-----------------------------------
+Changing the Forbidden Response
+-------------------------------
 
 When :mod:`repoze.bfg` can't authorize execution of a view based on
-the security policy in use, it creates and invokes a Forbidden WSGI
-application. The application it invokes can be customized by placing
-something like the following ZCML in your ``configure.zcml`` file.
+the security policy in use, it invokes a "forbidden response factory".
+Usually this forbidden response factory is serviced by the currently
+active :term:`security policy`, but it can be overridden as necessary
+by placing something like the following ZCML in your
+``configure.zcml`` file.
 
 .. code-block:: xml
    :linenos:
 
-   <utility provides="repoze.bfg.interfaces.IForbiddenAppFactory"
-            component="helloworld.factories.forbidden_app_factory"/>
+   <utility provides="repoze.bfg.interfaces.IForbiddenResponseFactory"
+            component="helloworld.factories.forbidden_response_factory"/>
 
 Replace ``helloworld.factories.forbidden_app_factory`` with the Python
-dotted name to the WSGI application factory you want to use.  Here's
-some sample code that implements a minimal Unauthorized application
-factory:
+dotted name to the forbidden response factory you want to use.  The
+response factory must accept two parameters: ``context`` and
+``request``.  The ``context`` is the context found by the router when
+the view invocation was denied.  The ``request`` is the current
+:term:`request` representing the denied action.  Here's some sample
+code that implements a minimal forbidden response factory:
 
 .. code-block:: python
 
    from repoze.bfg.chameleon_zpt import render_template_to_response
 
-   def forbidden_app_factory(context, request):
+   def forbidden_response_factory(context, request):
        return render_template_to_response('templates/login_form.pt')
 
-.. note:: When an Forbidden application factory is invoked, it is
-   passed the WSGI environ and the WSGI ``start_response`` handler by
-   :mod:`repoze.bfg`.  Within the WSGI environ will be a key named
-   ``repoze.bfg.message`` that has a value explaining why the action
-   was forbidden.  This error will be different when the
-   ``debug_authorization`` environment setting is true than it is when
-   it is false.  A WebOb ``Response`` object is a valid WSGI
-   application, by the way.
+.. note:: When an forbidden response factory is invoked, it is passed
+   the request as the second argument.  An attribute of the request is
+   ``environ``, which is the WSGI environment.  Within the WSGI
+   environ will be a key named ``repoze.bfg.message`` that has a value
+   explaining why the current view invocation was forbidden.  This
+   error will be different when the ``debug_authorization``
+   environment setting is true than it is when it is false.
 
 .. warning:: the default forbidden application factory sends a
    response with a ``401 Unauthorized`` status code for backwards