docs fixes

3 files changed, 34 insertions, 20 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
diff --git a/pyramid/url.py b/pyramid/url.py
index d1c1b6f42..efcf241b7 100644
--- a/pyramid/url.py
+++ b/pyramid/url.py
@@ -160,13 +160,18 @@ class URLMethodsMixin(object):
         element will always follow the query element,
         e.g. ``http://example.com?foo=1#bar``.
 
-        If any of ``_scheme``, ``_host``, or ``_port`` is passed and is
-        non-``None``, the provided value will replace the named portion in
-        the generated URL.  If ``_scheme`` is passed as ``https``, and
+        If any of the keyword arguments ``_scheme``, ``_host``, or ``_port``
+        is passed and is non-``None``, the provided value will replace the
+        named portion in the generated URL.  For example, if you pass
+        ``_host='foo.com'``, and the URL that would have been generated
+        without the host replacement is ``http://example.com/a``, the result
+        will be ``https://foo.com/a``.
+        
+        Note that if ``_scheme`` is passed as ``https``, and ``_port`` is not
+        passed, the ``_port`` value is assumed to have been passed as
+        ``443``.  Likewise, if ``_scheme`` is passed as ``http`` and
         ``_port`` is not passed, the ``_port`` value is assumed to have been
-        passed as ``443``.  Likewise, if ``_scheme`` is passed as ``http``
-        and ``_port`` is not passed, the ``_port`` value is assumed to have
-        been passed as ``80``. To avoid this behavior, always explicitly pass
+        passed as ``80``. To avoid this behavior, always explicitly pass
         ``_port`` whenever you pass ``_scheme``.
 
         If a keyword ``_app_url`` is present, it will be used as the
@@ -362,9 +367,9 @@ class URLMethodsMixin(object):
         If any of the keyword arguments ``scheme``, ``host``, or ``port`` is
         passed and is non-``None``, the provided value will replace the named
         portion in the generated URL.  For example, if you pass
-        ``scheme='https'``, and the URL that would be generated without the
-        scheme replacement is ``http://foo.com``, the result will be
-        ``https://foo.com``.
+        ``host='foo.com'``, and the URL that would have been generated
+        without the host replacement is ``http://example.com/a``, the result
+        will be ``https://foo.com/a``.
         
         If ``scheme`` is passed as ``https``, and an explicit ``port`` is not
         passed, the ``port`` value is assumed to have been passed as ``443``.