- Added a "Resources" chapter to the narrative documentation which

  explains how to override resources within one package from another
  package.

6 files changed, 230 insertions, 78 deletions

diff --git a/CHANGES.txt b/CHANGES.txt
index d601f3199..9a343aa50 100644
--- a/CHANGES.txt
+++ b/CHANGES.txt
@@ -8,7 +8,14 @@ Features
   environment variable (``BFG_CONFIGURE_ZCML``) to name a ZCML file
   that will be used to bootstrap the application.  Previously, the
   integrator could not influence which ZCML file was used to do the
-  boostrapping (only the original application developer).
+  boostrapping (only the original application developer could do so).
+
+Documentation
+-------------
+
+- Added a "Resources" chapter to the narrative documentation which
+  explains how to override resources within one package from another
+  package.
 
 1.0a9 (2009-07-01)
 ==================
diff --git a/docs/glossary.rst b/docs/glossary.rst
index 3abe31ea6..46b94d62d 100644
--- a/docs/glossary.rst
+++ b/docs/glossary.rst
@@ -24,6 +24,9 @@ Glossary
     non-Python-source that lives in a Python package can be considered
     a resource file.  See also `PkgResources
     <http://peak.telecommunity.com/DevCenter/PkgResources>`_
+  Resource
+    Any file contained within a Python :term:`package` which is *not*
+    a Python source code file.
   Package
     A directory on disk which contains an ``__init__.py`` file, making
     it recognizable to Python as a location which can be ``import`` -ed.
diff --git a/docs/index.rst b/docs/index.rst
index 41d3409b3..928ded272 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -35,6 +35,7 @@ Narrative documentation in chapter form explaining how to use
    narr/templates
    narr/models
    narr/security
+   narr/resources
    narr/hybrid
    narr/vhosting
    narr/events
diff --git a/docs/narr/hooks.rst b/docs/narr/hooks.rst
index 9eba8a92c..086dc16ad 100644
--- a/docs/narr/hooks.rst
+++ b/docs/narr/hooks.rst
@@ -118,81 +118,4 @@ an object that implements any particular interface; it simply needs
 have a ``status`` attribute, a ``headerlist`` attribute, and and
 ``app_iter`` attribute.
 
-.. _overriding_resources_section:
-
-Overriding Resources
---------------------
-
-A ZCML directive exists named "resource".  This ZCML directive allows
-you to override Chameleon templates within a package (both directories
-full of templates and individual template files) with other templates
-in the same package or within another package.  This allows you to
-"fake out" a view's use of a template, causing it to retrieve a
-different template than the one actually named by a relative path to a
-call like ``render_template_to_response('templates/mytemplate.pt')``.
-For example, you can override a template file by doing::
-
-    <resource
-      to_override="some.package:templates/mytemplate.pt"
-      override_with="another.package:othertemplates/anothertemplate.pt"
-     />
-
-The string passed to "to_override" and "override_with" is named a
-"specification".  The colon separator in a specification separates the
-package name from a package-relative directory name.  The colon and
-the following relative path are optional.  If they are not specified,
-the override attempts to resolve every lookup into a package from the
-directory of another package.  For example::
-
-    <resource
-      to_override="some.package"
-      override_with="another.package"
-     />
-
-
-Individual subdirectories within a package can also be overridden::
-
-    <resource
-      to_override="some.package:templates/"
-      override_with="another.package:othertemplates/"
-     />
-
-If you wish to override a directory with another directory, you must
-make sure to attach the slash to the end of both the ``to_override``
-specification and the ``override_with`` specification.  If you fail to
-attach a slash to the end of a specification that points a directory,
-you will get unexpected results.  You cannot override a directory
-specification with a file specification, and vice versa (a startup
-error will occur if you try).
-
-You cannot override a resource with itself (a startup error will
-occur if you try).
-
-Only individual *package* resources may be overridden.  Overrides will
-not traverse through subpackages within an overridden package.  This
-means that if you want to override resources for both
-``some.package:templates``, and ``some.package.views:templates``, you
-will need to register two overrides.
-
-The package name in a specification may start with a dot, meaning that
-the package is relative to the package in which the ZCML file resides.
-For example::
-
-    <resource
-      to_override=".subpackage:templates/"
-      override_with="another.package:templates/"
-     />
-
-Overrides for the same ``to_overrides`` specification can be named
-multiple times within ZCML.  Each ``override_with`` path will be
-consulted in the order defined within ZCML, forming an override search
-path.
-
-Resource overrides can actually override resources other than
-templates.  Any software which uses the ``pkg_resources``
-``get_resource_filename``, ``get_resource_stream`` or
-``get_resource_string`` APIs will obtain an overridden file when an
-override is used.  However, the only built-in facility which uses the
-``pkg_resources`` API within BFG is the templating stuff, so we only
-call out template overrides here.
 
diff --git a/docs/narr/project.rst b/docs/narr/project.rst
index b465082eb..a8b0ccdd4 100644
--- a/docs/narr/project.rst
+++ b/docs/narr/project.rst
@@ -7,6 +7,8 @@ You can use :mod:`repoze.bfg` 's sample application generator to get
 started.  This generator uses :term:`Paste` templates to allow
 creation of a new project by answering a series of questions.
 
+.. _creating_a_project:
+
 Creating the Project
 --------------------
 
diff --git a/docs/narr/resources.rst b/docs/narr/resources.rst
new file mode 100644
index 000000000..fb6e82de0
--- /dev/null
+++ b/docs/narr/resources.rst
@@ -0,0 +1,216 @@
+.. _resources_chapter:
+
+Resources
+=========
+
+A :term:`resource` is any file contained within a Python
+:term:`package` which is *not* a Python source code file.  For
+example, each of the following is a resource:
+
+- a :term:`Chameleon` template file contained within a Python package.
+
+- a GIF image file contained within a Python package.
+
+- a CSS file contined within a Python package.
+
+- a Javascript source file contained within a Python package.
+
+- A directory within a package that does not have an ``__init__.py``
+  in it (if it possessed an ``__init__.py`` it would *be* a package).
+
+The use of resources is quite common in most web development projects.
+For example, when you create a :mod:`repoze.bfg` application using one
+of the available "paster" templates, as described in
+:ref:`creating_a_project`, the directory representing the application
+contains a Python :term:`package`.  Within that Python package, there
+are directories full of files which are resources.  For example, there
+is a ``templates`` directory which contains ``.pt`` files, and a
+``static`` directory which contains ``.css``, ``.js``, and ``.gif``
+files.
+
+.. _understanding_resources:
+
+Understanding Resources
+-----------------------
+
+Let's imagine you've created a :mod:`repoze.bfg` application that uses
+a :term:`Chameleon` template via the ``render_template_to_response``
+API.  For example, the application might address the resource named
+``templates/some_template.pt`` using that API within a ``views.py``
+file inside a ``myapp`` package:
+
+.. code-block:: python
+   :linenos:
+
+   render_template_to_response('templates/some_template.pt')
+
+"Under the hood", when this API is called, :mod:`repoze.bfg` attempts
+to make sense out of the string ``templates/some_template.pt``
+provided by the developer.  To do so, it first finds the "current"
+package.  The "current" package is the Python package in which the
+``views.py`` module which contains this code lives.  This would be the
+``myapp`` package, according to our example so far.  By resolving the
+current package, :mod:`repoze.bfg` has enough information to locate
+the actual template file.  These are the elements it needs:
+
+- The *package name* (``myapp``)
+
+- The *resource name* (``templates/some_template.pt``)
+
+:mod:`repoze.bfg` uses the :term:`pkg_resources` API to resolve the
+package name and resource name to an absolute
+(operating-system-specific) file name.  It eventually passes this
+resolved absolute filesystem path to the Chameleon templating engine,
+which then uses it to load, parse, and execute the template file.
+
+Package names often contain dots.  For example, ``repoze.bfg`` is a
+package.  Resource names usually look a lot like relative UNIX file
+paths.
+
+.. _overriding_resources_section:
+
+Overriding Resources
+--------------------
+
+It can often be useful to override specific resources "from outside" a
+given :mod:`repoze.bfg` application.  For example, you may wish to
+reuse an existing :mod:`repoze.bfg` application more or less
+unchanged.  However, some specific template file owned by the
+application might have inappropriate HTML, or some static resource
+(such as a logo file or some CSS file) might not appropriate.  You
+*could* just fork the application entirely, but it's often more
+convenient to just override the resources that are inappropriate and
+reuse the application "as is".  This is particularly true when you
+reuse some "core" application over and over again for some set of
+customers (such as a CMS application, or some bug tracking
+application), and you want to make arbitrary visual modifications to a
+particular application deployment without forking the underlying code.
+
+To this end, :mod:`repoze.bfg` contains a feature that makes it
+possible to "override" one resource with one or more other resources.
+In support of this feature, a :term:`ZCML` directive exists named
+``resource``.  The ``resource`` directive allows you to *override* the
+following kinds of resources defined in any Python package:
+
+- Individual :term:`Chameleon` templates.
+
+- A directory containing multuple Chameleon templates.
+
+- Individual static files served up by an instance of the
+  ``repoze.bfg.view.static`` helper class.
+
+- A directory of static files served up by an instance of the
+  ``repoze.bfg.view.static`` helper class.
+
+- Any other resource (or set of resources) addressed by code that uses
+  the setuptools :term:`pkg_resources` API.
+
+Usually, overriding a resource in an existing application means
+performing the following steps:
+
+- Create a new Python package.  The easiest way to do this is to
+  create a new :mod:`repoze.bfg` application using the "paster"
+  template mechanism.  See :ref:`creating_a_project` for more
+  information.
+
+- Install the new package into the same Python environment as the
+  original application (e.g. ``python setup.py develop`` or ``python
+  setup.py install``).
+
+- Change the ``configure.zcml`` in the new package to include one or
+  more ``resource`` ZCML directives (see :ref:`resource_directive`
+  below).  The new package's ``configure.zcml`` should then include
+  the original :mod:`repoze.bfg` application's ``configure.zcml`` via
+  an include statement, e.g.  ``<include
+  package="theoriginalpackage"/>``.
+
+- Add override resources to the package as necessary.
+
+- Change the Paste ``.ini`` file that starts up the original
+  application.  Add a ``configure_zcml`` statement within the
+  application's section in the file which points at your *new*
+  package's ``configure.zcml`` file.  See :ref:`environment_chapter`
+  for more information about this setting.
+
+.. _resource_directive:
+
+The ``resource`` ZCML Directive
+-------------------------------
+
+An individual :mod:`repoze.bfg` ``resource`` ZCML statement can
+override a single resource.  For example:
+
+.. code-block:: xml
+   :linenos:
+
+    <resource
+      to_override="some.package:templates/mytemplate.pt"
+      override_with="another.package:othertemplates/anothertemplate.pt"
+    />
+
+The string value passed to both ``to_override`` and ``override_with``
+attached to a resource directive is called a "specification".  The
+colon separator in a specification separates the *package name* from
+the *resource name*.  The colon and the following resource name are
+optional.  If they are not specified, the override attempts to resolve
+every lookup into a package from the directory of another package.
+For example:
+
+.. code-block:: xml
+   :linenos:
+
+    <resource
+      to_override="some.package"
+      override_with="another.package"
+     />
+
+Individual subdirectories within a package can also be overridden:
+
+.. code-block:: xml
+   :linenos:
+
+    <resource
+      to_override="some.package:templates/"
+      override_with="another.package:othertemplates/"
+     />
+
+If you wish to override a directory with another directory, you *must*
+make sure to attach the slash to the end of both the ``to_override``
+specification and the ``override_with`` specification.  If you fail to
+attach a slash to the end of a specification that points a directory,
+you will get unexpected results.
+
+You cannot override a directory specification with a file
+specification, and vice versa (a startup error will occur if you try).
+You cannot override a resource with itself (a startup error will occur
+if you try).
+
+Only individual *package* resources may be overridden.  Overrides will
+not traverse through subpackages within an overridden package.  This
+means that if you want to override resources for both
+``some.package:templates``, and ``some.package.views:templates``, you
+will need to register two overrides.
+
+The package name in a specification may start with a dot, meaning that
+the package is relative to the package in which the ZCML file resides.
+For example:
+
+.. code-block:: xml
+   :linenos:
+
+    <resource
+      to_override=".subpackage:templates/"
+      override_with="another.package:templates/"
+     />
+
+Multiple ``resource`` statements which name a shared ``to_override``
+but a different ``override_with`` specification can be "stacked" to
+form a search path.  The first resource that exists in the search path
+will be used; if no resource exists in the override path, the original
+resource is used.
+
+Resource overrides can actually override resources other than
+templates and static files.  Any software which uses the
+``pkg_resources`` ``get_resource_filename``, ``get_resource_stream``
+or ``get_resource_string`` APIs will obtain an overridden file when an
+override is used.