Diff: spec.txt - spec.txt

Couldn't find wdiff. Falling back to builtin diff colouring... Diff: spec.txt - spec.txt

	spec.txt	spec.txt
	---	---
	title: CommonMark Spec	title: CommonMark Spec
	author: John MacFarlane	author: John MacFarlane

	version: 0.26	version: 0.27
	date: '2016-07-15'	date: '2016-11-18'
	license: '[CC-BY-SA 4.0](http://creativecommons.org/licenses/by-sa/4.0/)'	license: '[CC-BY-SA 4.0](http://creativecommons.org/licenses/by-sa/4.0/)'
	...	...

	# Introduction	# Introduction

	## What is Markdown?	## What is Markdown?

	Markdown is a plain text format for writing structured documents,	Markdown is a plain text format for writing structured documents,
	based on conventions used for indicating formatting in email and	based on conventions used for indicating formatting in email and
	usenet posts. It was developed in 2004 by John Gruber, who wrote	usenet posts. It was developed in 2004 by John Gruber, who wrote

	skipping to change at line 1872 ¶	skipping to change at line 1872 ¶
	## HTML blocks	## HTML blocks

	An [HTML block](@) is a group of lines that is treated	An [HTML block](@) is a group of lines that is treated
	as raw HTML (and will not be escaped in HTML output).	as raw HTML (and will not be escaped in HTML output).

	There are seven kinds of [HTML block], which can be defined	There are seven kinds of [HTML block], which can be defined
	by their start and end conditions. The block begins with a line that	by their start and end conditions. The block begins with a line that
	meets a [start condition](@) (after up to three spaces	meets a [start condition](@) (after up to three spaces
	optional indentation). It ends with the first subsequent line that	optional indentation). It ends with the first subsequent line that
	meets a matching [end condition](@), or the last line of	meets a matching [end condition](@), or the last line of

	the document or other [container block](@), if no line is encountered that meets the	the document or other [container block]), if no line is encountered that meets t he
	[end condition]. If the first line meets both the [start condition]	[end condition]. If the first line meets both the [start condition]
	and the [end condition], the block will contain just that line.	and the [end condition], the block will contain just that line.

	1. Start condition: line begins with the string `<script`,	1. Start condition: line begins with the string `<script`,
	`<pre`, or `<style` (case-insensitive), followed by whitespace,	`<pre`, or `<style` (case-insensitive), followed by whitespace,
	the string `>`, or the end of the line.\	the string `>`, or the end of the line.\
	End condition: line contains an end tag	End condition: line contains an end tag
	`</script>`, `</pre>`, or `</style>` (case-insensitive; it	`</script>`, `</pre>`, or `</style>` (case-insensitive; it
	need not match the start tag).	need not match the start tag).


	skipping to change at line 1902 ¶	skipping to change at line 1902 ¶

	5. Start condition: line begins with the string	5. Start condition: line begins with the string
	`<![CDATA[`.\	`<![CDATA[`.\
	End condition: line contains the string `]]>`.	End condition: line contains the string `]]>`.

	6. Start condition: line begins the string `<` or `</`	6. Start condition: line begins the string `<` or `</`
	followed by one of the strings (case-insensitive) `address`,	followed by one of the strings (case-insensitive) `address`,
	`article`, `aside`, `base`, `basefont`, `blockquote`, `body`,	`article`, `aside`, `base`, `basefont`, `blockquote`, `body`,
	`caption`, `center`, `col`, `colgroup`, `dd`, `details`, `dialog`,	`caption`, `center`, `col`, `colgroup`, `dd`, `details`, `dialog`,
	`dir`, `div`, `dl`, `dt`, `fieldset`, `figcaption`, `figure`,	`dir`, `div`, `dl`, `dt`, `fieldset`, `figcaption`, `figure`,

	`footer`, `form`, `frame`, `frameset`, `h1`, `head`, `header`, `hr`,	`footer`, `form`, `frame`, `frameset`,
		`h1`, `h2`, `h3`, `h4`, `h5`, `h6`, `head`, `header`, `hr`,
	`html`, `iframe`, `legend`, `li`, `link`, `main`, `menu`, `menuitem`,	`html`, `iframe`, `legend`, `li`, `link`, `main`, `menu`, `menuitem`,
	`meta`, `nav`, `noframes`, `ol`, `optgroup`, `option`, `p`, `param`,	`meta`, `nav`, `noframes`, `ol`, `optgroup`, `option`, `p`, `param`,
	`section`, `source`, `summary`, `table`, `tbody`, `td`,	`section`, `source`, `summary`, `table`, `tbody`, `td`,
	`tfoot`, `th`, `thead`, `title`, `tr`, `track`, `ul`, followed	`tfoot`, `th`, `thead`, `title`, `tr`, `track`, `ul`, followed
	by [whitespace], the end of the line, the string `>`, or	by [whitespace], the end of the line, the string `>`, or
	the string `/>`.\	the string `/>`.\
	End condition: line is followed by a [blank line].	End condition: line is followed by a [blank line].

	7. Start condition: line begins with a complete [open tag]	7. Start condition: line begins with a complete [open tag]
	or [closing tag] (with any [tag name] other than `script`,	or [closing tag] (with any [tag name] other than `script`,

	skipping to change at line 3415 ¶	skipping to change at line 3416 ¶
	blocks Bs starting with a [non-whitespace character] and not separated	blocks Bs starting with a [non-whitespace character] and not separated
	from each other by more than one blank line, and M is a list	from each other by more than one blank line, and M is a list
	marker of width W followed by 1 ≤ N ≤ 4 spaces, then the result	marker of width W followed by 1 ≤ N ≤ 4 spaces, then the result
	of prepending M and the following spaces to the first line of	of prepending M and the following spaces to the first line of
	Ls, and indenting subsequent lines of Ls by W + N spaces, is a	Ls, and indenting subsequent lines of Ls by W + N spaces, is a
	list item with Bs as its contents. The type of the list item	list item with Bs as its contents. The type of the list item
	(bullet or ordered) is determined by the type of its list marker.	(bullet or ordered) is determined by the type of its list marker.
	If the list item is ordered, then it is also assigned a start	If the list item is ordered, then it is also assigned a start
	number, based on the ordered list marker.	number, based on the ordered list marker.


	Exceptions: When the list item interrupts a paragraph---that	Exceptions: When the first list item in a [list] interrupts
	is, when it starts on a line that would otherwise count as	a paragraph---that is, when it starts on a line that would
	[paragraph continuation text]---then (a) the lines Ls must	otherwise count as [paragraph continuation text]---then (a)
	not begin with a blank line, and (b) if the list item is	the lines Ls must not begin with a blank line, and (b) if
	ordered, the start number must be 1.	the list item is ordered, the start number must be 1.

	For example, let Ls be the lines	For example, let Ls be the lines

	```````````````````````````````` example	```````````````````````````````` example
	A paragraph	A paragraph
	with two lines.	with two lines.

	indented code	indented code

	> A block quote.	> A block quote.

	skipping to change at line 4458 ¶	skipping to change at line 4459 ¶
	we don't have a "first paragraph" to measure from? Rule #2 simply stipulates	we don't have a "first paragraph" to measure from? Rule #2 simply stipulates
	that in such cases, we require one space indentation from the list marker	that in such cases, we require one space indentation from the list marker
	(and then the normal four spaces for the indented code). This will match the	(and then the normal four spaces for the indented code). This will match the
	four-space rule in cases where the list marker plus its initial indentation	four-space rule in cases where the list marker plus its initial indentation
	takes four spaces (a common case), but diverge in other cases.	takes four spaces (a common case), but diverge in other cases.

	## Lists	## Lists

	A [list](@) is a sequence of one or more	A [list](@) is a sequence of one or more
	list items [of the same type]. The list items	list items [of the same type]. The list items

	may be separated by single [blank lines], but two	may be separated by any number of blank lines.
	blank lines end all containing lists.

	Two list items are [of the same type](@)	Two list items are [of the same type](@)
	if they begin with a [list marker] of the same type.	if they begin with a [list marker] of the same type.
	Two list markers are of the	Two list markers are of the
	same type if (a) they are bullet list markers using the same character	same type if (a) they are bullet list markers using the same character
	(`-`, `+`, or `*`) or (b) they are ordered list numbers with the same	(`-`, `+`, or `*`) or (b) they are ordered list numbers with the same
	delimiter (either `.` or `)`).	delimiter (either `.` or `)`).

	A list is an [ordered list](@)	A list is an [ordered list](@)
	if its constituent list items begin with	if its constituent list items begin with

	skipping to change at line 4535 ¶	skipping to change at line 4535 ¶
	<p>Foo</p>	<p>Foo</p>
	<ul>	<ul>
	<li>bar</li>	<li>bar</li>
	<li>baz</li>	<li>baz</li>
	</ul>	</ul>
	````````````````````````````````	````````````````````````````````

	`Markdown.pl` does not allow this, through fear of triggering a list	`Markdown.pl` does not allow this, through fear of triggering a list
	via a numeral in a hard-wrapped line:	via a numeral in a hard-wrapped line:


	```````````````````````````````` markdown	``` markdown
	The number of windows in my house is	The number of windows in my house is
	14. The number of doors is 6.	14. The number of doors is 6.

	````````````````````````````````	```

	Oddly, though, `Markdown.pl` does allow a blockquote to	Oddly, though, `Markdown.pl` does allow a blockquote to
	interrupt a paragraph, even though the same considerations might	interrupt a paragraph, even though the same considerations might
	apply.	apply.

	In CommonMark, we do allow lists to interrupt paragraphs, for	In CommonMark, we do allow lists to interrupt paragraphs, for
	two reasons. First, it is natural and not uncommon for people	two reasons. First, it is natural and not uncommon for people
	to start lists without blank lines:	to start lists without blank lines:


	I need to buy	``` markdown
	- new shoes	I need to buy
	- a coat	- new shoes
	- a plane ticket	- a coat
		- a plane ticket
		```

	Second, we are attracted to a	Second, we are attracted to a

	> [principle of uniformity](@):	> [principle of uniformity](@):
	> if a chunk of text has a certain	> if a chunk of text has a certain
	> meaning, it will continue to have the same meaning when put into a	> meaning, it will continue to have the same meaning when put into a
	> container block (such as a list item or blockquote).	> container block (such as a list item or blockquote).

	(Indeed, the spec for [list items] and [block quotes] presupposes	(Indeed, the spec for [list items] and [block quotes] presupposes
	this principle.) This principle implies that if	this principle.) This principle implies that if


	* I need to buy	``` markdown
	- new shoes	* I need to buy
	- a coat	- new shoes
	- a plane ticket	- a coat
		- a plane ticket
		```

	is a list item containing a paragraph followed by a nested sublist,	is a list item containing a paragraph followed by a nested sublist,
	as all Markdown implementations agree it is (though the paragraph	as all Markdown implementations agree it is (though the paragraph
	may be rendered without `<p>` tags, since the list is "tight"),	may be rendered without `<p>` tags, since the list is "tight"),
	then	then


	I need to buy	``` markdown
	- new shoes	I need to buy
	- a coat	- new shoes
	- a plane ticket	- a coat
		- a plane ticket
		```

	by itself should be a paragraph followed by a nested sublist.	by itself should be a paragraph followed by a nested sublist.

	Since it is well established Markdown practice to allow lists to	Since it is well established Markdown practice to allow lists to
	interrupt paragraphs inside list items, the [principle of	interrupt paragraphs inside list items, the [principle of
	uniformity] requires us to allow this outside list items as	uniformity] requires us to allow this outside list items as
	well. ([reStructuredText](http://docutils.sourceforge.net/rst.html)	well. ([reStructuredText](http://docutils.sourceforge.net/rst.html)
	takes a different approach, requiring blank lines before lists	takes a different approach, requiring blank lines before lists
	even inside other list items.)	even inside other list items.)


	skipping to change at line 5343 ¶	skipping to change at line 5350 ¶
	Interior spaces and [line endings] are collapsed into	Interior spaces and [line endings] are collapsed into
	single spaces, just as they would be by a browser:	single spaces, just as they would be by a browser:

	```````````````````````````````` example	```````````````````````````````` example
	`foo bar	`foo bar
	baz`	baz`
	.	.
	<p><code>foo bar baz</code></p>	<p><code>foo bar baz</code></p>
	````````````````````````````````	````````````````````````````````


		Not all [Unicode whitespace] (for instance, non-breaking space) is
		collapsed, however:

		```````````````````````````````` example
		`a b`
		.
		<p><code>a b</code></p>
		````````````````````````````````

	Q: Why not just leave the spaces, since browsers will collapse them	Q: Why not just leave the spaces, since browsers will collapse them
	anyway? A: Because we might be targeting a non-HTML format, and we	anyway? A: Because we might be targeting a non-HTML format, and we
	shouldn't rely on HTML-specific rendering assumptions.	shouldn't rely on HTML-specific rendering assumptions.

	(Existing implementations differ in their treatment of internal	(Existing implementations differ in their treatment of internal
	spaces and [line endings]. Some, including `Markdown.pl` and	spaces and [line endings]. Some, including `Markdown.pl` and
	`showdown`, convert an internal [line ending] into a	`showdown`, convert an internal [line ending] into a
	`<br />` tag. But this makes things difficult for those who like to	`<br />` tag. But this makes things difficult for those who like to
	hard-wrap their paragraphs, since a line break in the midst of a code	hard-wrap their paragraphs, since a line break in the midst of a code
	span will cause an unintended line break in the output. Others just	span will cause an unintended line break in the output. Others just

	skipping to change at line 6158 ¶	skipping to change at line 6174 ¶
	<p><em>foo<strong>bar</strong>baz</em></p>	<p><em>foo<strong>bar</strong>baz</em></p>
	````````````````````````````````	````````````````````````````````

	Note that in the preceding case, the interpretation	Note that in the preceding case, the interpretation

	``` markdown	``` markdown
	<p><em>foo</em><em>bar<em></em>baz</em></p>	<p><em>foo</em><em>bar<em></em>baz</em></p>
	```	```

	is precluded by the condition that a delimiter that	is precluded by the condition that a delimiter that

	can both open and close (like the `*` after `foo`	can both open and close (like the `*` after `foo`)
	cannot form emphasis if the sum of the lengths of	cannot form emphasis if the sum of the lengths of
	the delimiter runs containing the opening and	the delimiter runs containing the opening and
	closing delimiters is a multiple of 3.	closing delimiters is a multiple of 3.

	The same condition ensures that the following	The same condition ensures that the following
	cases are all strong emphasis nested inside	cases are all strong emphasis nested inside
	emphasis, even when the interior spaces are	emphasis, even when the interior spaces are
	omitted:	omitted:

	```````````````````````````````` example	```````````````````````````````` example

	skipping to change at line 6186 ¶	skipping to change at line 6202 ¶
	.	.
	<p><em>foo <strong>bar</strong></em></p>	<p><em>foo <strong>bar</strong></em></p>
	````````````````````````````````	````````````````````````````````

	```````````````````````````````` example	```````````````````````````````` example
	foobar**	foobar**
	.	.
	<p><em>foo<strong>bar</strong></em></p>	<p><em>foo<strong>bar</strong></em></p>
	````````````````````````````````	````````````````````````````````


	```````````````````````````````` example
	foobar**
	.
	<p><em>foo<strong>bar</strong></em></p>
	````````````````````````````````

	Indefinite levels of nesting are possible:	Indefinite levels of nesting are possible:

	```````````````````````````````` example	```````````````````````````````` example
	foo bar baz* bim** bop*	foo bar baz* bim** bop*
	.	.
	<p><em>foo <strong>bar <em>baz</em> bim</strong> bop</em></p>	<p><em>foo <strong>bar <em>baz</em> bim</strong> bop</em></p>
	````````````````````````````````	````````````````````````````````

	```````````````````````````````` example	```````````````````````````````` example
	foo [bar](/url)	foo [bar](/url)

	skipping to change at line 6871 ¶	skipping to change at line 6881 ¶

	Backslash escapes and entity and numeric character references	Backslash escapes and entity and numeric character references
	may be used in titles:	may be used in titles:

	```````````````````````````````` example	```````````````````````````````` example
	[link](/url "title \""")	[link](/url "title \""")
	.	.
	<p><a href="/url" title="title """>link</a></p>	<p><a href="/url" title="title """>link</a></p>
	````````````````````````````````	````````````````````````````````


		Titles must be separated from the link using a [whitespace].
		Other [Unicode whitespace] like non-breaking space doesn't work.

		```````````````````````````````` example
		[link](/url "title")
		.
		<p><a href="/url%C2%A0%22title%22">link</a></p>
		````````````````````````````````

	Nested balanced quotes are not allowed without escaping:	Nested balanced quotes are not allowed without escaping:

	```````````````````````````````` example	```````````````````````````````` example
	[link](/url "title "and" title")	[link](/url "title "and" title")
	.	.
	<p>[link](/url "title "and" title")</p>	<p>[link](/url "title "and" title")</p>
	````````````````````````````````	````````````````````````````````

	But it is easy to work around this by using a different quote type:	But it is easy to work around this by using a different quote type:


	skipping to change at line 7477 ¶	skipping to change at line 7496 ¶
	following closing bracket:	following closing bracket:

	```````````````````````````````` example	```````````````````````````````` example
	[foo*]: /url	[foo*]: /url

	[foo]	[foo]
	.	.
	<p><a href="/url">foo</a></p>	<p><a href="/url">foo</a></p>
	````````````````````````````````	````````````````````````````````


	Full references take precedence over shortcut references:	Full and compact references take precedence over shortcut
		references:

	```````````````````````````````` example	```````````````````````````````` example
	[foo][bar]	[foo][bar]

	[foo]: /url1	[foo]: /url1
	[bar]: /url2	[bar]: /url2
	.	.
	<p><a href="/url2">foo</a></p>	<p><a href="/url2">foo</a></p>
	````````````````````````````````	````````````````````````````````


		```````````````````````````````` example
		[foo][]

		[foo]: /url1
		.
		<p><a href="/url1">foo</a></p>
		````````````````````````````````

		Inline links also take precedence:

		```````````````````````````````` example
		[foo]()

		[foo]: /url1
		.
		<p><a href="">foo</a></p>
		````````````````````````````````

		```````````````````````````````` example
		[foo](not a link)

		[foo]: /url1
		.
		<p><a href="/url1">foo</a>(not a link)</p>
		````````````````````````````````

	In the following case `[bar][baz]` is parsed as a reference,	In the following case `[bar][baz]` is parsed as a reference,
	`[foo]` as normal text:	`[foo]` as normal text:

	```````````````````````````````` example	```````````````````````````````` example
	[foo][bar][baz]	[foo][bar][baz]

	[baz]: /url	[baz]: /url
	.	.
	<p>[foo]<a href="/url">bar</a></p>	<p>[foo]<a href="/url">bar</a></p>
	````````````````````````````````	````````````````````````````````

	skipping to change at line 8410 ¶	skipping to change at line 8456 ¶
	1. First we iterate through the open blocks, starting with the	1. First we iterate through the open blocks, starting with the
	root document, and descending through last children down to the last	root document, and descending through last children down to the last
	open block. Each block imposes a condition that the line must satisfy	open block. Each block imposes a condition that the line must satisfy
	if the block is to remain open. For example, a block quote requires a	if the block is to remain open. For example, a block quote requires a
	`>` character. A paragraph requires a non-blank line.	`>` character. A paragraph requires a non-blank line.
	In this phase we may match all or just some of the open	In this phase we may match all or just some of the open
	blocks. But we cannot close unmatched blocks yet, because we may have a	blocks. But we cannot close unmatched blocks yet, because we may have a
	[lazy continuation line].	[lazy continuation line].

	2. Next, after consuming the continuation markers for existing	2. Next, after consuming the continuation markers for existing

	blocks, we look for new block starts (e.g. `>` for a block quote.	blocks, we look for new block starts (e.g. `>` for a block quote).
	If we encounter a new block start, we close any blocks unmatched	If we encounter a new block start, we close any blocks unmatched
	in step 1 before creating the new block as a child of the last	in step 1 before creating the new block as a child of the last
	matched block.	matched block.

	3. Finally, we look at the remainder of the line (after block	3. Finally, we look at the remainder of the line (after block
	markers like `>`, list markers, and indentation have been consumed).	markers like `>`, list markers, and indentation have been consumed).
	This is text that can be incorporated into the last open	This is text that can be incorporated into the last open
	block (a paragraph, code block, heading, or raw HTML).	block (a paragraph, code block, heading, or raw HTML).

	Setext headings are formed when we see a line of a paragraph	Setext headings are formed when we see a line of a paragraph

End of changes. 17 change blocks.
	34 lines changed or deleted	80 lines changed or added
This html diff was produced by rfcdiff 1.45. The latest version is available from http://tools.ietf.org/tools/rfcdiff/