From ecbb8c717d7bd3d116e35ade4133c34e39379f9b Mon Sep 17 00:00:00 2001
From: Russ Cox <rsc@golang.org>
Date: Sat, 4 Sep 2021 18:47:46 -0400
Subject: [PATCH] clarify link reference definition interruptions and
 continuation text

Other blocks can interrupt a link reference definition,
and link reference definitions can have continuation text
that is not fully prefixed, following the rules of paragraph
continuation text.

Document both these facts and give examples.

Fixes #688.
---
 spec.txt | 140 ++++++++++++++++++++++++++++++++++++++++++++++++++-----
 1 file changed, 129 insertions(+), 11 deletions(-)

diff --git a/spec.txt b/spec.txt
index 3f6bf0f9..0a2cd3de 100644
--- a/spec.txt
+++ b/spec.txt
@@ -3467,16 +3467,6 @@ bar
 <p><a href="/url">foo</a></p>
 ````````````````````````````````
 
-```````````````````````````````` example
-[foo]: /url
-===
-[foo]
-.
-<p>===
-<a href="/url">foo</a></p>
-````````````````````````````````
-
-
 Several [link reference definitions]
 can occur one after another, without intervening blank lines.
 
@@ -3485,7 +3475,6 @@ can occur one after another, without intervening blank lines.
 [bar]: /bar-url
   "bar"
 [baz]: /baz-url
-
 [foo],
 [bar],
 [baz]
@@ -3495,6 +3484,120 @@ can occur one after another, without intervening blank lines.
 <a href="/baz-url">baz</a></p>
 ````````````````````````````````
 
+The text of a link reference definition can be interrupted by any block element
+that can interrupt a paragraph. These are not definitions at all,
+because what would be a multi-line title is interrupted
+by a heading, quoted text, and a fenced code block:
+
+```````````````````````````````` example
+[foo]: /url '
+# h1
+'
+
+[foo]: /url '
+> quote
+'
+
+[foo]: /url '
+```
+text
+```
+'
+
+[foo]
+.
+<p>[foo]: /url '</p>
+<h1>h1</h1>
+<p>'</p>
+<p>[foo]: /url '</p>
+<blockquote>
+<p>quote
+'</p>
+</blockquote>
+<p>[foo]: /url '</p>
+<pre><code>text
+</code></pre>
+<p>'</p>
+<p>[foo]</p>
+````````````````````````````````
+
+This isn't a two-line definition because the list interrupts the title,
+leaving a one-line definition:
+
+```````````````````````````````` example
+[foo]: /url
+'
+- list item
+'
+
+[foo]
+.
+<p>'</p>
+<ul>
+<li>list item
+'</li>
+</ul>
+<p><a href="/url">foo</a></p>
+````````````````````````````````
+
+It is also possible for the URL itself to be interrupted:
+
+```````````````````````````````` example
+[foo]:
+#
+[foo]
+.
+<p>[foo]:</p>
+<h1></h1>
+<p>[foo]</p>
+````````````````````````````````
+
+
+Because an indented code block cannot interrupt a paragraph,
+it also cannot interrupt a link reference definition:
+
+```````````````````````````````` example
+[foo]: /url '
+        not a code block
+'
+
+[foo]
+.
+<p><a href="/url" title="
+not a code block
+">foo</a></p>
+````````````````````````````````
+
+Both of these are valid link reference definitions,
+leaving no text for `===` to create a setext heading:
+
+```````````````````````````````` example
+[foo]: /url
+===
+[foo]
+.
+<p>===
+<a href="/url">foo</a></p>
+````````````````````````````````
+
+```````````````````````````````` example
+[foo]: /url 'bar'
+===
+[foo]
+.
+<p>===
+<a href="/url" title="bar">foo</a></p>
+````````````````````````````````
+
+```````````````````````````````` example
+[foo]: /url
+'bar'
+===
+[foo]
+.
+<p>===
+<a href="/url" title="bar">foo</a></p>
+````````````````````````````````
 
 [Link reference definitions] can occur
 inside block containers, like lists and block quotations.  They
@@ -3511,6 +3614,21 @@ are defined:
 </blockquote>
 ````````````````````````````````
 
+The text in a link reference definition can be continued
+using the same rules as for [paragraph continuation text]:
+
+```````````````````````````````` example
+> [foo]: /url '
+hello
+'
+> [foo]
+.
+<blockquote>
+<p><a href="/url" title="
+hello
+">foo</a></p>
+</blockquote>
+````````````````````````````````
 
 ## Paragraphs