Edit.

1 files changed, 28 insertions, 20 deletions

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: