Added disambiguation on using raw in expressions

diff --git a/doc/filters/raw.rst b/doc/filters/raw.rst
index a9900c7..065e577 100644 (file)
--- a/doc/filters/raw.rst
+++ b/doc/filters/raw.rst
@@ -10,3 +10,27 @@ if ``raw`` is the last filter applied to it:
     {% autoescape %}
         {{ var|raw }} {# var won't be escaped #}
     {% endautoescape %}
+
+.. note::
+
+    Be careful when using the ``raw`` filter inside expressions. This
+    snippet illustrates a case that can be confusing :
+
+    .. code-block:: jinja
+
+        {% autoescape %}
+            {% set hello = '<strong>Hello</strong>' %}
+            {% set hola = '<strong>Hola</strong>' %}
+
+            {{ false ? '<strong>Hola</strong>' : hello|raw }}
+            does not render the same as
+            {{ false ? hola : hello|raw }}
+            but renders the same as
+            {{ (false ? hola : hello)|raw }}
+        {% endautoescape %}
+
+    The first ternary won't be escaped : ``hello`` is marked as being safe and
+    Twig does not escape static values (see :doc:`escape<../tags/autoescape>`).
+    In the second ternary, even if ``hello`` is marked as safe, ``hola``
+    remains unsafe and so will be the whole expression. On the other hand, the
+    third ternary will be marked as safe and the result won't be escaped.
\ No newline at end of file

diff --git a/doc/tags/autoescape.rst b/doc/tags/autoescape.rst
index c5ff0c2..09f8d47 100644 (file)
--- a/doc/tags/autoescape.rst
+++ b/doc/tags/autoescape.rst
@@ -67,5 +67,18 @@ Functions returning template data (like :doc:`macros<macro>` and
 
 .. note::
 
+    Twig does not escape static expressions :
+
+    .. code-block:: jinja
+
+        {% set hello = "<strong>Hello</strong>" %}
+        {{ hello }}
+        {{ "<strong>world</strong>" }}
+
+    Will be rendered "<strong>Hello</strong> **world**".
+
+
+.. note::
+
     The chapter :doc:`Twig for Developers<../api>` gives more information
-    about when and how automatic escaping is applied.
+    about when and how automatic escaping is applied.
\ No newline at end of file