Tweaks.

7 files changed, 84 insertions, 66 deletions

diff --git a/docs/narr/install.rst b/docs/narr/install.rst
index 69e244515..7a970d437 100644
--- a/docs/narr/install.rst
+++ b/docs/narr/install.rst
@@ -10,23 +10,16 @@ primarily under Python 2.4, so that version is recommended.
 :mod:`repoze.bfg` does *not* run under any version of Python before
 2.4, and does *not* run under Python 3.X.
 
-.. warning:: To succesfully install :mod:`repoze.bfg`, you will need an
-   environment capable of compiling C code.  See the documentation
+.. warning:: To succesfully install :mod:`repoze.bfg`, you will need
+   an environment capable of compiling C code.  See the documentation
    about installing, e.g. ``gcc`` for your system.  Additionally, the
    Python development libraries for your Python version will need to
    be installed and the ``lixbml2`` and ``libxslt`` development
    libraries will need to be installed.  These requirements are often
    satisfied by installing the ``python-devel``, ``libxml2-devel`` and
-   ``libxslt-devel`` packages into your system.
-
-After you've got the requisite dependencies installed, you may install
-:mod:`repoze.bfg` into your Python environment using the following
-command::
-
-  $ easy_install -i http://dist.repoze.org/lemonade/dev/simple repoze.bfg
-
-You will need :term:`setuptools` installed on within your Python
-system in order to run the ``easy_install`` command.
+   ``libxslt-devel`` packages into your system.  You will also need
+   :term:`setuptools` installed on within your Python system in order
+   to run the ``easy_install`` command.
 
 It is advisable to install :mod:`repoze.bfg` into a :term:`virtualenv`
 in order to obtain isolation from any "system" packages you've got
@@ -34,6 +27,12 @@ installed in your Python version (and likewise, to prevent
 :mod:`repoze.bfg` from globally installing versions of packages that
 are not compatible with your system Python).
 
+After you've got the requisite dependencies installed, you may install
+:mod:`repoze.bfg` into your Python environment using the following
+command::
+
+  $ easy_install -i http://dist.repoze.org/lemonade/dev/simple repoze.bfg
+
 What Gets Installed
 -------------------
 
diff --git a/docs/narr/models.rst b/docs/narr/models.rst
index 045bcad52..cff04ea18 100644
--- a/docs/narr/models.rst
+++ b/docs/narr/models.rst
@@ -25,11 +25,17 @@ An example of a model describing a blog entry::
           self.author = author
           self.created = datetime.datetime.now()
 
-A model consists of basically two things: the object which defines the
-model (above as the class ``IBlogEntry``), and an *interface* attached
-to the model object.  An interface simply tags the model object with a
+A model consists of two things: the object which defines the model
+(above as the class ``IBlogEntry``), and an *interface* attached to
+the model object.  An interface simply tags the model object with a
 "type" that can be referred to within view configuration.  A model
-object can implement zero or more interfaces.
+object can implement zero or more interfaces.  The interface must be
+an instance of a class that inherits from
+``zope.interface.Interface``.
+
+You specify that a model *implements* an interface by using the
+``zope.interface.implements`` function at class scope.  The above
+``BlogEntry`` model implements the ``IBlogEntry`` interface.
 
 Defining a Graph of Model Instances
 -----------------------------------
@@ -41,12 +47,13 @@ instance nodes in the graph:
  - Nodes which contain other nodes (aka "container" nodes) must supply
    a ``__getitem__`` method which is willing to resolve a string or
    unicode name to a subobject.  If a subobject by that name does not
-   exist in the container, ``__getitem__`` must raise a KeyError.  If
-   a subobject by that name *does* exist, the container should return
-   the subobject (another model instance).  
+   exist in the container, ``__getitem__`` must raise a ``KeyError``.
+   If a subobject by that name *does* exist, the container should
+   return the subobject (another model instance).
 
  - Nodes which do not contain other nodes (aka "leaf" nodes) must not
-   implement ``__getitem__``.
+   implement a ``__getitem__``, or if they do, their ``__getitem__``
+   method must raise a ``KeyError``.
 
 Location-Aware Model Instances
 ------------------------------
@@ -68,8 +75,10 @@ Location-Aware Model Instances
  LocationProxy which will dynamically assign a ``__name__`` and a
  ``__parent__`` to it, recursively.
 
- If you choose to make use of the dynamic assignment of ``__parent__``
- and ``__name__``, the root node must have a ``__parent__`` and a
- ``__name__`` that are both ``None``, and it must provide the
- ``ILocation`` interface.  The easiest way to do this is to claim that
- the class representing the root node ``implements(ILocation)``.
+ If you choose to make use of the location-based dynamic assignment of
+ ``__parent__`` and ``__name__``, the root node must have a
+ ``__parent__`` and a ``__name__`` that are both ``None``, and it must
+ provide the ``ILocation`` interface.  The easiest way to do this is
+ to claim that the class representing the root node
+ ``implements(ILocation)``, as above.
+
diff --git a/docs/narr/project.rst b/docs/narr/project.rst
index b87197b9a..f67e28e1e 100644
--- a/docs/narr/project.rst
+++ b/docs/narr/project.rst
@@ -4,8 +4,8 @@ Starting a :mod:`repoze.bfg` Project
 ====================================
 
 You can use :mod:`repoze.bfg` 's sample application generator to get
-started.  This generator leverages Paste templates to allow creation
-of a new project by answering a series of questions.
+started.  This generator uses :term:`Paste` templates to allow
+creation of a new project by answering a series of questions.
 
 Creating the Project
 --------------------
@@ -53,9 +53,9 @@ As a result of the above, a project is created in a directory named
 directory from which a Python setuptools *distribution* can be
 created.  The ``setup.py`` file in that directory can be used to
 distribute your application, or install your application for
-deployment or development. A sample PasteDeploy ``.ini`` file named
-``myproject.ini`` will also be created in the project directory.  You
-can use this to run your application.
+deployment or development. A sample ``PasteDeploy`` ``.ini`` file
+named ``myproject.ini`` will also be created in the project directory.
+You can use this to run your application.
 
 The main ``myproject`` contains an additional subdirectory (also named
 ``myproject``) representing a Python pakckage which holds very simple
@@ -237,7 +237,7 @@ like so:
 
 #. Lines 1-3 provide the root node and namespaces for the
    configuration language.  ``bfg`` is the namespace for
-   :mod:`repoze.bfg`-specific configuration directives.
+   :mod:`repoze.bfg` -specific configuration directives.
 
 #. Line 6 initializes :mod:`repoze.bfg`-specific configuration
    directives by including it as a package.
@@ -250,8 +250,8 @@ like so:
 ~~~~~~~~~~~~
 
 Much of the heavy lifting in a :mod:`repoze.bfg` application comes in
-the views.  Views are the bridge between the content in the model, and
-the HTML given back to the browser.
+the form of *views*.  A :term:`view` is the bridge between the content
+in the model, and the HTML given back to the browser.
 
 .. literalinclude:: myproject/myproject/views.py
    :linenos:
@@ -273,7 +273,7 @@ the HTML given back to the browser.
   This example uses ``render_template_to_response`` which allows the
   view author to think only in terms of templates.  If you want more
   control over the response, use ``render_template`` and create your
-  own WebOb Response object to return.
+  own ``WebOb`` Response object to return.
 
 ``models.py``
 ~~~~~~~~~~~~~
@@ -331,6 +331,10 @@ The single template in the project looks like so:
    :linenos:
    :language: xml
 
+This is a :term:`z3c.pt` template.  It displays the current project
+name when it is rendered.  It is referenced by the ``my_view``
+function in the ``views.py`` module.
+
 ``tests.py``
 ~~~~~~~~~~~~
 
@@ -339,4 +343,7 @@ The ``tests.py`` module includes unit tests for your application.
 .. literalinclude:: myproject/myproject/tests.py
    :linenos:
 
+This sample ``tests.py`` file has a single unit test defined within
+it.  This is the code that is executed when you run ``setup.py test
+-q``.  You may add more tests here as you build your application.
 
diff --git a/docs/narr/security.rst b/docs/narr/security.rst
index 6215bf1bc..7adeda3b9 100644
--- a/docs/narr/security.rst
+++ b/docs/narr/security.rst
@@ -6,11 +6,8 @@ prevents views that are protected by a :term:`permission` from being
 rendered when the user represented by the request does not have the
 appropriate level of access in a context.
 
-Jargon
-------
-
-To learn about the jargon tossed around in this chapter, you may want
-to review the :ref:`glossary`.
+Security is enabled by adding configuration to your ``configure.zcml``
+which specifies a :term:`security policy`.
 
 Enabling a Security Policy
 --------------------------
@@ -30,18 +27,19 @@ The above insrcutable stanza enables the
 ``RemoteUserACLSecurityPolicy`` to be in effect for every request to
 your application.  The ``RemoteUserACLSecurityPolicy`` is a policy
 which compares the ``REMOTE_USER`` variable passed in the reqest's
-environment (as the sole *principal*) against any *ACL* found in model
-data when attempting to call some *view*.  The policy either allows
-the view that the permission was declared for to be called, or returns
-a ``401 Unathorized`` response code to the upstream WSGI server.
+environment (as the sole :term:`principal`) against any *ACL* found in
+model data when attempting to call some :term:`view`.  The policy
+either allows the view that the permission was declared for to be
+called, or returns a ``401 Unathorized`` response code to the upstream
+WSGI server.
 
 Protecting Views with Permissions
 ---------------------------------
 
 You declaratively protected a particular view with a permisson via the
 ``configure.zcml`` application registry.  For example, the following
-declaration protects the view named "add_entry.html" when invoked
-against an IBlog context with the ``add`` permission::
+declaration protects the view named ``add_entry.html`` when invoked
+against an ``IBlog`` context with the ``add`` permission::
 
   <bfg:view
       for=".models.IBlog"
@@ -62,12 +60,12 @@ Assigning ACLs to your Model Objects
 ------------------------------------
 
 When ``repoze.bfg`` determines whether a user possesses a particular
-permission in a context, it examines the ACL associated with the
-context.  An ACL is associated with a context by virtue of the
-``__acl__`` attribute of the model object representing the context.
-This attribute can be defined on the model *instance* (if you need
-instance-level security), or it can be defined on the model *class*
-(if you just need type-level security).
+permission in a :term:`context`, it examines the :term:`ACL`
+associated with the context.  An ACL is associated with a context by
+virtue of the ``__acl__`` attribute of the model object representing
+the context.  This attribute can be defined on the model *instance*
+(if you need instance-level security), or it can be defined on the
+model *class* (if you just need type-level security).
 
 For example, an ACL might be attached to model for a blog via its
 class::
@@ -92,6 +90,11 @@ The above ACL indicates that the Everyone principal (a system-defined
 principal) is allowed to view the blog, the ``group:editors``
 principal is allowed to add to and edit the blog.
 
+A principal is usually a user id, however it also may be a group id if
+your authentication system provides group information and the security
+policy is written to respect them.  The
+``RemoteUserACLSecurityPolicy`` does not respect group information.
+
 ACL Inheritance
 ---------------
 
diff --git a/docs/narr/templates.rst b/docs/narr/templates.rst
index beb5fd58b..c67bee81b 100644
--- a/docs/narr/templates.rst
+++ b/docs/narr/templates.rst
@@ -2,21 +2,19 @@ Templates
 =========
 
 A *template* is a file on disk which can be used to render data
-provided by a *view* in a form that is meaningful for a particular
-*context*.
+provided by a *view*.
 
 Default Templating With z3c.pt Page Templates
 ------------------------------------------------
 
 Like Zope, :mod:`repoze.bfg` uses Zope Page Templates (ZPT) as its
 default templating language. However, :mod:`repoze.bfg` uses a
-different implementation of the ZPT specification: the `z3c.pt
-<http://pypi.python.org/pypi/z3c.pt>`_ templating engine. This
-templating engine complies with the `Zope Page Template
-<http://wiki.zope.org/ZPT/FrontPage>`_ template specification. While
-``z3c.pt`` doesn't implement the METAL specification (feature or
-drawback, depending on your viewpoint), it is significantly
-faster. And faster, of course, is the zen of :mod:`repoze.bfg`.
+different implementation of the ZPT specification: the :term:`z3c.pt`
+templating engine. This templating engine complies with the `Zope Page
+Template <http://wiki.zope.org/ZPT/FrontPage>`_ template
+specification. While :term:`z3c.pt` doesn't implement the *METAL*
+specification (feature or drawback, depending on your viewpoint), it
+is significantly faster.
 
 Given a template named ``foo.html`` in a directory in your application
 named "templates", you can render the template in a view via::
@@ -24,7 +22,7 @@ named "templates", you can render the template in a view via::
   from repoze.bfg.template import render_template_to_response
   return render_template_to_response('templates/foo.html', foo=1, bar=2)
 
-You can also wire up page templates via ZCML:
+You associate a view with a URL by adding information to your ZCML.
 
 .. sourcecode:: xml
 
@@ -34,7 +32,7 @@ You can also wire up page templates via ZCML:
       name="contents.html"
       />
 
-Both approaches load the template and keep it in memory between
+:mod:`repoze.bfg` loads the template and keeps it in memory between
 requests. This means that modifications to the ZPT require a restart
 before you can see the changes.
 
diff --git a/docs/narr/traversal.rst b/docs/narr/traversal.rst
index 1044c25f1..64e92c570 100644
--- a/docs/narr/traversal.rst
+++ b/docs/narr/traversal.rst
@@ -22,8 +22,10 @@ items.
 .. note::
 
   :mod:`repoze.bfg` features graph traversal.  However, via the
-  inclusion of Routes, URL dispatch is also supported for the parts of
-  your URL space that better fit that model.
+  inclusion of :term:`Routes`, URL dispatch is also supported for the
+  parts of your URL space that better fit that model.  See the
+  :ref:`urldispatch_module` for more information about using URL
+  dispatch.
 
 Non-graph traversal based URL dispatch can easily handle URLs such as
 ``http://example.com/members/Chris``, where it's assumed that each
diff --git a/docs/narr/views.rst b/docs/narr/views.rst
index 91eaa91ff..a2a0c79ca 100644
--- a/docs/narr/views.rst
+++ b/docs/narr/views.rst
@@ -20,11 +20,11 @@ world view implemented as a function::
 View Arguments
 --------------
 
-context
+:term:`context`
 
   An instance of a model found via graph traversal.
 
-request
+:term:`request`
 
   A WebOb request object representing the current request.