From c3b0c6312f47fbe1dd71073429440f77a7bb89ad 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 | 147 +++++++++++++++++++++++++++++++++++++++++++++++++++----
 1 file changed, 137 insertions(+), 10 deletions(-)

diff --git a/spec.txt b/spec.txt
index 3f6bf0f9..d6ef8e10 100644
--- a/spec.txt
+++ b/spec.txt
@@ -3467,15 +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 +3476,6 @@ can occur one after another, without intervening blank lines.
 [bar]: /bar-url
   "bar"
 [baz]: /baz-url
-
 [foo],
 [bar],
 [baz]
@@ -3496,6 +3486,126 @@ can occur one after another, without intervening blank lines.
 ````````````````````````````````
 
 
+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]:
+#
+[bar]: #
+[foo] [bar]
+.
+<p>[foo]:</p>
+<h1></h1>
+<p>[foo] <a href="#">bar</a></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>
+````````````````````````````````
+
+
+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
 affect the entire document, not just the container in which they
@@ -3512,6 +3622,23 @@ are defined:
 ````````````````````````````````
 
 
+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
 
 A sequence of non-blank lines that cannot be interpreted as other