Updated spec.txt.

1 files changed, 105 insertions, 24 deletions

diff --git a/test/spec.txt b/test/spec.txt
index f0a54ea..e4a9ee3 100644
--- a/test/spec.txt
+++ b/test/spec.txt
@@ -786,12 +786,12 @@ ATX headings can be empty:
 
 ## Setext headings
 
-A [setext heading](@setext-heading)
-consists of a line of text, containing at least one [non-whitespace character],
-with no more than 3 spaces indentation, followed by a [setext heading
-underline].  The line of text must be
-one that, were it not followed by the setext heading underline,
-would be interpreted as part of a paragraph:  it cannot be
+A [setext heading](@setext-heading) consists of one or more
+lines of text, each containing at least one [non-whitespace
+character], with no more than 3 spaces indentation, followed by
+a [setext heading underline].  The lines of text must be such
+that, were they not followed by the setext heading underline,
+they would be interpreted as a paragraph:  they cannot be
 interpretable as a [code fence], [ATX heading][ATX headings],
 [block quote][block quotes], [thematic break][thematic breaks],
 [list item][list items], or [HTML block][HTML blocks].
@@ -803,10 +803,11 @@ containing a single `-` can be interpreted as an
 empty [list items], it should be interpreted this way
 and not as a [setext heading underline].
 
-The heading is a level 1 heading if `=` characters are used in the
-[setext heading underline], and a level 2
-heading if `-` characters are used.  The contents of the heading are the
-result of parsing the first line as Markdown inline content.
+The heading is a level 1 heading if `=` characters are used in
+the [setext heading underline], and a level 2 heading if `-`
+characters are used.  The contents of the heading are the result
+of parsing the preceding lines of text as CommonMark inline
+content.
 
 In general, a setext heading need not be preceded or followed by a
 blank line.  However, it cannot interrupt a paragraph, so when a
@@ -826,6 +827,17 @@ Foo *bar*
 <h2>Foo <em>bar</em></h2>
 .
 
+The content of the header may span more than one line:
+
+.
+Foo *bar
+baz*
+====
+.
+<h1>Foo <em>bar
+baz</em></h1>
+.
+
 The underlining can be any length:
 
 .
@@ -959,6 +971,18 @@ line] in a list item or block quote:
 .
 
 .
+> foo
+bar
+===
+.
+<blockquote>
+<p>foo
+bar
+===</p>
+</blockquote>
+.
+
+.
 - Foo
 ---
 .
@@ -968,26 +992,21 @@ line] in a list item or block quote:
 <hr />
 .
 
-A setext heading cannot interrupt a paragraph:
+A blank line is needed between a paragraph and a following
+setext heading, since otherwise the paragraph becomes part
+of the heading's content:
 
 .
 Foo
 Bar
 ---
-
-Foo
-Bar
-===
 .
-<p>Foo
-Bar</p>
-<hr />
-<p>Foo
-Bar
-===</p>
+<h2>Foo
+Bar</h2>
 .
 
-But in general a blank line is not required before or after:
+But in general a blank line is not required before or after
+setext headings:
 
 .
 ---
@@ -1063,6 +1082,68 @@ use backslash escapes:
 <h2>&gt; foo</h2>
 .
 
+**Compatibility note:**  Most existing Markdown implementations
+do not allow the text of setext headings to span multiple lines.
+But there is no consensus about how to interpret
+
+``` markdown
+Foo
+bar
+---
+baz
+```
+
+One can find four different interpretations:
+
+1. paragraph "Foo", heading "bar", paragraph "baz"
+2. paragraph "Foo bar", thematic break, paragraph "baz"
+3. paragraph "Foo bar --- baz"
+4. heading "Foo bar", paragraph "baz"
+
+We find interpretation 4 most natural, and interpretation 4
+increases the expressive power of CommonMark, by allowing
+multiline headings.  Authors who want interpretation 1 can
+put a blank line after the first paragraph:
+
+``` markdown
+Foo
+
+bar
+---
+baz
+```
+
+Authors who want interpretation 2 can put blank lines around
+the thematic break,
+
+``` markdown
+Foo
+bar
+
+---
+
+baz
+```
+
+or use a thematic break that cannot count as a [setext heading
+line], such as
+
+``` markdown
+Foo
+bar
+* * *
+baz
+```
+
+Authors who want interpretation 3 can use backslash escapes:
+
+``` markdown
+Foo
+bar
+\---
+baz
+```
+
 ## Indented code blocks
 
 An [indented code block](@indented-code-block) is composed of one or more
@@ -8221,8 +8302,8 @@ markers like `>`, list markers, and indentation have been consumed).
 This is text that can be incorporated into the last open
 block (a paragraph, code block, heading, or raw HTML).
 
-Setext headings are formed when we detect that the second line of
-a paragraph is a setext heading line.
+Setext headings are formed when we see a line of a paragraph
+that is a setext heading line.
 
 Reference link definitions are detected when a paragraph is closed;
 the accumulated text lines are parsed to see if they begin with