APPEND_SLASH behaviour should be documented better

[ttencate@…]

Current docs say:

APPEND_SLASH

Default: True

Whether to append trailing slashes to URLs. This is only used if
CommonMiddleware is installed (see Middleware). See also PREPEND_WWW.

This is not the complete story: a slash is appended only if the URL without slash does not match any in the urlconf. This becomes an issue if the urlconf has patterns that are subsets of other patterns, like this:

urlpatterns = patterns('',
    (r'^blog/', 'blog.views.index'),
    (r'^(?P<pagename>\w+)/', 'pages.views.page'),

Even though pages.views.page does not know a page named blog, and would thus return a 404, APPEND_SLASHES will recognize /blog as a valid URL and not append the slash. I realize that this cannot be solved without actually running the view (which we don't want to do), but this behaviour should be documented.

A note about the fact that a HTTP redirect happens (and thus a round trip to the client) would also be nice.

Suggested wording:

APPEND_SLASH

Default: True

Whether to append trailing slashes to URLs. If an URL does not match
any of the patterns in the URLconf, and it doesn't end in a slash, a
HTTP redirect is issued to the same URL with the slash appended.
(Note that data in a POST request will be lost, which might not be
what you want.) The APPEND_SLASH setting is only used if
CommonMiddleware is installed (see Middleware). See also PREPEND_WWW.

[Gabriel Hurley]

(In [14110]) Fixed #14228 -- Added additional information on what the APPEND_SLASH setting does. Thanks to ttencate for the report and draft text.