1 files changed, 36 insertions, 8 deletions
diff --git a/docs/narr/urldispatch.rst b/docs/narr/urldispatch.rst
index 18cb3e4db..61849c3c0 100644
--- a/docs/narr/urldispatch.rst
+++ b/docs/narr/urldispatch.rst
@@ -105,6 +105,7 @@ to using the previous combination of ``add_route`` and ``add_view``.
 
 .. _route_pattern_syntax:
 
+
 Route Pattern Syntax
 ~~~~~~~~~~~~~~~~~~~~
 
@@ -127,6 +128,10 @@ and:
 
    /{foo}/bar/baz
 
+If a pattern is a valid URL it won't be ever matched against an incoming
+request. Instead it can be useful for generating external URLs. See
+:ref:`External routes <external_route_narr>` for details.
+
 A pattern segment (an individual item between ``/`` characters in the
 pattern) may either be a literal string (e.g. ``foo``) *or* it may be a
 replacement marker (e.g. ``{foo}``) or a certain combination of both. A
@@ -394,13 +399,6 @@ process.  Examples of route predicate arguments are ``pattern``, ``xhr``, and
 Other arguments are ``name`` and ``factory``.  These arguments represent
 neither predicates nor view configuration information.
 
-.. warning::
-
-   Some arguments are view-configuration related arguments, such as
-   ``view_renderer``.  These only have an effect when the route configuration
-   names a ``view`` and these arguments have been deprecated as of
-   :app:`Pyramid` 1.1.
-
 .. index::
    single: route matching
 
@@ -754,9 +752,39 @@ other non-``name`` and non-``pattern`` arguments to
 exception to this rule is use of the ``pregenerator`` argument, which is not
 ignored when ``static`` is ``True``.
 
+:ref:`External routes <external_route_narr>` are implicitly static.
+
 .. versionadded:: 1.1
    the ``static`` argument to :meth:`~pyramid.config.Configurator.add_route`
 
+.. _external_route_narr:
+
+
+External Routes
+---------------
+
+.. versionadded:: 1.5
+
+Route patterns that are valid URLs, are treated as external routes. Like
+:ref:`static routes <static_route_narr>` they are useful for URL generation
+purposes only and are never considered for matching at request time.
+
+.. code-block:: python
+   :linenos:
+
+   >>> config = Configurator()
+   >>> config.add_route('youtube', 'https://youtube.com/watch/{video_id}')
+   ...
+   >>> request.route_url('youtube', video_id='oHg5SJYRHA0')
+   >>> "https://youtube.com/watch/oHg5SJYRHA0"
+
+Most pattern replacements and calls to
+:meth:`pyramid.request.Request.route_url` will work as expected. However, calls
+to :meth:`pyramid.request.Request.route_path` against external patterns will
+raise an exception, and passing ``_app_url`` to
+:meth:`~pyramid.request.Request.route_url` to generate a URL against a route
+that has an external pattern will also raise an exception.
+
 .. index::
    single: redirecting to slash-appended routes
 
@@ -865,7 +893,7 @@ Debugging Route Matching
 ------------------------
 
 It's useful to be able to take a peek under the hood when requests that enter
-your application arent matching your routes as you expect them to.  To debug
+your application aren't matching your routes as you expect them to.  To debug
 route matching, use the ``PYRAMID_DEBUG_ROUTEMATCH`` environment variable or the
 ``pyramid.debug_routematch`` configuration file setting (set either to ``true``).
 Details of the route matching decision for a particular request to the