From 25bd9faf327c7c0a45b9ca6e0ea678d898af8838 Mon Sep 17 00:00:00 2001
From: Natalia <124304+nessita@users.noreply.github.com>
Date: Wed, 24 May 2023 13:59:00 -0300
Subject: [PATCH] [4.2.x] Fixed #34574 -- Noted unexpected outcomes in
 autoescape/escape docs.

Backport of 1a59a324cec5caf12ea0c4947564828aa7bda02a from main.
---
 docs/ref/templates/builtins.txt | 46 ++++++++++++++++++++++++++-------
 docs/spelling_wordlist          |  1 +
 2 files changed, 38 insertions(+), 9 deletions(-)

diff --git a/docs/ref/templates/builtins.txt b/docs/ref/templates/builtins.txt
index 853a62e719..2677e35815 100644
--- a/docs/ref/templates/builtins.txt
+++ b/docs/ref/templates/builtins.txt
@@ -21,15 +21,6 @@ Controls the current auto-escaping behavior. This tag takes either ``on`` or
 ``off`` as an argument and that determines whether auto-escaping is in effect
 inside the block. The block is closed with an ``endautoescape`` ending tag.
 
-When auto-escaping is in effect, all variable content has HTML escaping applied
-to it before placing the result into the output (but after any filters have
-been applied). This is equivalent to manually applying the :tfilter:`escape`
-filter to each variable.
-
-The only exceptions are variables that are already marked as "safe" from
-escaping, either by the code that populated the variable, or because it has had
-the :tfilter:`safe` or :tfilter:`escape` filters applied.
-
 Sample usage:
 
 .. code-block:: html+django
@@ -38,6 +29,33 @@ Sample usage:
         {{ body }}
     {% endautoescape %}
 
+When auto-escaping is in effect, all content derived from variables has HTML
+escaping applied before placing the result into the output (but after any
+filters are applied). This is equivalent to manually applying the
+:tfilter:`escape` filter to each variable.
+
+The only exceptions are variables already marked as "safe" from escaping.
+Variables could be marked as "safe" by the code which populated the variable,
+by applying the :tfilter:`safe` or :tfilter:`escape` filters, or because it's
+the result of a previous filter that marked the string as "safe".
+
+Within the scope of disabled auto-escaping, chaining filters, including
+:tfilter:`escape`, may cause unexpected (but documented) results such as the
+following:
+
+.. code-block:: html+django
+
+    {% autoescape off %}
+        {{ my_list|join:", "|escape }}
+    {% endautoescape %}
+
+The above code will output the joined elements of ``my_list`` unescaped. This
+is because the filter chaining sequence executes first :tfilter:`join` on
+``my_list`` (without applying escaping to each item since ``autoescape`` is
+``off``), marking the result as safe. Subsequently, this safe result will be
+fed to :tfilter:`escape` filter, which does not apply a second round of
+escaping.
+
 .. templatetag:: block
 
 ``block``
@@ -1832,6 +1850,16 @@ For example, you can apply ``escape`` to fields when :ttag:`autoescape` is off:
         {{ title|escape }}
     {% endautoescape %}
 
+.. admonition:: Chaining ``escape`` with other filters
+
+    As mentioned in the :ttag:`autoescape` section, when filters including
+    ``escape`` are chained together, it can result in unexpected outcomes if
+    preceding filters mark a potentially unsafe string as safe due to the lack
+    of escaping caused by :ttag:`autoescape` being ``off``.
+
+    In such cases, chaining ``escape`` would not reescape strings that have
+    already been marked as safe.
+
 .. templatefilter:: escapejs
 
 ``escapejs``
diff --git a/docs/spelling_wordlist b/docs/spelling_wordlist
index 4ed4f49cf2..26d777ab68 100644
--- a/docs/spelling_wordlist
+++ b/docs/spelling_wordlist
@@ -415,6 +415,7 @@ redisplayed
 redisplaying
 redisplays
 reenable
+reescape
 referer
 referers
 reflow