From 257b14b634773f52e0e0b370b1a54982e462fc7d Mon Sep 17 00:00:00 2001
From: Russ Cox <rsc@golang.org>
Date: Sat, 4 Sep 2021 19:03:32 -0400
Subject: [PATCH] clarify that character references are not interpreted in HTML
 blocks and raw HTML

The wording in section 2.5 implied otherwise,
although an example in 6.6 did clarify.
Adjust the first to remove the false implication
and adjust the second from saying "preserved",
which might mean they have to be parsed first,
to "copied uninterpreted".
---
 spec.txt | 62 ++++++++++++++++++++++++++++++++------------------------
 1 file changed, 36 insertions(+), 26 deletions(-)

diff --git a/spec.txt b/spec.txt
index 3f6bf0f9..89316892 100644
--- a/spec.txt
+++ b/spec.txt
@@ -722,57 +722,64 @@ recognized as entity references either:
 ````````````````````````````````
 
 
-Entity and numeric character references are recognized in any
-context besides code spans or code blocks, including
-URLs, [link titles], and [fenced code block][] [info strings]:
+Entity and numeric character references are treated as literal
+text in code spans and code blocks:
 
 ```````````````````````````````` example
-<a href="&ouml;&ouml;.html">
+`f&ouml;&ouml;`
 .
-<a href="&ouml;&ouml;.html">
+<p><code>f&amp;ouml;&amp;ouml;</code></p>
 ````````````````````````````````
 
 
 ```````````````````````````````` example
-[foo](/f&ouml;&ouml; "f&ouml;&ouml;")
+    f&ouml;f&ouml;
 .
-<p><a href="/f%C3%B6%C3%B6" title="föö">foo</a></p>
+<pre><code>f&amp;ouml;f&amp;ouml;
+</code></pre>
 ````````````````````````````````
 
 
+
+Entity and numeric character references are left uninterpreted
+in HTML blocks and raw HTML:
+
 ```````````````````````````````` example
-[foo]
+<div id="&copy&asdf;">
 
-[foo]: /f&ouml;&ouml; "f&ouml;&ouml;"
+Link <a href="&copy&ouml;&ouml;.html">
 .
-<p><a href="/f%C3%B6%C3%B6" title="föö">foo</a></p>
+<div id="&copy&asdf;">
+<p>Link <a href="&copy&ouml;&ouml;.html"></p>
 ````````````````````````````````
 
 
+Entity and numeric character references are recognized in any
+any other context, including URLs, [link titles], and
+[fenced code block][] [info strings]:
+
 ```````````````````````````````` example
-``` f&ouml;&ouml;
-foo
-```
+[foo](/f&ouml;&ouml; "f&ouml;&ouml;")
 .
-<pre><code class="language-föö">foo
-</code></pre>
+<p><a href="/f%C3%B6%C3%B6" title="föö">foo</a></p>
 ````````````````````````````````
 
 
-Entity and numeric character references are treated as literal
-text in code spans and code blocks:
-
 ```````````````````````````````` example
-`f&ouml;&ouml;`
+[foo]
+
+[foo]: /f&ouml;&ouml; "f&ouml;&ouml;"
 .
-<p><code>f&amp;ouml;&amp;ouml;</code></p>
+<p><a href="/f%C3%B6%C3%B6" title="föö">foo</a></p>
 ````````````````````````````````
 
 
 ```````````````````````````````` example
-    f&ouml;f&ouml;
+``` f&ouml;&ouml;
+foo
+```
 .
-<pre><code>f&amp;ouml;f&amp;ouml;
+<pre><code class="language-föö">foo
 </code></pre>
 ````````````````````````````````
 
@@ -9173,17 +9180,17 @@ foo <![CDATA[>&<]]>
 ````````````````````````````````
 
 
-Entity and numeric character references are preserved in HTML
+Entity and numeric character references are copied uninterpreted in HTML
 attributes:
 
 ```````````````````````````````` example
-foo <a href="&ouml;">
+foo <a href="&ouml;&copy">
 .
-<p>foo <a href="&ouml;"></p>
+<p>foo <a href="&ouml;&copy"></p>
 ````````````````````````````````
 
 
-Backslash escapes do not work in HTML attributes:
+Backslash escapes are also copied uninterpreted:
 
 ```````````````````````````````` example
 foo <a href="\*">
@@ -9192,6 +9199,9 @@ foo <a href="\*">
 ````````````````````````````````
 
 
+Not interpreting backslash escapes can mean not recognizing
+a tag that HTML5 would recognize:
+
 ```````````````````````````````` example
 <a href="\"">
 .