model->resource; make docs render without warnings

9 files changed, 58 insertions, 54 deletions

diff --git a/docs/narr/declarative.rst b/docs/narr/declarative.rst
index 54e9ecaa1..28dec4ff1 100644
--- a/docs/narr/declarative.rst
+++ b/docs/narr/declarative.rst
@@ -720,19 +720,19 @@ documentation.
 .. index::
    triple: view; zcml; static resource
 
-.. _zcml_static_resources_section:
+.. _zcml_static_assets_section:
 
-Serving Static Resources Using ZCML
-------------------------------------
+Serving Static Assets Using ZCML
+--------------------------------
 
-Use of the ``static`` ZCML directive makes static files available at a name
-relative to the application root URL, e.g. ``/static``.  
+Use of the ``static`` ZCML directive makes static assets available at a name
+relative to the application root URL, e.g. ``/static``.
 
 Note that the ``path`` provided to the ``static`` ZCML directive may be a
-fully qualified :term:`resource specification`, a package-relative path, or
+fully qualified :term:`asset specification`, a package-relative path, or
 an *absolute path*.  The ``path`` with the value ``a/b/c/static`` of a
 ``static`` directive in a ZCML file that resides in the "mypackage" package
-will resolve to a package-qualified resource such as
+will resolve to a package-qualified assets such as
 ``some_package:a/b/c/static``.
 
 Here's an example of a ``static`` ZCML directive that will serve files
@@ -751,7 +751,7 @@ absolute path.
 Here's an example of a ``static`` directive that will serve files up
 under the ``/static`` URL from the ``a/b/c/static`` directory of the
 Python package named ``some_package`` using a fully qualified
-:term:`resource specification`.
+:term:`asset specification`.
 
 .. code-block:: xml
    :linenos:
@@ -774,7 +774,7 @@ package-relative path.
      path="static"
     />
 
-Whether you use for ``path`` a fully qualified resource specification,
+Whether you use for ``path`` a fully qualified asset specification,
 an absolute path, or a package-relative path, When you place your
 static files on the filesystem in the directory represented as the
 ``path`` of the directive, you will then be able to view the static
@@ -791,7 +791,7 @@ While the ``path`` argument can be a number of different things, the
 ``name`` argument of the ``static`` ZCML directive can also be one of
 a number of things: a *view name* or a *URL*.  The above examples have
 shown usage of the ``name`` argument as a view name.  When ``name`` is
-a *URL* (or any string with a slash (``/``) in it), static resources
+a *URL* (or any string with a slash (``/``) in it), static assets
 can be served from an external webserver.  In this mode, the ``name``
 is used as the URL prefix when generating a URL using
 :func:`pyramid.url.static_url`.
@@ -819,7 +819,7 @@ detail later in this chapter.
 The :meth:`pyramid.config.Configurator.add_static_view` method offers
 an imperative equivalent to the ``static`` ZCML directive.  Use of the
 ``add_static_view`` imperative configuration method is completely equivalent
-to using ZCML for the same purpose.  See :ref:`static_resources_section` for
+to using ZCML for the same purpose.  See :ref:`static_assets_section` for
 more information.
 
 .. index::
diff --git a/docs/narr/environment.rst b/docs/narr/environment.rst
index 8cad9a666..0c6f3dd03 100644
--- a/docs/narr/environment.rst
+++ b/docs/narr/environment.rst
@@ -61,7 +61,7 @@ also :ref:`overriding_assets_section`.
 +---------------------------------+-----------------------------+
 | Environment Variable Name       | Config File Setting Name    |
 +=================================+=============================+
-| ``BFG_RELOAD_ASSETS`   `        |  ``reload_assets``          |
+| ``BFG_RELOAD_ASSETS``           |  ``reload_assets``          |
 |                                 |                             |
 |                                 |                             |
 |                                 |                             |
diff --git a/docs/narr/handlers.rst b/docs/narr/handlers.rst
index f6e658cf0..5b6f71984 100644
--- a/docs/narr/handlers.rst
+++ b/docs/narr/handlers.rst
@@ -100,7 +100,7 @@ Using :meth:`~pyramid.config.Configurator.add_handler`
 When calling :meth:`~pyramid.config.Configurator.add_handler`, an
 ``action`` is required in either the route pattern or as a keyword argument,
 but **cannot appear in both places**. A ``handler`` argument must also be
-supplied, which can be either a :term:`resource specification` or a Python
+supplied, which can be either a :term:`asset specification` or a Python
 reference to the handler class. Additional keyword arguments are passed
 directly through to :meth:`pyramid.config.Configurator.add_route`.
 
@@ -112,7 +112,7 @@ For example:
     config.add_handler('hello', '/hello/{action}',
                        handler='mypackage.handlers:MyHandler')
 
-In larger applications, it is advised to use a :term:`resource specification`
+In larger applications, it is advised to use a :term:`asset specification`
 with :meth:`~pyramid.config.Configurator.add_handler` to avoid having
 to import every handler class.
 
diff --git a/docs/narr/introduction.rst b/docs/narr/introduction.rst
index 0d8077fc4..3ade3726c 100644
--- a/docs/narr/introduction.rst
+++ b/docs/narr/introduction.rst
@@ -178,10 +178,11 @@ frameworks, :app:`Pyramid` also generally fits into this class.
 
    The :app:`Pyramid` authors believe that the MVC pattern just doesn't
    really fit the web very well. In a :app:`Pyramid` application, there is a
-   model, which stores data, and views, which present the data stored in the
-   model.  However, no facility provided by the framework actually maps to
-   the concept of a "controller".  So :app:`Pyramid` is actually an "MV"
-   framework rather than an "MVC" framework.  "MVC", however, is close enough
-   as a general classification moniker for purposes of comparison with other
-   web frameworks.
-
+   resource tree, which represents the site structure, and views, which tend
+   to present the data stored in the resource tree and a user-defined "domain
+   model".  However, no facility provided *by the framework* actually
+   necessarily maps to the concept of a "controller" or "model".  So if you
+   had to give it some acronym, I guess you'd say :app:`Pyramid` is actually
+   an "RV" framework rather than an "MVC" framework.  "MVC", however, is
+   close enough as a general classification moniker for purposes of
+   comparison with other web frameworks.
diff --git a/docs/narr/project.rst b/docs/narr/project.rst
index 27974d8df..ff03a57b8 100644
--- a/docs/narr/project.rst
+++ b/docs/narr/project.rst
@@ -790,13 +790,13 @@ also informs Python that the directory which contains it is a *package*.
    name`.  The view declaration also names a ``renderer``, which in this case
    is a template that will be used to render the result of the view callable.
    This particular view declaration points at
-   ``myproject:templates/mytemplate.pt``, which is a :term:`resource
+   ``myproject:templates/mytemplate.pt``, which is a :term:`asset
    specification` that specifies the ``mytemplate.pt`` file within the
    ``templates`` directory of the ``myproject`` package.  The template file
    it actually points to is a :term:`Chameleon` ZPT template file.
 
    Line 11 registers a static view, which will serve up the files from the
-   ``mypackage:static`` :term:`resource specification` (the ``static``
+   ``mypackage:static`` :term:`asset specification` (the ``static``
    directory of the ``mypackage`` package).
 
    Line 12 returns a :term:`WSGI` application to the caller of the function
@@ -874,10 +874,10 @@ sort of datastore you'll want to use, so the sample application uses an
 instance of :class:`myproject.resources.Root` to represent the root.
 
 ``static``
-~~~~~~~~~~~~~~~~~~~~
+~~~~~~~~~~
 
-This directory contains static resources which support the
-``mytemplate.pt`` template.  It includes CSS and images.
+This directory contains static assets which support the ``mytemplate.pt``
+template.  It includes CSS and images.
 
 .. index::
    single: tests.py
diff --git a/docs/narr/resources.rst b/docs/narr/resources.rst
index 05e108494..21ba97c9e 100644
--- a/docs/narr/resources.rst
+++ b/docs/narr/resources.rst
@@ -3,7 +3,7 @@ Resources
 
 A :term:`resource` is an object that represents a "place" in your
 application.  Every :app:`Pyramid` application has at least one resource
-object: the :term:`root resource`.  The root resource is the root of a
+object: the :term:`root` resource.  The root resource is the root of a
 :term:`resource tree`.  A resource tree is a set of nested dictionary-like
 objects which you may use to represent your website's structure.
 
@@ -25,7 +25,7 @@ that use traversal.
 In "Zope-like" :app:`Pyramid` applications, resource objects also often store
 data persistently and offer methods related to mutating that persistent data.
 In these kinds of applications, resources not only represent the site
-structure of your website, but they become the :term:`model` of the
+structure of your website, but they become the :term:`domain model` of the
 application.
 
 Also:
diff --git a/docs/narr/templates.rst b/docs/narr/templates.rst
index d6c21831e..adec9aa0c 100644
--- a/docs/narr/templates.rst
+++ b/docs/narr/templates.rst
@@ -84,9 +84,9 @@ prefix on Windows.
    file instead of treating relative paths as relative to the current
    view module.  See :ref:`mako_templates`.
 
-The path can alternately be a :term:`resource specification` in the form
+The path can alternately be a :term:`asset specification` in the form
 ``some.dotted.package_name:relative/path``. This makes it possible to
-address template resources which live in another package.  For example:
+address template assets which live in another package.  For example:
 
 .. code-block:: python
    :linenos:
@@ -98,20 +98,20 @@ address template resources which live in another package.  For example:
                                  {'foo':1, 'bar':2},
                                  request=request)
 
-A resource specification points at a file within a Python *package*.
+An asset specification points at a file within a Python *package*.
 In this case, it points at a file named ``foo.pt`` within the
 ``templates`` directory of the ``mypackage`` package.  Using a
-resource specification instead of a relative template name is usually
-a good idea, because calls to ``render_to_response`` using resource
+asset specification instead of a relative template name is usually
+a good idea, because calls to ``render_to_response`` using asset
 specifications will continue to work properly if you move the code
 containing them around.
 
 .. note::
 
-   Mako templating system bindings also respect absolute resource
+   Mako templating system bindings also respect absolute asset
    specifications as an argument to any of the ``render*`` commands.  If a
    template name defines a ``:`` (colon) character and is not an absolute
-   path, it is treated as an absolute resource specification.
+   path, it is treated as an absolute asset specification.
 
 In the examples above we pass in a keyword argument named ``request``
 representing the current :app:`Pyramid` request. Passing a request
@@ -187,8 +187,8 @@ combination as shown above.
    :app:`Pyramid` bindings directly within view callables, the
    auto-template-reload strategy explained in
    :ref:`reload_templates_section` will not be available, nor will the
-   template resource overriding capability explained in
-   :ref:`overriding_resources_section` be available, nor will it be
+   template asset overriding capability explained in
+   :ref:`overriding_assets_section` be available, nor will it be
    possible to use any template using that language as a
    :term:`renderer`.  However, it's reasonably easy to write custom
    templating system binding packages for use under :app:`Pyramid` so
@@ -289,7 +289,7 @@ to specify the template as a :term:`renderer` in your
 templating languages supported by :app:`Pyramid`.
 
 To use a renderer via view configuration, specify a template
-:term:`resource specification` as the ``renderer`` argument, or
+:term:`asset specification` as the ``renderer`` argument, or
 attribute to the :term:`view configuration` of a :term:`view
 callable`.  Then return a *dictionary* from that view callable.  The
 dictionary items returned by the view callable will be made available
@@ -326,7 +326,7 @@ template renderer:
    we're using a Chameleon renderer, it means "relative to the directory in
    which the file which defines the view configuration lives".  In this case,
    this is the directory containing the file that defines the ``my_view``
-   function.  View-configuration-relative resource specifications work only
+   function.  View-configuration-relative asset specifications work only
    in Chameleon, not in Mako templates.
 
 Similar renderer configuration can be done imperatively and via
@@ -335,9 +335,9 @@ Similar renderer configuration can be done imperatively and via
 
 Although a renderer path is usually just a simple relative pathname, a path
 named as a renderer can be absolute, starting with a slash on UNIX or a drive
-letter prefix on Windows.  The path can alternately be a :term:`resource
+letter prefix on Windows.  The path can alternately be an :term:`asset
 specification` in the form ``some.dotted.package_name:relative/path``, making
-it possible to address template resources which live in another package.
+it possible to address template assets which live in another package.
 
 Not just any template from any arbitrary templating system may be used as a
 renderer.  Bindings must exist specifically for :app:`Pyramid` to use a
@@ -473,15 +473,15 @@ least two top-level names available to the template by default: ``context``
 and ``request``.  One of the common needs in ZPT-based templates is to use
 one template's "macros" from within a different template.  In Zope, this is
 typically handled by retrieving the template from the ``context``.  But the
-context in :app:`Pyramid` is a resource object, and templates cannot usually
-be retrieved from resources.  To use macros in :app:`Pyramid`, you need to make
-the macro template itself available to the rendered template by passing the
-macro template, or even the macro itself, *into* the rendered template.  To
-do this you can use the :func:`pyramid.renderers.get_renderer` API to
-retrieve the macro template, and pass it into the template being rendered via
-the dictionary returned by the view.  For example, using a :term:`view
-configuration` via a :class:`pyramid.view.view_config` decorator that uses a
-:term:`renderer`:
+context in :app:`Pyramid` is a :term:`resource` object, and templates cannot
+usually be retrieved from resources.  To use macros in :app:`Pyramid`, you
+need to make the macro template itself available to the rendered template by
+passing the macro template, or even the macro itself, *into* the rendered
+template.  To do this you can use the :func:`pyramid.renderers.get_renderer`
+API to retrieve the macro template, and pass it into the template being
+rendered via the dictionary returned by the view.  For example, using a
+:term:`view configuration` via a :class:`pyramid.view.view_config` decorator
+that uses a :term:`renderer`:
 
 .. code-block:: python
    :linenos:
diff --git a/docs/narr/traversal.rst b/docs/narr/traversal.rst
index c8878224e..9bc6014cd 100644
--- a/docs/narr/traversal.rst
+++ b/docs/narr/traversal.rst
@@ -223,9 +223,12 @@ root factory always returns an object that has no child resources.
    availability is more useful when you're developing an application using
    :term:`URL dispatch`.
 
-Items contained within the resource tree are sometimes, in certain types of
-applications, analogous to the concept of :term:`model` objects used by many
-other frameworks.  They are typically instances of Python classes.
+.. note::
+
+   If the items contained within the resource tree are "persistent" (they
+   have state that lasts longer than the execution of a single process), they
+   become analogous to the concept of :term:`domain model` objects used by
+   many other frameworks.
 
 The resource tree consists of *container* resources and *leaf* resources.
 There is only one difference between a *container* resource and a *leaf*
diff --git a/docs/narr/urldispatch.rst b/docs/narr/urldispatch.rst
index 8adeb2511..739a826c1 100644
--- a/docs/narr/urldispatch.rst
+++ b/docs/narr/urldispatch.rst
@@ -613,7 +613,7 @@ represent neither predicates nor view configuration information.
 
 ``view_renderer``
   This is either a single string term (e.g. ``json``) or a string
-  implying a path or :term:`resource specification`
+  implying a path or :term:`asset specification`
   (e.g. ``templates/views.pt``).  If the renderer value is a single
   term (does not contain a dot ``.``), the specified term will be used
   to look up a renderer implementation, and that renderer