explain relative asset spec

1 files changed, 10 insertions, 1 deletions

diff --git a/docs/narr/assets.rst b/docs/narr/assets.rst
index 84fe42186..be3325a11 100644
--- a/docs/narr/assets.rst
+++ b/docs/narr/assets.rst
@@ -72,6 +72,15 @@ eventually passes this resolved absolute filesystem path to the Chameleon
 templating engine, which then uses it to load, parse, and execute the
 template file.
 
+There is a second form of asset specification: a *relative* asset
+specification.  Instead of using an "absolute" asset specification which
+includes the package name, in certain circumstances you can omit the package
+name.  For example, you might be able to use ``templates/mytemplate.pt``
+instead of ``myapp:templates/some_template.pt``.  Such asset specifications
+are usually relative to a "current package."  The "current package" is
+usually the package which contains the code that *uses* the asset
+specification.
+
 .. index::
    single: add_static_view
 
@@ -143,7 +152,7 @@ specification` as the ``path``:
    config.add_static_view(name='static', path='some_package:a/b/c/static')
 
 The ``path`` provided to :meth:`pyramid.config.Configurator.add_static_view`
-may be a fully qualified :term:`asset specification`, or an *absolute path*.
+may be a fully qualified :term:`asset specification` or an *absolute path*.
 
 Instead of representing a URL prefix, the ``name`` argument of a call to
 :meth:`pyramid.config.Configurator.add_static_view` can alternately be a