From 18810458067445b3f02b75d16a84ff78042b3824 Mon Sep 17 00:00:00 2001
From: Fabien Potencier <fabien.potencier@gmail.com>
Date: Tue, 30 Oct 2012 10:25:30 +0100
Subject: [PATCH] added a note about double-escaping when using a variable for the strategy (closes #868)

---
 doc/api.rst            |    8 ++++----
 doc/filters/escape.rst |   27 +++++++++++++++++++++++++++
 2 files changed, 31 insertions(+), 4 deletions(-)

diff --git a/doc/api.rst b/doc/api.rst
index 2ac0aaf..fbcc8bc 100644
--- a/doc/api.rst
+++ b/doc/api.rst
@@ -496,10 +496,10 @@ The escaping rules are implemented as follows:
 
   .. code-block:: jinja
 
-        {% autoescape true js %}
-        {{ var|escape('html') }} {# will be escaped for html and javascript #}
-        {{ var }} {# will be escaped for javascript #}
-        {{ var|escape('js') }} {# won't be double-escaped #}
+        {% autoescape 'js' %}
+            {{ var|escape('html') }} {# will be escaped for html and javascript #}
+            {{ var }} {# will be escaped for javascript #}
+            {{ var|escape('js') }} {# won't be double-escaped #}
         {% endautoescape %}
 
 .. note::
diff --git a/doc/filters/escape.rst b/doc/filters/escape.rst
index 9685585..ddb2bbb 100644
--- a/doc/filters/escape.rst
+++ b/doc/filters/escape.rst
@@ -57,4 +57,31 @@ The ``escape`` filter supports the following escaping strategies:
     Internally, ``escape`` uses the PHP native `htmlspecialchars`_ function
     for the HTML escaping strategy.
 
+.. caution::
+
+    When using automatic escaping, Twig tries to not double-escape a variable
+    when the automatic escaping strategy is the same as the one applied by the
+    escape filter; but that does not work when using a variable as the
+    escaping strategy:
+
+    .. code-block:: jinja
+
+        {% set strategy = 'html' %}
+
+        {% autoescape 'html' %}
+            {{ var|escape('html') }}   {# won't be double-escaped #}
+            {{ var|escape(strategy) }} {# will be double-escaped #}
+        {% endautoescape %}
+
+    When using a variable as the escaping strategy, you should disable
+    automatic escaping::
+
+    .. code-block:: jinja
+
+        {% set strategy = 'html' %}
+
+        {% autoescape 'html' %}
+            {{ var|escape(strategy)|raw }} {# won't be double-escaped #}
+        {% endautoescape %}
+
 .. _`htmlspecialchars`: http://php.net/htmlspecialchars
-- 
1.7.2.5