[1.0.X] Documented how to handle '%' characters in redirect_to() URL strings

(even in the absence of keyword arguments). Fixed #9773.

Backport of r9626 from trunk.


git-svn-id: http://code.djangoproject.com/svn/django/branches/releases/1.0.X@9627 bcc190cf-cafb-0310-a4f2-bffc1f526a37

1 files changed, 12 insertions, 1 deletions

diff --git a/docs/ref/generic-views.txt b/docs/ref/generic-views.txt
index c14cc295d2..c5f4476764 100644
--- a/docs/ref/generic-views.txt
+++ b/docs/ref/generic-views.txt
@@ -120,7 +120,10 @@ variable ``{{ params.id }}`` that is set to ``15``.
 Redirects to a given URL.
 
 The given URL may contain dictionary-style string formatting, which will be
-interpolated against the parameters captured in the URL.
+interpolated against the parameters captured in the URL. Because keyword
+interpolation is *always* done (even if no arguments are passed in), any ``"%"``
+characters in the URL must be written as ``"%%"`` so that Python will convert
+them to a single percent sign on output.
 
 If the given URL is ``None``, Django will return an ``HttpResponseGone`` (410).
 
@@ -143,6 +146,14 @@ This example returns a 410 HTTP error for requests to ``/bar/``::
         ('^bar/$', 'redirect_to', {'url': None}),
     )
 
+This example shows how ``"%"`` characters must be written in the URL in order
+to avoid confusion with Python's string formatting markers. If the redirect
+string is written as ``"%7Ejacob/"`` (with only a single ``%``), an exception would be raised::
+
+    urlpatterns = patterns('django.views.generic.simple',
+        ('^bar/$', 'redirect_to', {'url': '%%7Ejacob.'}),
+    )
+
 Date-based generic views
 ========================