Bring up to date.

3 files changed, 81 insertions, 40 deletions

diff --git a/docs/glossary.rst b/docs/glossary.rst
index b045a1232..528522e16 100644
--- a/docs/glossary.rst
+++ b/docs/glossary.rst
@@ -72,10 +72,15 @@ Glossary
     in your :mod:`repoze.bfg` application, you are using URL dispatch.
     See the :ref:`urldispatch_module` for more information.
   Context
-    A :term:`model` in the system that is "found" during
-    :term:`traversal` or :term:`URL dispatch`; it becomes the subject
-    of a :term:`view`.  See the :ref:`traversal_chapter` chapter for
-    more information.
+    A object in the system that is found during :term:`traversal` or
+    :term:`URL dispatch` based on URL data; if it's found via
+    traversal, it's usually a :term:`model` object; if it's found via
+    :term:`URL dispatch`, it's a manufactured context object that
+    contains routing information.  A context becomes the subject of a
+    :term:`view`, and typically has security information attached to
+    it.  See the :ref:`traversal_chapter` chapter and the
+    :ref:`urldispatch_chapter` chapter for more information about how
+    a URL is resolved to a context.
   Application registry
     A registry which maps model types to views, as well as performing
     other application-specific component registrations.  Every
@@ -175,8 +180,14 @@ Glossary
     An `Apache module <http://code.google.com/p/modwsgi/>`_ for hosting
     Python WSGI applications.
   Zope
-    `The Z Object Publishing Framework <http://zope.org>`_.  The granddaddy 
-    of Python web frameworks.
+    `The Z Object Publishing Framework <http://zope.org>`_, a
+    full-featured Python web framework.
+  Grok
+    `A web framework based on Zope 3 <http://grok.zope.org>`_.
+  Django
+    `A full-featured Python web framework <http://djangoproject.com>`_.
+  Pylons
+    `A lightweight Python web framework <http://pylonshq.com>`_.
   ZODB
      `Zope Object Database <http://wiki.zope.org/ZODB/FrontPage>`_, a
      persistent Python object store.
@@ -243,8 +254,9 @@ Glossary
     :mod:`repoze.bfg` is to perform view mappings via the ``view``
     declaration.  The ``configure.zcml`` file in a :mod:`repoze.bfg`
     application represents the application's :term:`application
-    registry`.  See :term:`repoze.bfg.convention` for an alternative
-    to ZCML for application configuration.
+    registry`.  You can also use decorators to configure views in
+    :mod:`repoze.bfg`; see
+    :ref:`mapping_views_to_urls_using_a_decorator_section`.
   ReStructuredText
     A `plain text format <http://docutils.sourceforge.net/rst.html>`_
     that is the defacto standard for descriptive text shipped in
@@ -259,13 +271,14 @@ Glossary
     or a request object in order to identify that the object is "of a
     type".  Interfaces are used internally by :mod:`repoze.bfg` to
     perform view lookups and security policy lookups.  Interfaces are
-    exposed to application programmers by the ``view`` ZCML
-    directive in the form of both the ``for_`` attribute and the
-    ``request_type`` attribute.  They may be exposed to application
-    developers when using the :term:`event` system as
-    well. Fundamentally, :mod:`repoze.bfg` programmers can think of an
-    interface as something that they can attach to an object that
-    stamps it with a "type".  Interfaces can also be used to describe
+    exposed to application programmers by the ``view`` ZCML directive
+    or the corresponding ``bfg_view`` decorator in the form of both
+    the ``for`` attribute and the ``request_type`` attribute.  They
+    may be exposed to application developers when using the
+    :term:`event` system as well. Fundamentally, :mod:`repoze.bfg`
+    programmers can think of an interface as something that they can
+    attach to an object that stamps it with a "type" unrelated to its
+    underlying Python type.  Interfaces can also be used to describe
     the behavior of an object (its methods and attributes), but unless
     they choose to, :mod:`repoze.bfg` programmers do not need to
     understand or use this feature of interfaces.  In other words, bfg
@@ -320,4 +333,5 @@ Glossary
     `An add-on for repoze.bfg
     <http://static.repoze.org/conventiondocs>`_ which provides
     alternative mechanisms for common :mod:`repoze.bfg` application
-    configuration tasks.  Useful for the :term:`ZCML` -allergic.
+    configuration tasks.  The functionality of this package has been
+    merged into the :mod:`repoze.bfg` core as of version 0.6.3.
diff --git a/docs/narr/introduction.rst b/docs/narr/introduction.rst
index bf2e29be1..836f57c44 100644
--- a/docs/narr/introduction.rst
+++ b/docs/narr/introduction.rst
@@ -7,30 +7,29 @@ work.  However, it simpler than any than any released version of Zope.
 :mod:`repoze.bfg` uses the :term:`WSGI` protocol to handle requests
 and responses.
 
-Similarities with Other Frameworks
-----------------------------------
-
-:mod:`repoze.bfg` was inspired by Zope, Django, and Pylons.
-
-:mod:`repoze.bfg` traversal is inspired by Zope.  :mod:`repoze.bfg`
-uses the Zope Component Architecture ("CA") internally, as do Zope 2,
-Zope 3, and Grok.  Developers don't interact with the CA very much
-during typical development, however; it's mostly used by the framework
-developer rather than the application developer.  :mod:`repoze.bfg`
-developers use :term:`ZCML` (an XML dialect) or decorators to perform
-various configuration tasks; in particular, as in Zope3, one more more
-:term:`view` functions is associated with a :term:`model` type via
-ZCML or a decorator.
-
-Like Pylons, :mod:`repoze.bfg` is mostly policy-free.  It makes no
-assertions about which database you should use, and its built-in
-templating facilities are only for convenience.  In essence, it only
-supplies a mechanism to map URLs to :term:`view` code, along with a
-convention for calling those views.  You are free to use third-party
-components in your application that fit your needs.  Also like Pylons,
-:mod:`repoze.bfg` is heavily dependent on WSGI.
-
-The Django docs state that Django is an "MTV" framework in their `FAQ
+Similarities to Other Frameworks
+--------------------------------
+
+:mod:`repoze.bfg` was inspired by :term:`Zope`, :term:`Django`, and
+:term:`Pylons`.
+
+The :mod:`repoze.bfg` concept of traversal is inspired by
+:term:`Zope`.  Additionally, :mod:`repoze.bfg` uses the Zope Component
+Architecture ("CA") internally, as do Zope 2, Zope 3, and
+:term:`Grok`.  Application :mod:`repoze.bfg` developers use either
+:term:`ZCML` (an XML dialect, used in Zope) or decorators to perform
+various configuration tasks.  The decorator support is provided by the
+:term:`Grok` project.
+
+Like :term:`Pylons`, :mod:`repoze.bfg` is mostly policy-free.  It
+makes no assertions about which database you should use, and its
+built-in templating facilities are only for convenience.  In essence,
+it only supplies a mechanism to map URLs to :term:`view` code, along
+with a convention for calling those views.  You are free to use
+third-party components in your application that fit your needs.  Also
+like Pylons, :mod:`repoze.bfg` is heavily dependent on WSGI.
+
+The "Django docs state that Django is an "MTV" framework in their `FAQ
 <http://www.djangoproject.com/documentation/faq/>`_.  This also
 happens to be true for :mod:`repoze.bfg`::
 
@@ -72,6 +71,30 @@ Django.
 To learn more about the concepts used by :mod:`repoze.bfg`, visit the
 :ref:`glossary` for a listing of definitions.
 
+Differences from Other Frameworks
+---------------------------------
+
+Like :term:`Zope`, the :mod:`repoze.bfg` framework imposes slightly
+more `control inversion <http://plope.com/control_inversion>`_ upon
+application developers than other Python frameworks such as
+:term:`Pylons`.  For example :mod:`repoze.bfg` assumes that you're
+wiling to resolve a URL to a :term:`context` object before passing it
+to a :term:`view`.  Pylons and other Python "MVC" frameworks have no
+such intermediate step; they resolve a URL directly to a controller.
+Another example: using the :mod:`repoze.bfg` security subsystem
+assumes that you're willing to attach an :term:`ACL` to a
+:term:`context` object; the ACL is checked by the framework itself
+instead of by user code, and access is permitted or denied by the
+framework itself rather than by user code.  Such a task would
+typically be performed by user-space decorators in other Python web
+frameworks.
+
+Unlike application development using Zope, application developers
+don't interact with the Zope Component Architecture ("CA") very much
+during :mod:`repoze.bfg` application development.  Instead, the
+:mod:`repoze.bfg` framework tends to "hide" most interaction with the
+CA behind special-purpose API functions.
+
 Why?
 ----
 
diff --git a/docs/narr/views.rst b/docs/narr/views.rst
index edbe03d82..6eb42a0cd 100644
--- a/docs/narr/views.rst
+++ b/docs/narr/views.rst
@@ -61,6 +61,8 @@ If a view happens to return something to the :mod:`repoze.bfg`
 publisher that does not implement this interface, the publisher will
 raise an error.
 
+.. _mapping_views_to_urls_using_zcml_section:
+
 Mapping Views to URLs Using ZCML
 --------------------------------
 
@@ -159,6 +161,8 @@ request_type
   called.  See :ref:`view_request_types_section` for more
   information about view security and permissions.
 
+.. _mapping_views_to_urls_using_a_decorator_section:
+
 Mapping Views to URLs Using a Decorator
 ---------------------------------------