Add more docs around autoescape changes

website/sphinx/overview.rst

@@ -317,6 +317,14 @@ replacing ``{{ ... }}`` with ``{% raw ...%}``. Additionally, in each of
 these places the name of an alternative escaping function may be used
 instead of ``None``.
 
+Note that while Tornado's automatic escaping is helpful in avoiding
+XSS vulnerabilities, it is not sufficient in all cases.  Expressions
+that appear in certain locations, such as in Javascript or CSS, may need
+additional escaping.  Additionally, either care must be taken to always
+use double quotes and ``xhtml_escape`` in HTML attributes that may contain
+untrusted content, or a separate escaping function must be used for
+attributes (see e.g. http://wonko.com/post/html-escaping)
+
 Cookies and secure cookies
 ~~~~~~~~~~~~~~~~~~~~~~~~~~
 

website/sphinx/releases/v2.0.0.rst

@@ -17,6 +17,8 @@ Jun 21, 2011
       a previous release of Tornado must either disable autoescaping or adapt
       their templates to work with it.  For most applications, the simplest
       way to do this is to pass autoescape=None to the Application constructor.
+      Note that this affects certain built-in methods, e.g. xsrf_form_html
+      and linkify, which must now be called with {% raw %} instead of {}
     * Applications that wish to continue using curl_httpclient instead of
       simple_httpclient may do so by calling
         AsyncHTTPClient.configure("tornado.curl_httpclient.CurlAsyncHTTPClient")