Audit grammar in bfgwik2 tutorial.

1 files changed, 36 insertions, 31 deletions

diff --git a/docs/tutorials/bfgwiki2/definingviews.rst b/docs/tutorials/bfgwiki2/definingviews.rst
index e12800d13..8a739ff58 100644
--- a/docs/tutorials/bfgwiki2/definingviews.rst
+++ b/docs/tutorials/bfgwiki2/definingviews.rst
@@ -2,19 +2,22 @@
 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`
-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.
+A :term:`view` in a :term:`url dispatch` -based :mod:`repoze.bfg`
+application is typically a simple Python function that accepts a
+single parameter named :term:`request`.  A view is assumed to return a
+:term:`response` object.
+
+.. note:: A :mod:`repoze.bfg` view can also be defined as callable
+   which accepts *two* arguments: a :term:`context` and `
+   :term:`request`.  You'll see this two-argument pattern used in
+   other :mod:`repoze.bfg` tutorials and applications.  Either calling
+   convention will work in any :mod:`repoze.bfg` 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 visual "noise".  If you do need the ``context`` within a
+   view function that only takes the request as a single argument, you
+   can obtain it via ``request.context``.
 
 The request passed to every view that is called as the result of a
 route match has an attribute named ``matchdict`` that contains the
@@ -29,11 +32,12 @@ Declaring Dependencies in Our ``setup.py`` File
 ===============================================
 
 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.
+dependency of the original "tutorial" application.  The original
+"tutorial" application was generated by the ``paster create`` command;
+it doesn't know about our custom application requirements.  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:
 
@@ -57,12 +61,11 @@ briefly and show the resulting ``views.py`` file afterwards.
 
 .. note::
 
-  There is nothing automagically special about the filename
-  ``views.py``.  A project may have many views throughout its codebase
-  in arbitrarily-named files.  Files implementing views often have
-  ``view`` in their filenames (or may live in a Python subpackage of
-  your application package named ``views``), but this is only by
-  convention.
+  There is nothing special about the filename ``views.py``.  A project
+  may have many views throughout its codebase in arbitrarily-named
+  files.  Files implementing views often have ``view`` in their
+  filenames (or may live in a Python subpackage of your application
+  package named ``views``), but this is only by convention.
 
 The ``view_wiki`` view function
 -------------------------------
@@ -292,11 +295,11 @@ concerned the pipeline *is* our application.  Simpler configurations
 don't use a pipeline: instead they expose a single WSGI application as
 "main".  Our setup is more complicated, so we use a pipeline.
 
-"egg:repoze.tm2#tm" is at the "top" of the pipeline.  This is a piece
-of middleware which commits a transaction if no exception occurs; if
-an exception occurs, the transaction will be aborted.  This is the
-piece of software that allows us to forget about needing to do manual
-commits and aborts of our database connection in view code.
+``egg:repoze.tm2#tm`` is at the "top" of the pipeline.  This is a
+piece of middleware which commits a transaction if no exception
+occurs; if an exception occurs, the transaction will be aborted.  This
+is the piece of software that allows us to forget about needing to do
+manual commits and aborts of our database connection in view code.
 
 Adding an Element to the Pipeline
 ---------------------------------
@@ -334,6 +337,8 @@ our application in a browser.  The views we'll try are as follows:
   <http://localhost:6543/add_page/SomePageName>`_ in a browser invokes
   the add view for a page.
 
-Try generating an error in a view by typing some bad code.  Then hit
-the view.  You should see an interactive exception handler in the
+Try generating an error within the body of a view by adding code to
+the top of it that generates an exception (e.g. ``raise
+Exception('Forced Exception')``).  Then visit the error-raising view
+in a browser.  You should see an interactive exception handler in the
 browser which allows you to examine values in a post-mortem mode.