Improvement of auto-escaping (#1030)

* Evolution of auto-escaping: no double-escaping when using the 'escape' modifier; add the 'force' mode to the 'escape' modifier; add the 'raw' modifier.
* Add 'raw' modifier's documentation
---------

Co-authored-by: Simon Wisselink <s.wisselink@iwink.nl>

3 files changed, 39 insertions, 2 deletions

diff --git a/docs/api/configuring.md b/docs/api/configuring.md
index ee2ebf7e..540f6906 100644
--- a/docs/api/configuring.md
+++ b/docs/api/configuring.md
@@ -143,6 +143,35 @@ Enable auto-escaping for HTML as follows:
 $smarty->setEscapeHtml(true);
 ```
 
+When auto-escaping is enabled, the `|escape` modifier's default mode (`html`) has no effect,
+to avoid double-escaping. It is possible to force it with the `force` mode.
+Other modes (`htmlall`, `url`, `urlpathinfo`, `quotes`, `javascript`) may be used
+with the result you might expect, without double-escaping.
+
+Even when auto-escaping is enabled, you might want to display the content of a variable without
+escaping it. To do so, use the `|raw` modifier.
+
+Examples (with auto-escaping enabled):
+```smarty
+{* these three statements are identical *}
+{$myVar}
+{$myVar|escape}
+{$myVar|escape:'html'}
+
+{* no double-escaping on these statements *}
+{$var|escape:'htmlall'}
+{$myVar|escape:'url'}
+{$myVar|escape:'urlpathinfo'}
+{$myVar|escape:'quotes'}
+{$myVar|escape:'javascript'}
+
+{* no escaping at all *}
+{$myVar|raw}
+
+{* force double-escaping *}
+{$myVar|escape:'force'}
+```
+
 ## Disabling compile check
 By default, Smarty tests to see if the
 current template has changed since the last time
diff --git a/docs/designers/language-modifiers/language-modifier-escape.md b/docs/designers/language-modifiers/language-modifier-escape.md
index 6fd5dd2b..18c98f1c 100644
--- a/docs/designers/language-modifiers/language-modifier-escape.md
+++ b/docs/designers/language-modifiers/language-modifier-escape.md
@@ -73,6 +73,6 @@ This snippet is useful for emails, but see also
 <a href="mailto:{$EmailAddress|escape:'hex'}">{$EmailAddress|escape:'mail'}</a>
 ```
 
-See also [escaping smarty parsing](../language-basic-syntax/language-escaping.md),
+See also [auto-escaping](../../api/configuring.md#enabling-auto-escaping), [escaping smarty parsing](../language-basic-syntax/language-escaping.md),
 [`{mailto}`](../language-custom-functions/language-function-mailto.md) and the [obfuscating email
-addresses](../../appendixes/tips.md#obfuscating-e-mail-addresses) page.
+addresses](../../appendixes/tips.md#obfuscating-e-mail-addresses) pages.
diff --git a/docs/designers/language-modifiers/language-modifier-raw.md b/docs/designers/language-modifiers/language-modifier-raw.md
new file mode 100644
index 00000000..e9cce97d
--- /dev/null
+++ b/docs/designers/language-modifiers/language-modifier-raw.md
@@ -0,0 +1,8 @@
+# raw
+
+Prevents variable escaping when [auto-escaping](../../api/configuring.md#enabling-auto-escaping) is activated.
+
+## Basic usage
+```smarty
+{$myVar|raw}
+```