fix permission discussion

2 files changed, 58 insertions, 56 deletions

diff --git a/docs/narr/static.rst b/docs/narr/static.rst
index e6be5fdff..d4f6da76d 100644
--- a/docs/narr/static.rst
+++ b/docs/narr/static.rst
@@ -42,16 +42,24 @@ files that live in ``/var/www/static`` as sub-URLs of the ``/static`` URL
 prefix.  Therefore, the file ``/var/www/static/foo.css`` will be returned
 when the user visits your application's URL ``/static/foo.css``.
 
-No authorization is ever required for users to visit files served by a static
-view added via :meth:`~pyramid.config.Configurator.add_static_view`.  If you
-need "static" resources to be protected by authentication services, see
-:ref:`advanced_static`.
-
 A static directory named at ``path`` may contain subdirectories recursively,
 and any subdirectories may hold files; these will be resolved by the static
 view as you would expect.  The ``Content-Type`` header returned by the static
 view for each particular type of file is dependent upon its file extension.
 
+By default, all files made available via
+:meth:`~pyramid.config.Configurator.add_static_view` are accessible by
+completely anonymous users.  Simple authorization can be required, however.
+To protect a set of static files using a permission, in addition to passing
+the required ``name`` and ``path`` arguments, also pass the ``permission``
+keyword argument to :meth:`~pyramid.config.Configurator.add_static_view`.
+The value of the ``permission`` argument represents the :term:`permission`
+that the user must have relative to the current :term:`context` when the
+static view is invoked.  A user will be required to possess this permission
+to view any of the files represented by ``path`` of the static view.  If your
+static resources must be protected by a more complex authorization scheme,
+see :ref:`advanced_static`.
+
 Here's another example that uses an :term:`asset specification` instead of an
 absolute path as the ``path`` argument.  To convince
 :meth:`pyramid.config.Configurator.add_static_view` to serve files up under
diff --git a/pyramid/config.py b/pyramid/config.py
index 93123c119..2a18db4e9 100644
--- a/pyramid/config.py
+++ b/pyramid/config.py
@@ -2151,20 +2151,19 @@ class Configurator(object):
         """ Add a view used to render static assets such as images
         and CSS files.
 
-        The ``name`` argument is a string representing :term:`view
-        name` of the view which is registered.  It may alternately be
-        a *url prefix*.
+        The ``name`` argument is a string representing an
+        application-relative local URL prefix.  It may alternately be a full
+        URL.
 
-        The ``path`` argument is the path on disk where the static
-        files reside.  This can be an absolute path, a
-        package-relative path, or a :term:`asset specification`.
+        The ``path`` argument is the path on disk where the static files
+        reside.  This can be an absolute path, a package-relative path, or a
+        :term:`asset specification`.
 
         The ``cache_max_age`` keyword argument is input to set the
-        ``Expires`` and ``Cache-Control`` headers for static assets
-        served.  Note that this argument has no effect when the
-        ``name`` is a *url prefix*.  By default, this argument is
-        ``None``, meaning that no particular Expires or Cache-Control
-        headers are set in the response.
+        ``Expires`` and ``Cache-Control`` headers for static assets served.
+        Note that this argument has no effect when the ``name`` is a *url
+        prefix*.  By default, this argument is ``None``, meaning that no
+        particular Expires or Cache-Control headers are set in the response.
 
         The ``permission`` keyword argument is used to specify the
         :term:`permission` required by a user to execute the static view.  By
@@ -2178,67 +2177,62 @@ class Configurator(object):
 
         *Usage*
 
-        The ``add_static_view`` function is typically used in
-        conjunction with the :func:`pyramid.url.static_url`
-        function.  ``add_static_view`` adds a view which renders a
-        static asset when some URL is visited;
-        :func:`pyramid.url.static_url` generates a URL to that
-        asset.
+        The ``add_static_view`` function is typically used in conjunction
+        with the :func:`pyramid.url.static_url` function.
+        ``add_static_view`` adds a view which renders a static asset when
+        some URL is visited; :func:`pyramid.url.static_url` generates a URL
+        to that asset.
 
-        The ``name`` argument to ``add_static_view`` is usually a
-        :term:`view name`.  When this is the case, the
-        :func:`pyramid.url.static_url` API will generate a URL
-        which points to a Pyramid view, which will serve up a set of
-        assets that live in the package itself. For example:
+        The ``name`` argument to ``add_static_view`` is usually a :term:`view
+        name`.  When this is the case, the :func:`pyramid.url.static_url` API
+        will generate a URL which points to a Pyramid view, which will serve
+        up a set of assets that live in the package itself. For example:
 
         .. code-block:: python
 
            add_static_view('images', 'mypackage:images/')
 
-        Code that registers such a view can generate URLs to the view
-        via :func:`pyramid.url.static_url`:
+        Code that registers such a view can generate URLs to the view via
+        :func:`pyramid.url.static_url`:
 
         .. code-block:: python
 
            static_url('mypackage:images/logo.png', request)
 
-        When ``add_static_view`` is called with a ``name`` argument
-        that represents a simple view name, as it is above, subsequent
-        calls to :func:`pyramid.url.static_url` with paths that
-        start with the ``path`` argument passed to ``add_static_view``
-        will generate a URL something like ``http://<Pyramid app
-        URL>/images/logo.png``, which will cause the ``logo.png`` file
-        in the ``images`` subdirectory of the ``mypackage`` package to
-        be served.
-
-        ``add_static_view`` can alternately be used with a ``name``
-        argument which is a *URL*, causing static assets to be
-        served from an external webserver.  This happens when the
-        ``name`` argument is a URL (detected as any string with a
-        slash in it).  In this mode, the ``name`` is used as the URL
-        prefix when generating a URL using
-        :func:`pyramid.url.static_url`.  For example, if
-        ``add_static_view`` is called like so:
+        When ``add_static_view`` is called with a ``name`` argument that
+        represents a URL prefix, as it is above, subsequent calls to
+        :func:`pyramid.url.static_url` with paths that start with the
+        ``path`` argument passed to ``add_static_view`` will generate a URL
+        something like ``http://<Pyramid app URL>/images/logo.png``, which
+        will cause the ``logo.png`` file in the ``images`` subdirectory of
+        the ``mypackage`` package to be served.
+
+        ``add_static_view`` can alternately be used with a ``name`` argument
+        which is a *URL*, causing static assets to be served from an external
+        webserver.  This happens when the ``name`` argument is a fully
+        qualified URL (e.g. starts with ``http://`` or similar).  In this
+        mode, the ``name`` is used as the prefix of the full URL when
+        generating a URL using :func:`pyramid.url.static_url`.  For example,
+        if ``add_static_view`` is called like so:
 
         .. code-block:: python
 
            add_static_view('http://example.com/images', 'mypackage:images/')
 
-        Subsequently, the URLs generated by
-        :func:`pyramid.url.static_url` for that static view will be
-        prefixed with ``http://example.com/images``:
+        Subsequently, the URLs generated by :func:`pyramid.url.static_url`
+        for that static view will be prefixed with
+        ``http://example.com/images``:
 
         .. code-block:: python
 
            static_url('mypackage:images/logo.png', request)
 
-        When ``add_static_view`` is called with a ``name`` argument
-        that is the URL prefix ``http://example.com/images``,
-        subsequent calls to :func:`pyramid.url.static_url` with
-        paths that start with the ``path`` argument passed to
-        ``add_static_view`` will generate a URL something like
-        ``http://example.com/logo.png``.  The external webserver
-        listening on ``example.com`` must be itself configured to
+        When ``add_static_view`` is called with a ``name`` argument that is
+        the URL ``http://example.com/images``, subsequent calls to
+        :func:`pyramid.url.static_url` with paths that start with the
+        ``path`` argument passed to ``add_static_view`` will generate a URL
+        something like ``http://example.com/logo.png``.  The external
+        webserver listening on ``example.com`` must be itself configured to
         respond properly to such a request.
 
         See :ref:`static_assets_section` for more information.