summaryrefslogtreecommitdiff
path: root/test/spec.txt
diff options
context:
space:
mode:
authorJohn MacFarlane <jgm@berkeley.edu>2016-01-07 22:31:13 -0800
committerJohn MacFarlane <jgm@berkeley.edu>2016-01-07 22:31:13 -0800
commit7020eb8dab065c3806fc6174443c19e262344999 (patch)
treefb43adf69607914e8b781b15c3644a0ee5e21ea1 /test/spec.txt
parent2a3e1922efedbcff9899c4f7c9037c61991c90d6 (diff)
Updated spec.txt.
Diffstat (limited to 'test/spec.txt')
-rw-r--r--test/spec.txt129
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