Document RedirectHandler

diff --git a/website/templates/documentation.txt b/website/templates/documentation.txt
index 81f93c1825fc5a08c23ba7569ac6cddc3962f329..746c4974279a89432f0a9520de2bfc2af9462587 100644 (file)
--- a/website/templates/documentation.txt
+++ b/website/templates/documentation.txt
@@ -207,8 +207,11 @@ Other methods designed for overriding include:
 
 ### Redirection
 
+There are two main ways you can redirect requests in Tornado:
+`self.redirect` and with the `RedirectHandler`.
+
 You can use `self.redirect` within a
-`RequestHandler` to redirect users elsewhere. 
+`RequestHandler` method (like `get`) to redirect users elsewhere. 
 There is also an optional 
 parameter `permanent` which you can use to indicate
 that the redirection is considered permanent.  
@@ -222,6 +225,28 @@ users on successful POST requests.
 
        self.redirect('/some-canonical-page', permanent=True)
 
+`RedirectHandler` is available for your use when you initialize `Application`.
+
+For example, notice how we redirect to a longer download URL on this website:
+
+    application = tornado.wsgi.WSGIApplication([
+        (r"/([a-z]*)", ContentHandler),
+        (r"/static/tornado-0.2.tar.gz", tornado.web.RedirectHandler,
+         dict(url="http://github.com/downloads/facebook/tornado/tornado-0.2.tar.gz")),
+    ], **settings)
+
+The default `RedirectHandler` status code is `301 Moved Permanently`, but to use
+`302 Found` instead, set `permanent` to `False`.
+
+    application = tornado.wsgi.WSGIApplication([
+        (r"/foo", tornado.web.RedirectHandler, {"url":"/bar", "permanent":False}),
+    ], **settings)
+
+Note that the default value of `permanent` is different in `self.redirect` than in `RedirectHandler`.
+This should make some sense if you consider that `self.redirect` is used in your methods
+and is probably invoked by logic involving environment, authentication, or form submission,
+but `RedirectHandler` patterns are going to fire 100% of the time they match the request URL.
+
 ### Templates
 
 You can use any template language supported by Python, but Tornado ships