docs fixes

2 files changed, 20 insertions, 11 deletions

diff --git a/docs/narr/resources.rst b/docs/narr/resources.rst
index 83734be9f..a24c44f29 100644
--- a/docs/narr/resources.rst
+++ b/docs/narr/resources.rst
@@ -303,13 +303,22 @@ The ``__resource_url__`` hook is passed two arguments: ``request`` and
 two keys:
 
 ``physical_path``
-   The "physical path" computed for the resource, as defined by
-   ``pyramid.traversal.resource_path(resource)``.
+   A string representing the "physical path" computed for the resource, as
+   defined by ``pyramid.traversal.resource_path(resource)``.  It will begin
+   and end with a slash.
 
 ``virtual_path``
-   The "virtual path" computed for the resource, as defined by
-   :ref:`virtual_root_support`.  This will be identical to the physical path
-   if virtual rooting is not enabled.
+   A string representing the "virtual path" computed for the resource, as
+   defined by :ref:`virtual_root_support`.  This will be identical to the
+   physical path if virtual rooting is not enabled.  It will begin and end
+   with a slash.
+
+``app_url``
+  A string representing the application URL generated during
+  ``request.resource_url``.  It will not end with a slash.  It represents a
+  potentially customized URL prefix, containing potentially custom scheme,
+  host and port information passed by the user to ``request.resource_url``.
+  It should be preferred over use of ``request.application_url``.
 
 The ``__resource_url__`` method of a resource should return a string
 representing a URL.  If it cannot override the default, it should return
@@ -322,16 +331,16 @@ Here's an example ``__resource_url__`` method.
 
    class Resource(object):
        def __resource_url__(self, request, info):
-           return request.application_url + info['virtual_path']
+           return info['app_url'] + info['virtual_path']
 
 The above example actually just generates and returns the default URL, which
-would have been what was returned anyway, but your code can perform arbitrary
-logic as necessary.  For example, your code may wish to override the hostname
-or port number of the generated URL.
+would have been what was generated by the default ``resource_url`` machinery,
+but your code can perform arbitrary logic as necessary.  For example, your
+code may wish to override the hostname or port number of the generated URL.
 
 Note that the URL generated by ``__resource_url__`` should be fully
 qualified, should end in a slash, and should not contain any query string or
-anchor elements (only path elements) to work best with
+anchor elements (only path elements) to work with
 :meth:`~pyramid.request.Request.resource_url`.
 
 .. index::
diff --git a/docs/whatsnew-1.3.rst b/docs/whatsnew-1.3.rst
index 7d1c9217d..674b16e11 100644
--- a/docs/whatsnew-1.3.rst
+++ b/docs/whatsnew-1.3.rst
@@ -274,7 +274,7 @@ Minor Feature Additions
   ``ignore`` argument, which can be a string, a callable, or a list
   consisting of strings and/or callables.  This feature allows submodules,
   subpackages, and global objects from being scanned.  See
-   http://readthedocs.org/docs/venusian/en/latest/#ignore-scan-argument for
+  http://readthedocs.org/docs/venusian/en/latest/#ignore-scan-argument for
   more information about how to use the ``ignore`` argument to ``scan``.
 
 - Better error messages when a view callable returns a value that cannot be