From 975377933ca5a381d218ac7c676ae1f60e95f37e Mon Sep 17 00:00:00 2001
From: Dennis Snell <dmsnell@xkq.io>
Date: Thu, 4 Dec 2025 12:42:11 -0700
Subject: [PATCH] Encourage always-escaping ampersand character. (#11988)

In the example highlighting ambiguities from missing semicolons on named
character references, a "correct" encoding is provided, but that example
makes no mention of the fact that the fragment was ambiguous precisely
because the ampersand wasn't escaped.

This patch adds a clarifying note explaining how this situation is
avoided by always escaping the ampersand.

Co-authored-by: Jon Surrell <jon.surrell@automattic.com>
GitHub-PR: 11988
GitHub-PR-URL: https://github.com/whatwg/html/pull/11988
---
 source | 5 +++++
 1 file changed, 5 insertions(+)

diff --git a/source b/source
index d691684c2d3..6fbcd6ac802 100644
--- a/source
+++ b/source
@@ -1159,6 +1159,9 @@ a.setAttribute('href', 'https://example.com/'); // change the content attribute
      <pre><code class="html">&lt;a href="?bill&amp;ted">Bill and Ted&lt;/a> &lt;!-- &amp;ted is ok, since it's not a named character reference --></code></pre>
      <pre><code class="html">&lt;a href="?art&amp;amp;copy">Art and Copy&lt;/a> &lt;!-- the &amp; has to be escaped, since &amp;copy <em>is</em> a named character reference --></code></pre>
 
+     <p>It's best to always escape the "&amp;" character as "&amp;amp;", which avoids ambiguities like
+     these when other syntax errors are present.</p>
+
     </div>
    </dd>
 
@@ -156399,6 +156402,7 @@ INSERT INTERFACES HERE
   Debanjana Sarkar, <!-- debanjana-a11y on GitHub -->
   Debi Orton,
   Delan Azabani, <!-- delan on GitHub -->
+  Dennis Snell, <!-- dmsnell on GitHub -->
   Derek Featherstone,
   Derek Guenther,
   Devarshi Pant,
@@ -156660,6 +156664,7 @@ INSERT INTERFACES HERE
   Jon Gibbins,
   Jon Jensen,
   Jon Perlow,
+  Jon Surrell, <!-- sirreal on GitHub -->
   Jonas Sicking,
   Jonathan Cook,
   Jonathan Kew,