update docs for automatic escaping

diff --git a/doc/02-Twig-for-Template-Designers.markdown b/doc/02-Twig-for-Template-Designers.markdown
index fa300a9..f326697 100644 (file)
--- a/doc/02-Twig-for-Template-Designers.markdown
+++ b/doc/02-Twig-for-Template-Designers.markdown
@@ -1233,7 +1233,8 @@ might contain such characters in HTML.
 ### `raw`
 
 The `raw` filter marks the value as safe which means that in an environment
-with automatic escaping enabled this variable will not be escaped.
+with automatic escaping enabled this variable will not be escaped if `raw` is
+the last filter applied to it.
 
     [twig]
     {% autoescape on }

diff --git a/doc/03-Twig-for-Developers.markdown b/doc/03-Twig-for-Developers.markdown
index 9dfb23b..7867abc 100644 (file)
--- a/doc/03-Twig-for-Developers.markdown
+++ b/doc/03-Twig-for-Developers.markdown
@@ -327,7 +327,7 @@ You can also change the escaping mode locally by using the `autoescape` tag:
 >The `autoescape` tag has no effect on included files.
 
 The escaping rules are implemented as follows (it describes the behavior of
-Twig 0.9.5 and above):
+Twig 0.9.9 and above):
 
  * Literals (integers, booleans, arrays, ...) used in the template directly as
    variables or filter arguments are never automatically escaped:
@@ -338,28 +338,45 @@ Twig 0.9.5 and above):
         {% set text = "Twig<br />" %}
         {{ text }} {# will be escaped #}
 
- * Escaping is applied before any other filter is applied (the reasoning
-   behind this is that filter transformations should be safe, as the filtered
-   value and all its arguments are escaped):
+ * Expressions which the result is always a literal or a variable marked safe
+   are never automatically escaped:
 
         [twig]
-        {{ var|nl2br }} {# is equivalent to {{ var|escape|nl2br }} #}
+        {{ foo ? "Twig<br />" : "<br />Twig" }} {# won't be escaped #}
 
- * The `raw` filter can be used anywhere in the filter chain:
+        {% set text = "Twig<br />" %}
+        {{ foo ? text : "<br />Twig" }} {# will be escaped #}
+
+        {% set text = "Twig<br />" %}
+        {{ foo ? text|raw : "<br />Twig" }} {# won't be escaped #}
+
+        {% set text = "Twig<br />" %}
+        {{ foo ? text|escape : "<br />Twig" }} {# won't be escaped #}
+
+ * Escaping is applied before printing, after any other filter is applied:
 
         [twig]
-        {{ var|upper|nl2br|raw }} {# is equivalent to {{ var|raw|upper|nl2br }} #}
+        {{ var|upper }} {# is equivalent to {{ var|upper|escape }} #}
+
+ * The `raw` filter should only be used at the end of the filter chain:
 
- * Automatic escaping is applied to filter arguments, except for literals:
+        [twig]
+        {{ var|raw|upper }} {# will be escaped #}
 
         [twig]
-        {{ var|foo("bar") }} {# "bar" won't be escaped #}
-        {{ var|foo(bar) }} {# bar will be escaped #}
-        {{ var|foo(bar|raw) }} {# bar won't be escaped #}
+        {{ var|upper|raw }} {# won't be escaped #}
 
- * Automatic escaping is not applied if one of the filters in the chain has the
-   `is_escaper` option set to `true` (this is the case for the built-in
-   `escaper`, `raw`, and `urlencode` filters for instance).
+ * Automatic escaping is not applied if the last filter in the chain is marked
+   safe for the current context (e.g. `html` or `js`). `escaper` and
+   `escaper('html')` are marked safe for html, `escaper('js')` is marked safe
+   for javascript, `raw` is marked safe for everything.
+
+        [twig]
+        {% autoescape js on %}
+        {{ 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 %}
 
 ### Sandbox Extension
 

diff --git a/doc/04-Extending-Twig.markdown b/doc/04-Extending-Twig.markdown
index eee93af..f6d4833 100644 (file)
--- a/doc/04-Extending-Twig.markdown
+++ b/doc/04-Extending-Twig.markdown
@@ -335,17 +335,13 @@ filter call:
 
 ### Automatic Escaping
 
-If automatic escaping is enabled, the main value passed to the filters is
-automatically escaped. If your filter acts as an escaper, you will want the
-raw variable value. In such a case, set the `is_escaper` option to `true`:
+If automatic escaping is enabled, the output of the filter may be escaped before
+printing. If your filter acts as an escaper (or explicitly outputs html or
+javascript code), you will want the raw output to be printed. In such a case,
+set the `is_safe` option:
 
     [php]
-    $filter = new Twig_Filter_Function('urlencode', array('is_escaper' => true));
-
->**NOTE**
->The parameters passed as extra arguments to the filters are not affected by
->the `is_escaper` option and they are always escaped according to the
->automatic escaping rules.
+    $filter = new Twig_Filter_Function('nl2br', array('is_safe' => array('html')));
 
 Overriding default Filters
 --------------------------