Audit grammar in bfgwik2 tutorial.

10 files changed, 123 insertions, 108 deletions

diff --git a/docs/tutorials/bfgwiki/index.rst b/docs/tutorials/bfgwiki/index.rst
index c58822a61..4e6d9b306 100644
--- a/docs/tutorials/bfgwiki/index.rst
+++ b/docs/tutorials/bfgwiki/index.rst
@@ -3,10 +3,10 @@
 ZODB + Traversal Wiki Tutorial
 ==============================
 
-This tutorial introduces a :term:`traversal` -based BFG application to
-a developer with at least passing familiarity to Python.  When we're
-done with the tutorial, the developer will have created a basic Wiki
-application with authentication.
+This tutorial introduces a :term:`traversal` -based :mod:`repoze.bfg`
+application to a developer familiar with Python.  When we're done with
+the tutorial, the developer will have created a basic Wiki application
+with authentication.
 
 Contents:
 
diff --git a/docs/tutorials/bfgwiki/installation.rst b/docs/tutorials/bfgwiki/installation.rst
index 8feb0d5f2..63a770299 100644
--- a/docs/tutorials/bfgwiki/installation.rst
+++ b/docs/tutorials/bfgwiki/installation.rst
@@ -4,18 +4,21 @@ Installation
 
 For the most part, the installation process for this tutorial
 duplicates the steps described in :ref:`installing_chapter` and
-:ref:`project_narr`.
+:ref:`project_narr`, however it also explains how to install
+additional libraries for tutorial purposes.
 
 Preparation
 ========================
 
-The steps to prepare for the tutorial are slightly different depending
-on whether you're using UNIX or Windows.
+Please take the following steps to prepare for the tutorial.  The
+steps to prepare for the tutorial are slightly different depending on
+whether you're using UNIX or Windows.
 
 Preparation, UNIX
 -----------------
 
-#. Obtain, install, or find `Python 2.5
+#. If you don't already have a Python 2.5 interpreter installed on
+   your system, obtain, install, or find `Python 2.5
    <http://python.org/download/releases/2.5.4/>`_ for your system.
 
 #. Install latest `setuptools` into the Python you
@@ -57,7 +60,7 @@ Preparation, UNIX
 
 #. Use ``easy_install`` to install ``docutils``, ``repoze.tm``,
    ``repoze.zodbconn``, ``repoze.who``, ``nose`` and ``coverage`` from
-   a *different* index (the "bfgsite" index).
+   a different custom index (the "bfgsite" index).
 
    .. code-block:: bash
 
@@ -121,9 +124,9 @@ Preparation, Windows
 Making a Project
 ================
 
-:mod:`repoze.bfg` supplies a variety of templates to generate sample
-projects.  For this tutorial, we will use the :term:`ZODB` -oriented
-template named ``bfg_zodb``.
+Your next step is to create a project.  :mod:`repoze.bfg` supplies a
+variety of templates to generate sample projects.  For this tutorial,
+we will use the :term:`ZODB` -oriented template named ``bfg_zodb``.
 
 The below instructions assume your current working directory is the
 "virtualenv" named "bigfntut".
diff --git a/docs/tutorials/bfgwiki2/authorization.rst b/docs/tutorials/bfgwiki2/authorization.rst
index ec6f44882..2e9bb0e19 100644
--- a/docs/tutorials/bfgwiki2/authorization.rst
+++ b/docs/tutorials/bfgwiki2/authorization.rst
@@ -19,11 +19,11 @@ Adding A Root Factory
 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`.
+order for :mod:`repoze.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
@@ -40,9 +40,9 @@ statements to your ``models.py`` file:
        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.
+The ``RootFactory`` class we've just added will be used by
+:mod:`repoze.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
@@ -82,9 +82,10 @@ Changing ``configure.zcml``
 We'' change our ``configure.zcml`` file to enable an
 ``AuthTktAuthenticationPolicy`` and an ``ACLAuthorizationPolicy`` to
 enable declarative security checking.  We'll also add a ``forbidden``
-stanza.  This configures our login view to show up when BFG detects
-that a view invocation can not be authorized.  When you're done, your
-``configure.zcml`` will look like so:
+stanza.  This configures our login view to show up when
+:mod:`repoze.bfg` detects that a view invocation can not be
+authorized.  When you're done, your ``configure.zcml`` will look like
+so:
 
 .. literalinclude:: src/authorization/tutorial/configure.zcml
    :linenos:
@@ -184,13 +185,13 @@ We'll change our ``configure.zcml`` file to enable an
 enable declarative security checking.  We'll also change
 ``configure.zcml`` to add a ``forbidden`` 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:
+when :mod:`repoze.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 934fbcd42..2a0cd3f0f 100644
--- a/docs/tutorials/bfgwiki2/background.rst
+++ b/docs/tutorials/bfgwiki2/background.rst
@@ -2,17 +2,16 @@
 Background
 ==========
 
-This version of the BFG wiki tutorial presents a :mod:`repoze.bfg`
-application that uses technologies which will be familiar to someone
-with :term:`Pylons` experience.  It uses :term:`SQLAlchemy` as a
-persistence mechanism and :term:`url dispatch` to map URLs to code.
-It can also be followed by people without any prior Python web
-framework experience.
+This tutorial presents a :mod:`repoze.bfg` application that uses
+technologies which will be familiar to someone with :term:`Pylons`
+experience.  It uses :term:`SQLAlchemy` as a persistence mechanism and
+:term:`url dispatch` to map URLs to code.  It can also be followed by
+people without any prior Python web framework experience.
 
 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 1.0.
+This tutorial is known to work under :mod:`repoze.bfg` version 1.0b1.
 
 Have fun!
diff --git a/docs/tutorials/bfgwiki2/basiclayout.rst b/docs/tutorials/bfgwiki2/basiclayout.rst
index 89457b602..36cb8afd4 100644
--- a/docs/tutorials/bfgwiki2/basiclayout.rst
+++ b/docs/tutorials/bfgwiki2/basiclayout.rst
@@ -4,7 +4,7 @@ Basic Layout
 
 The starter files generated by the ``bfg_routesalchemy`` template are
 basic, but they provide a good orientation for the high-level patterns
-common to most :term:`url dispatch` -based BFG projects.
+common to most :term:`url dispatch` -based :mod:`repoze.bfg` projects.
 
 ``__init__.py``
 ---------------
@@ -16,15 +16,17 @@ directory as a Python package.
 Configuration With ``configure.zcml``
 --------------------------------------
 
-BFG uses a configuration markup language syntactically the same as
-Zope's implementation of :term:`ZCML`, but using a different default
-XML namespace.  Our sample ZCML file looks like the following:
+:mod:`repoze.bfg` uses a configuration markup language syntactically
+the same as Zope's implementation of :term:`ZCML`, but using a
+different default XML namespace.  Our sample ZCML file looks like the
+following:
 
    .. literalinclude:: src/basiclayout/tutorial/configure.zcml
       :linenos:
       :language: xml
 
-#. *Line 1*.  The root ``<configure>`` element, in a *BFG* namespace.
+#. *Line 1*.  The root ``<configure>`` element, in a ``bfg``
+   namespace.
 
 #. *Line 3*. Boilerplate, the comment explains.
 
@@ -50,7 +52,7 @@ XML namespace.  Our sample ZCML file looks like the following:
    declaration, we're saying that any URL that starts with ``/static``
    should go to the static view; any remainder of its path (e.g. the
    ``/foo`` in ``/static/foo``) will be used to compose a path to a
-   static file resource (CSS and such).  
+   static file resource, such as a CSS file.
 
 Content Models with ``models.py``
 ---------------------------------
@@ -101,10 +103,10 @@ Here is the source for ``models.py``:
 App Startup with ``run.py``
 ---------------------------
 
-How does a BFG application start up?  When you run under ``paster``
-using the ``tutorial.ini`` generated config file, the application area
-points at an entry point.  Our entry point happens to be in ``run.py``
-and its ``app`` function:
+How does a :mod:`repoze.bfg` application start up?  When you run under
+``paster`` using the ``tutorial.ini`` generated config file, the
+application area points at an entry point.  Our entry point happens to
+be in ``run.py`` and its ``app`` function:
 
    .. literalinclude:: src/basiclayout/tutorial/run.py
       :linenos:
@@ -131,12 +133,10 @@ and its ``app`` function:
 
 #. Line *26*.  We use the ``repoze.bfg.router.make_app`` to return a
    :term:`WSGI` application.  The ``make_app`` function's first
-   parameter is the "root factory", which is used by the BFG
-   :term:`traversal` mechanism.  Since this is a URL dispatch
-   application, the root factory is ``None``.  The second argument is
-   the *package* representing our application, and the third argument,
-   ``options`` is passed as a keyword argument.  It contains a
-   dictionary of options parsed by PasteDeploy.
-
-We'll later change ``run.py`` when we add :term:`authorization` to our
-wiki application.
+   parameter is the "root factory", which is used by the
+   :mod:`repoze.bfg` :term:`traversal` mechanism.  Since this is a URL
+   dispatch application, the root factory is ``None``.  The second
+   argument is the *package* representing our application, and the
+   third argument, ``options`` is passed as a keyword argument.  It
+   contains a dictionary of options parsed by PasteDeploy.
+
diff --git a/docs/tutorials/bfgwiki2/definingmodels.rst b/docs/tutorials/bfgwiki2/definingmodels.rst
index 69d8e653e..4942a72bd 100644
--- a/docs/tutorials/bfgwiki2/definingmodels.rst
+++ b/docs/tutorials/bfgwiki2/definingmodels.rst
@@ -2,9 +2,9 @@
 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.
+The first change we'll make to our 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.
 
 Making Edits to ``models.py``
 -----------------------------
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.
diff --git a/docs/tutorials/bfgwiki2/distributing.rst b/docs/tutorials/bfgwiki2/distributing.rst
index 8f36f34d7..e03060279 100644
--- a/docs/tutorials/bfgwiki2/distributing.rst
+++ b/docs/tutorials/bfgwiki2/distributing.rst
@@ -6,7 +6,7 @@ Once your application works properly, you can create a "tarball" from
 it by using the ``setup.py sdist`` command.  The following commands
 assume your current working directory is the ``tutorial`` package
 we've created and that the parent directory of the ``tutorial``
-package is a virtualenv representing a BFG environment.
+package is a virtualenv representing a :mod:`repoze.bfg` environment.
 
 On UNIX:
 
diff --git a/docs/tutorials/bfgwiki2/index.rst b/docs/tutorials/bfgwiki2/index.rst
index 7989a404d..f97972766 100644
--- a/docs/tutorials/bfgwiki2/index.rst
+++ b/docs/tutorials/bfgwiki2/index.rst
@@ -4,10 +4,9 @@ SQLAlchemy + URL Dispatch Wiki Tutorial
 =======================================
 
 This tutorial introduces a :term:`SQLAlchemy` and :term:`url dispatch`
--based BFG application to a developer with at least passing
-familiarity to Python.  When we're done with the tutorial, the
-developer will have created a basic Wiki application with
-authentication.
+-based :mod:`repoze.bfg` application to a developer familiar with
+Python.  When the tutorial is finished, the developer will have
+created a basic Wiki application with authentication.
 
 Contents:
 
diff --git a/docs/tutorials/bfgwiki2/installation.rst b/docs/tutorials/bfgwiki2/installation.rst
index 1e43c3abd..a6ba6fbfa 100644
--- a/docs/tutorials/bfgwiki2/installation.rst
+++ b/docs/tutorials/bfgwiki2/installation.rst
@@ -2,9 +2,9 @@
 Installation
 ============
 
-For the most part, the installation process for this tutorial follows
-the `Installing repoze.bfg
-<http://docs.repoze.org/bfg/narr/install.html>`_.  We install
+For the most part, the installation process for this tutorial
+duplicates the steps described in :ref:`installing_chapter` and
+:ref:`project_narr`, however it also explains how to install
 additional libraries for tutorial purposes.
 
 Preparation
@@ -52,7 +52,7 @@ Preparation, UNIX
    shell environment wired to use the virtualenv.
 
 #. Use ``easy_install`` and point to the BFG "current" index to get
-   BFG and its direct dependencies installed:
+   :mod:`repoze.bfg` and its direct dependencies installed:
 
    .. code-block:: bash
 
@@ -101,8 +101,8 @@ Preparation, Windows
 #. (Optional) Consider using ``bin\activate.bat`` to make your shell
    environment wired to use the virtualenv.
 
-#. Use ``easy_install`` and point to the BFG "current index to get BFG
-   and its direct dependencies installed:
+#. Use ``easy_install`` and point to the BFG "current index to get
+   :mod:`repoze.bfg` and its direct dependencies installed:
 
    .. code-block:: bat
 
@@ -120,9 +120,10 @@ Preparation, Windows
 Making a Project
 ================
 
-Your next step is to create a project.  BFG supplies a variety of
-templates to generate sample projects.  We will use the
-:term:`SQLAlchemy` + :term:`URL Dispatch` -oriented template.
+Your next step is to create a project.  :mod:`repoze.bfg` supplies a
+variety of templates to generate sample projects.  We will use the
+``bfg_routesalchemy`` template, which generates an application that
+uses :term:`SQLAlchemy` and :term:`URL dispatch`.
 
 The below instructions assume your current working directory is the
 "virtualenv" named "bigfntut".
@@ -139,6 +140,12 @@ On Windows:
 
    c:\bigfntut> Scripts\paster create -t bfg_routesalchemy tutorial
 
+.. note:: If you are using Windows, the ``bfg_routesalchemy`` Paster
+   template may not deal gracefully with installation into a location
+   that contains spaces in the path.  If you experience startup
+   problems, try putting both the virtualenv and the project into
+   directories that do not contain spaces in their paths.
+
 Installing the Project in "Development Mode"
 ============================================
 
@@ -253,8 +260,9 @@ Decisions the ``bfg_routesalchemy`` Template Has Made For You
 Creating a project using the ``bfg_routesalchemy`` template makes the
 assumption that you are willing to use :term:`SQLAlchemy` as a
 database access tool and :term:`url dispatch` to map URLs to code.
-BFG supports any persistent storage mechanism (e.g. object database or
-filesystem files, etc), and supports an additional mechanism to map
-URLs to code (:term:`traversal`).  However, for the purposes of
-this tutorial, we'll be using url dispatch and SQLAlchemy.
+:mod:`repoze.bfg` supports any persistent storage mechanism
+(e.g. object database or filesystem files, etc).  It also supports an
+additional mechanism to map URLs to code (:term:`traversal`).
+However, for the purposes of this tutorial, we'll only be using url
+dispatch and SQLAlchemy.