bfgwiki tutorial audit.

6 files changed, 65 insertions, 80 deletions

diff --git a/docs/index.rst b/docs/index.rst
index 4f90a5ec8..9f7ed72bd 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -72,9 +72,6 @@ Per-module :mod:`repoze.bfg` API documentation.
 Tutorials
 =========
 
-Step-by-step tutorials which demonstrate how you might use and deploy
-:mod:`repoze.bfg`.
-
 ZODB + traversal Wiki tutorial, demonstrating how to build a
 :term:`traversal` based application using :term:`ZODB` and
 :term:`authentication`.  Good for people with prior Zope experience
diff --git a/docs/tutorials/bfgwiki/authorization.rst b/docs/tutorials/bfgwiki/authorization.rst
index e605fd31a..7913240b8 100644
--- a/docs/tutorials/bfgwiki/authorization.rst
+++ b/docs/tutorials/bfgwiki/authorization.rst
@@ -25,9 +25,10 @@ Changing ``configure.zcml``
 We'll 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:
@@ -83,7 +84,8 @@ into its template.  We'll add something like this to each view body:
    logged_in = authenticated_userid(request)
 
 We'll then change the return value of ``render_template_to_response``
-to pass the `resulting `logged_in`` value to the template, e.g.:
+within each view to pass the `resulting `logged_in`` value to the
+template, e.g.:
 
 .. code-block:: python
    :linenos:
@@ -124,9 +126,10 @@ Giving Our Root Model Object an ACL
 -----------------------------------
 
 We need to give our root model object an ACL.  This ACL will be
-sufficient to provide enough information to the BFG security machinery
-to challenge a user who doesn't have appropriate credentials when he
-attempts to invoke the ``add_page`` or ``edit_page`` views.
+sufficient to provide enough information to the :mod:`repoze.bfg`
+security machinery to challenge a user who doesn't have appropriate
+credentials when he attempts to invoke the ``add_page`` or
+``edit_page`` views.
 
 We need to perform some imports at module scope in our ``models.py``
 file:
diff --git a/docs/tutorials/bfgwiki/background.rst b/docs/tutorials/bfgwiki/background.rst
index d81574753..0e57ef81e 100644
--- a/docs/tutorials/bfgwiki/background.rst
+++ b/docs/tutorials/bfgwiki/background.rst
@@ -12,11 +12,6 @@ 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.
 
-The tutorial makes mention of a CDROM disk.  This is due to the fact
-that the tutorial is taught "live" under some circumstances.  When it
-mentions use of a CD, there are alternate instructions which follow
-for people who do not have the CD.
-
-This tutorial is known to work under :mod:`repoze.bfg` version 0.9a7.
+This tutorial is known to work under :mod:`repoze.bfg` version 1.0b1.
 
 Have fun!
diff --git a/docs/tutorials/bfgwiki/basiclayout.rst b/docs/tutorials/bfgwiki/basiclayout.rst
index 1ec10094e..d69839c46 100644
--- a/docs/tutorials/bfgwiki/basiclayout.rst
+++ b/docs/tutorials/bfgwiki/basiclayout.rst
@@ -4,7 +4,8 @@ Basic Layout
 
 The starter files generated by the ``bfg_zodb`` template are basic,
 but they provide a good orientation for the high-level patterns common
-to most :term:`traversal` -based BFG (and BFG with ZODB) projects.
+to most :term:`traversal` -based :mod:`repoze.bfg` (and :term:`ZODB`
+based) projects.
 
 ``__init__.py``
 ---------------
@@ -16,17 +17,18 @@ directory as a Python package.
 Configuration With ``configure.zcml``
 --------------------------------------
 
-BFG uses a 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 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.
+#. *Line 4*. Boilerplate, the comment explains.
 
 #. *Lines 6-9*.  Register a ``<view>`` that is bound to a class.
    ``.views.my_view`` is a *function* we write (generated by the
@@ -44,10 +46,10 @@ namespace.  Our sample ZCML file looks like the following:
 Content Models with ``models.py``
 ---------------------------------
 
-BFG often uses the word *model* when talking about content resources
-arranged in a hierarchical *model graph*.  The ``models.py`` file is
-where the ``bfg_zodb`` Paster template put the classes that implement
-our models.
+:mod:`repoze.bfg` often uses the word *model* when talking about
+content resources arranged in a hierarchical *model graph*.  The
+``models.py`` file is where the ``bfg_zodb`` Paster template put the
+classes that implement our models.
 
 Here is the source for ``models.py``:
 
@@ -62,10 +64,10 @@ Here is the source for ``models.py``:
    that this is the :term:`root` object.
 
 #. *Lines 6-12*.  ``appmaker`` is used to return the *application
-   root* object.  It is called on *every request* to the BFG
-   application (it is essentially a :term:`root factory`).  It also
-   performs bootstrapping by *creating* an application root (inside
-   the ZODB root object) if one does not already exist.
+   root* object.  It is called on *every request* to the
+   :mod:`repoze.bfg` application.  It also performs bootstrapping by
+   *creating* an application root (inside the ZODB root object) if one
+   does not already exist.
  
    We do so by first seeing if the database has the persistent
    application root.  If not, we make an instance, store it, and
@@ -75,10 +77,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:
@@ -100,5 +102,3 @@ and its ``app`` function:
    factory (``get_root``), the *package* representing our application,
    and the keywords parsed by PasteDeploy.
 
-We'll later change ``run.py`` when we add :term:`authorization` to our
-wiki application.
diff --git a/docs/tutorials/bfgwiki/installation.rst b/docs/tutorials/bfgwiki/installation.rst
index 49a9f9cd5..8feb0d5f2 100644
--- a/docs/tutorials/bfgwiki/installation.rst
+++ b/docs/tutorials/bfgwiki/installation.rst
@@ -2,27 +2,18 @@
 Installation
 ============
 
-For the most part, the installation process for this tutorial follows
-the `Installing repoze.bfg
-<http://docs.repoze.org/bfg/narr/install.html>`_ and `Creating a
-repoze.bfg Project <http://docs.repoze.org/bfg/narr/project.html>`_
-pages.
+For the most part, the installation process for this tutorial
+duplicates the steps described in :ref:`installing_chapter` and
+:ref:`project_narr`.
 
-Preparation (with CD)
-=====================
-
-Follow the instructions within the ``INSTALL.txt`` file found on the
-CD.
-
-Preparation (without CD)
+Preparation
 ========================
 
-If you don't possess a CDROM with the tutorial files on it, take the
-following steps.  The steps are slightly different depending on
-whether you're using UNIX or Windows.
+The steps to prepare for the tutorial are slightly different depending
+on whether you're using UNIX or Windows.
 
-Preparation (without CD), UNIX
-------------------------------
+Preparation, UNIX
+-----------------
 
 #. Obtain, install, or find `Python 2.5
    <http://python.org/download/releases/2.5.4/>`_ for your system.
@@ -58,7 +49,7 @@ Preparation (without CD), 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
 
@@ -66,15 +57,15 @@ Preparation (without CD), UNIX
 
 #. Use ``easy_install`` to install ``docutils``, ``repoze.tm``,
    ``repoze.zodbconn``, ``repoze.who``, ``nose`` and ``coverage`` from
-   a *different* index (the "lemonade" index).
+   a *different* index (the "bfgsite" index).
 
    .. code-block:: bash
 
-     $ bin/easy_install -i http://dist.repoze.org/lemonade/dev/simple \
+     $ bin/easy_install -i http://dist.repoze.org/bfgsite/simple \
         docutils repoze.tm repoze.zodbconn repoze.who nose coverage
 
-Preparation (without CD), Windows
----------------------------------
+Preparation, Windows
+--------------------
 
 #. Install, or find `Python 2.5
    <http://python.org/download/releases/2.5.4/>`_ for your system.
@@ -110,8 +101,8 @@ Preparation (without CD), 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
 
@@ -119,23 +110,20 @@ Preparation (without CD), Windows
 
 #. Use ``easy_install`` to install ``docutils``, ``repoze.tm``,
    ``repoze.zodbconn``, ``repoze.who``, ``nose`` and ``coverage`` from
-   a *different* index (the "lemonade" index).
+   a *different* index (the "bfgsite" index).
 
    .. code-block:: bat
 
-     c:\bigfntut> Scripts\easy_install -i http://dist.repoze.org/lemonade/dev/simple docutils repoze.tm repoze.zodbconn repoze.who nose coverage
+     c:\bigfntut> Scripts\easy_install -i http://dist.repoze.org/bfgsite/simple docutils repoze.tm repoze.zodbconn repoze.who nose coverage
 
 .. _making_a_project:
 
 Making a Project
 ================
 
-Whether you arrived at this point by installing your own environment
-using the steps above, or you used the instructions in the tutorial
-disc, your next steps are to create a project.
-
-BFG supplies a variety of templates to generate sample projects.  We
-will use the :term:`ZODB` -oriented template.
+: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".
@@ -239,8 +227,9 @@ On Windows:
 
   c:\bigfntut\tutorial> ..\Scripts\nosetests --cover-package=tutorial --cover-erase --with-coverage
 
-Looks like the BFG template for ZODB projects is missing some test
-coverage, particularly in the file named ``models.py``.
+Looks like the code in the ``bfg_zodb`` template for ZODB projects is
+missing some test coverage, particularly in the file named
+``models.py``.
 
 Visit the Application in a Browser
 ==================================
@@ -253,9 +242,9 @@ Decisions the ``bfg_zodb`` Template Has Made For You
 
 Creating a project using the ``bfg_zodb`` template makes the
 assumption that you are willing to use :term:`ZODB` as persistent
-storage and :term:`traversal` to map URLs to code.  BFG supports any
-persistent storage mechanism (e.g. a SQL database or filesystem files,
-etc), and supports an additional mechanism to map URLs to code
-(:term:`URL dispatch`).  However, for the purposes of this tutorial,
-we'll be using traversal and ZODB.
+storage and :term:`traversal` to map URLs to code.  :mod:`repoze.bfg`
+supports any persistent storage mechanism (e.g. a SQL database or
+filesystem files, etc).  It also supports an additional mechanism to
+map URLs to code (:term:`URL dispatch`).  However, for the purposes of
+this tutorial, we'll only be using traversal and ZODB.
 
diff --git a/docs/tutorials/bfgwiki/viewdecorators.rst b/docs/tutorials/bfgwiki/viewdecorators.rst
index b9fd3b454..dc0e500eb 100644
--- a/docs/tutorials/bfgwiki/viewdecorators.rst
+++ b/docs/tutorials/bfgwiki/viewdecorators.rst
@@ -3,14 +3,15 @@ Using View Decorators Rather than ZCML ``view`` directives
 ==========================================================
 
 So far we've been using :term:`ZCML` to map model types to views.
-It's often easier to use the "bfg_view" view decorator to do this
+It's often easier to use the ``bfg_view`` view decorator to do this
 mapping.  Using view decorators provides better locality of reference
 for the mapping, because you can see which model types and view names
 the view will serve right next to the view function itself.  In this
 mode, however, you lose the ability for some views to be overridden
-"from the outside" (by someone using your application as a framework).
-Since this application is *definitely* not a framework, it makes sense
-for us to switch over to using view decorators.
+"from the outside" (by someone using your application as a framework,
+as explained in the :ref:`extending_chapter`).  Since this application
+is not meant to be a framework, it makes sense for us to switch over
+to using view decorators.
 
 Adding View Decorators
 ======================
@@ -213,7 +214,7 @@ On UNIX:
 
 On Windows:
 
-.. code-block:: bash
+.. code-block:: bat
 
 
   c:\bigfntut\tutorial> ..\Scripts\python setup.py test -q