link reference definition versus other elements

[rsc]

The 0.30 spec does not mention that link reference definitions can be interrupted by other elements.
It does say:

However, it can directly follow other block elements, such as headings and thematic breaks, and it need not be followed by a blank line.

and then it gives the example (215):

[foo]: /url
bar
===
[foo]

This is, as the text said, "not followed by a blank line", because the link reference definition has unambiguously ended before the bar. However, there are other cases where a link reference definition could arguably be in progress but the block structure interrupts it.

I suggest adding replacing examples 215-216 with something like:

---

The text of a link reference definition can be interrupted by any block element that can interrupt a paragraph:

Example A

[foo]: /url '
bar
'

[foo]

Example B

[foo]: /url '
# h1
'

[foo]

Example C

[foo]: /url '
> quote
'

[foo]

Example D

[foo]: /url
'
- list item
'

[foo]

Example E

[foo]: /url '
        not a code block
'

[foo]

Example F (== example 216)

[foo]: /url
===
[foo]

Example G

[foo]: /url 'bar'
===
[foo]

Example H

[foo]: /url
'bar'
===
[foo]

Example I (== example 215)

[foo]: /url
bar
===
[foo]

Example A is a link reference definition with an ordinary multiline title.
Examples B, C, and D do not have valid link titles: the title text is interrupted by block-level structure. Whether the overall link reference definition remains valid depends on whether the title started on a separate line.
Example E is a valid link title: indented code blocks cannot interrupt paragraphs, so they also cannot interrupt link titles.
Examples F, G, and H are valid link reference definitions: they are completed, leaving no paragraph text for the === to use to create a setext heading.
Example I also completes a valid link reference definition, leaving the unquoted bar for use in the setext heading.

---

Along the same lines, after example 218, I suggest adding something like:

---

The text of a link reference definition can be continued using the same rules as for paragraph continuation lines:

Example J

> [foo]: /url '
hello
'
> [foo]

---

This is all a bit roundabout and it would seem easier to say something like "Link reference definitions are removed from the start of each paragraph's initial text as the paragraph is accumulated. If no text remains, then there is no paragraph left behind." But that's probably too operational for the spirit of the spec.

[rsc]

Another pair of examples that could go after example B, interrupting the url instead of the link title:

Example B2 (valid link ref def):

[foo]: # 
[foo]

Example B3 (an h1 with no link reference definitions):

[foo]:
# 
[foo]

[jgm]

I think this is a good suggestion.
Would you like to do a PR?

[rsc]

Sure, will send one.

[rsc]

PR #689.

[vassudanagunta]

This is all a bit roundabout and it would seem easier to say something like "Link reference definitions are removed from the start of each paragraph's initial text as the paragraph is accumulated. If no text remains, then there is no paragraph left behind." But that's probably too operational for the spirit of the spec.

I can't find the relevant issue or forum post, but @jgm has confirmed previously that this behavior is an artifact of the parser implementation: for efficiency or simplicity it first parses out paragraphs and later parses Link Ref Defs from the top of the paragraphs. In other words, it's an accident and not how LRDs are supposed to behave. Lazy continuation is only for paragraphs.

I'm guessing the interruption issues have the same cause, i.e. LRDs are inheriting paragraph rules around interruption as an artifact of the parser implementation... though I don't have the time to examine that right now.

@jgm Have you changed your mind?

I have an implementation (not yet released) that does not take this shortcut and conforms to the spec as-is, so it's certainly doable.

[vassudanagunta]

Relevant OPEN issues that comment on this: #605, #574 and #622. Possibly also relevant: #583

[rsc]

Happy to remove or adjust the continuation text examples according to whatever the consensus is.