From 99fd2fbdcd574b05ce78431714f9a2a472daf1fa Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Christoph=20P=C3=A4per?= Date: Wed, 8 Jul 2015 15:03:13 +0200 Subject: [PATCH 1/7] Update spec.txt MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Use digits instead of words. Unicode ranges for active characters. `a \t b` = `a b` ≠ `a b` `--- \n---` hierarchic auto-IDs for headers --- spec.txt | 87 +++++++++++++++++++++++++++++++++++++++++++------------- 1 file changed, 68 insertions(+), 19 deletions(-) diff --git a/spec.txt b/spec.txt index ac2ce2a5..14f7ff3f 100644 --- a/spec.txt +++ b/spec.txt @@ -242,8 +242,10 @@ that is not a [whitespace character]. An [ASCII punctuation character](@ascii-punctuation-character) is `!`, `"`, `#`, `$`, `%`, `&`, `'`, `(`, `)`, -`*`, `+`, `,`, `-`, `.`, `/`, `:`, `;`, `<`, `=`, `>`, `?`, `@`, -`[`, `\`, `]`, `^`, `_`, `` ` ``, `{`, `|`, `}`, or `~`. +`*`, `+`, `,`, `-`, `.`, `/` (U+0021–2F), +`:`, `;`, `<`, `=`, `>`, `?`, `@` (U+003A–0040), +`[`, `\`, `]`, `^`, `_`, `` ` `` (U+005B–0060), +`{`, `|`, `}`, or `~` (U+007B–007E). A [punctuation character](@punctuation-character) is an [ASCII punctuation character] or anything in @@ -252,7 +254,8 @@ the unicode classes `Pc`, `Pd`, `Pe`, `Pf`, `Pi`, `Po`, or `Ps`. ## Preprocessing Tabs in lines are immediately expanded to [spaces][space], with a tab -stop of 4 characters: +width of 4 characters: + . →foo→baz→→bim @@ -324,7 +327,7 @@ Markdown document. ## Horizontal rules A line consisting of 0-3 spaces of indentation, followed by a sequence -of three or more matching `-`, `_`, or `*` characters, each followed +of 3 or more matching `-`, `_`, or `*` characters, each followed optionally by any number of spaces, forms a [horizontal rule](@horizontal-rule). @@ -364,7 +367,7 @@ __ __

. -One to three spaces indent are allowed: +Indentation of 1–3 spaces are allowed: . *** @@ -376,7 +379,7 @@ One to three spaces indent are allowed:
. -Four spaces is too many: +4 spaces is too many: . *** @@ -393,7 +396,7 @@ Foo ***

. -More than three characters may be used: +More than 3 characters may be used: . _____________________________________ @@ -443,6 +446,22 @@ a------

---a---

. +2 spaces at the end do not establish a continuation on the next line of code: + +. +--- +--- + +--- +a +. +
+
+ +
+

a

+. + It is required that all of the [non-space character]s be the same. So, this is not a horizontal rule: @@ -731,10 +750,37 @@ ATX headers can be empty:

. +### Header identifiers + +Headers may be used to generate a table of contents. +Authors and readers commonly want to target links at headers. +Therefore, an implementation may choose to +add unique anchors to all headers +which are automatically generated from their textual content +and, if necessary to disambiguate, upper-level headers. +If that does not result in unique identifiers, +a counter may be added. + +. +# Foo +## Bar +## Baz +# Quuz +## Baz +# Foo +. +

Foo

+

Bar

+

Baz

+

Quuz

+

Baz

+

Foo

+. + ## Setext headers A [setext header](@setext-header) -consists of a line of text, containing at least one [non-space character], +consists of a line of text, containing at least 1 [non-space character], with no more than 3 spaces indentation, followed by a [setext header underline]. The line of text must be one that, were it not followed by the setext header underline, @@ -747,7 +793,7 @@ A [setext header underline](@setext-header-underline) is a sequence of `=` characters or a sequence of `-` characters, with no more than 3 spaces indentation and any number of trailing spaces. If a line containing a single `-` can be interpreted as an -empty [list items], it should be interpreted this way +empty [list item][list items], it should be interpreted this way and not as a [setext header underline]. The header is a level 1 header if `=` characters are used in the @@ -786,7 +832,7 @@ Foo

Foo

. -The header content can be indented up to three spaces, and need +The header content can be indented up to 3 spaces, and need not line up with the underlining: . @@ -804,7 +850,7 @@ not line up with the underlining:

Foo

. -Four spaces indent is too much: +4 spaces indent is too much: . Foo @@ -821,7 +867,7 @@ Foo
. -The setext header underline can be indented up to three spaces, and +The setext header underline can be indented up to 3 spaces, and may have trailing spaces: . @@ -831,7 +877,7 @@ Foo

Foo

. -Four spaces is too much: +4 spaces is too much: . Foo @@ -1083,7 +1129,7 @@ as Markdown: . -Here we have three chunks separated by blank lines: +Here we have 3 chunks separated by blank lines: . chunk1 @@ -1104,7 +1150,7 @@ chunk3 . -Any initial spaces beyond four will be included in the content, even +Any initial spaces beyond 4 will be included in the content, even in interior blank lines: . @@ -1130,7 +1176,7 @@ Foo bar

. -However, any non-blank line with fewer than four leading spaces ends +However, any non-blank line with fewer than 4 leading spaces ends the code block immediately. So a paragraph may occur immediately after indented code: @@ -1201,10 +1247,10 @@ Trailing spaces are included in the code block's content: ## Fenced code blocks A [code fence](@code-fence) is a sequence -of at least three consecutive backtick characters (`` ` ``) or +of at least 3 consecutive backtick characters (`` ` ``) or tildes (`~`). (Tildes and backticks cannot be mixed.) A [fenced code block](@fenced-code-block) -begins with a code fence, indented no more than three spaces. +begins with a code fence, indented no more than 3 spaces. The line with the opening code fence may optionally contain some text following the code fence; this is trimmed of leading and trailing @@ -1223,7 +1269,7 @@ each line of the content (if present). (If a content line is not indented, it is preserved unchanged. If it is indented less than N spaces, all of the indentation is removed.) -The closing code fence may be indented up to three spaces, and may be +The closing code fence may be indented up to 3 spaces, and may be followed only by spaces, which are ignored. If the end of the containing block (or document) is reached and no closing code fence has been found, the code block contains all of the lines after the @@ -1241,6 +1287,9 @@ as inlines. The first word of the [info string] is typically used to specify the language of the code sample, and rendered in the `class` attribute of the `code` tag. However, this spec does not mandate any particular treatment of the [info string]. +That means, extensions may use the info, for instance, +to highlight the syntax with different colors +or to parse and evaluate the code, e.g. to create a diagram. Here is a simple example with backticks: From 7f7bd71e0130a9dcbf8eb27ab46c39b3a912e42f Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Christoph=20P=C3=A4per?= Date: Mon, 30 Oct 2017 17:38:46 +0100 Subject: [PATCH 2/7] Update spec.txt deal with some conflicts --- spec.txt | 52 ++++------------------------------------------------ 1 file changed, 4 insertions(+), 48 deletions(-) diff --git a/spec.txt b/spec.txt index f9d8d80f..0035a1e7 100644 --- a/spec.txt +++ b/spec.txt @@ -337,16 +337,10 @@ the Unicode classes `Pc`, `Pd`, `Pe`, `Pf`, `Pi`, `Po`, or `Ps`. ## Tabs -<<<<<<< HEAD -Tabs in lines are immediately expanded to [spaces][space], with a tab -width of 4 characters: - -======= Tabs in lines are not expanded to [spaces]. However, in contexts where whitespace helps to define block structure, tabs behave as if they were replaced by spaces with a tab stop of 4 characters. ->>>>>>> jgm/master Thus, for example, a tab can be used instead of four spaces in an indented code block. (Note, however, that internal @@ -663,8 +657,7 @@ a------

---a---

```````````````````````````````` -<<<<<<< HEAD -2 spaces at the end do not establish a continuation on the next line of code: +Unlike within text, 2 spaces at the end do not establish a continuation on the next line of code: . --- @@ -682,8 +675,6 @@ a It is required that all of the [non-space character]s be the same. So, this is not a horizontal rule: -======= ->>>>>>> jgm/master It is required that all of the [non-whitespace characters] be the same. So, this is not a thematic break: @@ -1024,17 +1015,6 @@ a counter may be added.

Foo

. -## Setext headers - -A [setext header](@setext-header) -consists of a line of text, containing at least 1 [non-space character], -with no more than 3 spaces indentation, followed by a [setext header -underline]. The line of text must be -one that, were it not followed by the setext header underline, -would be interpreted as part of a paragraph: it cannot be -interpretable as a [code fence], [ATX header][ATX headers], -[block quote][block quotes], [horizontal rule][horizontal rules], -======= ## Setext headings A [setext heading](@) consists of one or more @@ -1045,20 +1025,14 @@ 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], ->>>>>>> jgm/master [list item][list items], or [HTML block][HTML blocks]. A [setext heading underline](@) is a sequence of `=` characters or a sequence of `-` characters, with no more than 3 spaces indentation and any number of trailing spaces. If a line containing a single `-` can be interpreted as an -<<<<<<< HEAD -empty [list item][list items], it should be interpreted this way -and not as a [setext header underline]. -======= empty [list items], it should be interpreted this way and not as a [setext heading underline]. ->>>>>>> jgm/master The heading is a level 1 heading if `=` characters are used in the [setext heading underline], and a level 2 heading if `-` @@ -1110,12 +1084,7 @@ Foo

Foo

```````````````````````````````` -<<<<<<< HEAD -The header content can be indented up to 3 spaces, and need -======= - -The heading content can be indented up to three spaces, and need ->>>>>>> jgm/master +The heading content can be indented up to 3 spaces, and need not line up with the underlining: ```````````````````````````````` example @@ -1151,12 +1120,7 @@ Foo
```````````````````````````````` -<<<<<<< HEAD -The setext header underline can be indented up to 3 spaces, and -======= - -The setext heading underline can be indented up to three spaces, and ->>>>>>> jgm/master +The setext heading underline can be indented up to 3 spaces, and may have trailing spaces: ```````````````````````````````` example @@ -1656,19 +1620,11 @@ Trailing spaces are included in the code block's content: ## Fenced code blocks -<<<<<<< HEAD -A [code fence](@code-fence) is a sequence -of at least 3 consecutive backtick characters (`` ` ``) or -tildes (`~`). (Tildes and backticks cannot be mixed.) -A [fenced code block](@fenced-code-block) -begins with a code fence, indented no more than 3 spaces. -======= A [code fence](@) is a sequence of at least three consecutive backtick characters (`` ` ``) or tildes (`~`). (Tildes and backticks cannot be mixed.) A [fenced code block](@) -begins with a code fence, indented no more than three spaces. ->>>>>>> jgm/master +begins with a code fence, indented no more than 3 spaces. The line with the opening code fence may optionally contain some text following the code fence; this is trimmed of leading and trailing From 2c62229abc8e40c8cdd6c6f143b2720956c5927f Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Christoph=20P=C3=A4per?= Date: Mon, 30 Oct 2017 17:52:14 +0100 Subject: [PATCH 3/7] rewrite ### Heading identifiers --- spec.txt | 47 ++++++++++++++++++++++++++++++++++------------- 1 file changed, 34 insertions(+), 13 deletions(-) diff --git a/spec.txt b/spec.txt index 0035a1e7..6abc293f 100644 --- a/spec.txt +++ b/spec.txt @@ -986,35 +986,56 @@ ATX headings can be empty:

```````````````````````````````` +### Heading identifiers -<<<<<<< HEAD -### Header identifiers - -Headers may be used to generate a table of contents. -Authors and readers commonly want to target links at headers. +Headings may be used to generate a table of contents (ToC). +Authors and readers commonly want to target links at headings. Therefore, an implementation may choose to -add unique anchors to all headers +add unique anchors to all headings which are automatically generated from their textual content -and, if necessary to disambiguate, upper-level headers. -If that does not result in unique identifiers, -a counter may be added. . # Foo ## Bar ## Baz -# Quuz -## Baz -# Foo .

Foo

Bar

Baz

+. + +If necessary to disambiguate, +the textual content of their ancestral headings can also be used. + +. +# Foo +## Bar +# Quuz +## Bar +. +

Foo

+

Bar

Quuz

-

Baz

+

Baz

+. + +If that does not result in unique identifiers, +a counter may be added. + +. +# Foo +# Foo +.

Foo

+

Foo

. +The exact algorithm to generate the identifier is not mandated. +Implementations may choose to apply Unicode normalization, +case folding, white space collapsing, affix addition, +romanization, removal of diacritic marks etc. +as required to conform to the requirements of the target language. + ## Setext headings A [setext heading](@) consists of one or more From d47ff242aaaa7cb8a173c8b3d3dad0ccb6c5bda9 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Christoph=20P=C3=A4per?= Date: Mon, 30 Oct 2017 17:54:58 +0100 Subject: [PATCH 4/7] remove dupe --- spec.txt | 4 +--- 1 file changed, 1 insertion(+), 3 deletions(-) diff --git a/spec.txt b/spec.txt index 6abc293f..d15cd097 100644 --- a/spec.txt +++ b/spec.txt @@ -673,9 +673,6 @@ a

a

. -It is required that all of the [non-space character]s be the same. -So, this is not a horizontal rule: - It is required that all of the [non-whitespace characters] be the same. So, this is not a thematic break: @@ -1105,6 +1102,7 @@ Foo

Foo

```````````````````````````````` + The heading content can be indented up to 3 spaces, and need not line up with the underlining: From 84f1f7f49f933df961587ec59d58a2f345c5a3ef Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Christoph=20P=C3=A4per?= Date: Mon, 30 Oct 2017 18:05:34 +0100 Subject: [PATCH 5/7] digit before "spaces" --- spec.txt | 92 ++++++++++++++++++++++++++++---------------------------- 1 file changed, 46 insertions(+), 46 deletions(-) diff --git a/spec.txt b/spec.txt index d15cd097..2bbee1d5 100644 --- a/spec.txt +++ b/spec.txt @@ -106,9 +106,9 @@ does not specify the syntax unambiguously. Here are some examples of questions it does not answer: 1. How much indentation is needed for a sublist? The spec says that - continuation paragraphs need to be indented four spaces, but is + continuation paragraphs need to be indented 4 spaces, but is not fully explicit about sublists. It is natural to think that - they, too, must be indented four spaces, but `Markdown.pl` does + they, too, must be indented 4 spaces, but `Markdown.pl` does not require that. This is hardly a "corner case," and divergences between implementations on this issue often lead to surprises for users in real documents. (See [this comment by John @@ -342,7 +342,7 @@ in contexts where whitespace helps to define block structure, tabs behave as if they were replaced by spaces with a tab stop of 4 characters. -Thus, for example, a tab can be used instead of four spaces +Thus, for example, a tab can be used instead of 4 spaces in an indented code block. (Note, however, that internal tabs are passed through as literal tabs, not expanded to spaces.) @@ -372,7 +372,7 @@ spaces.) In the following example, a continuation paragraph of a list item is indented with a tab; this has exactly the same effect -as indentation with four spaces would: +as indentation with 4 spaces would: ```````````````````````````````` example - foo @@ -406,9 +406,9 @@ optionally by a space, which is not considered part of the content. In the following case `>` is followed by a tab, which is treated as if it were expanded into spaces. Since one of theses spaces is considered part of the -delimiter, `foo` is considered to be indented six spaces +delimiter, `foo` is considered to be indented 6 spaces inside the block quote context, so we get an indented -code block starting with two spaces. +code block starting with 2 spaces. ```````````````````````````````` example >→→foo @@ -804,7 +804,7 @@ More than six `#` characters is not a heading: ```````````````````````````````` -At least one space is required between the `#` characters and the +At least 1 space is required between the `#` characters and the heading's contents, unless the heading is empty. Note that many implementations currently do not require the space. However, the space was required by the @@ -849,7 +849,7 @@ Leading and trailing blanks are ignored in parsing inline content: ```````````````````````````````` -One to three spaces indentation are allowed: +One to 3 spaces indentation are allowed: ```````````````````````````````` example ### foo @@ -862,7 +862,7 @@ One to three spaces indentation are allowed: ```````````````````````````````` -Four spaces are too much: +But 4 spaces are too much: ```````````````````````````````` example # foo @@ -1444,7 +1444,7 @@ An [indented code block](@) is composed of one or more An [indented chunk](@) is a sequence of non-blank lines, each indented four or more spaces. The contents of the code block are the literal contents of the lines, including trailing -[line endings], minus four spaces of indentation. +[line endings], minus 4 spaces of indentation. An indented code block has no [info string]. An indented code block cannot interrupt a paragraph, so there must be @@ -1599,7 +1599,7 @@ Heading ```````````````````````````````` -The first line can be indented more than four spaces: +The first line can be indented more than 4 spaces: ```````````````````````````````` example foo @@ -1870,7 +1870,7 @@ aaa ```````````````````````````````` -Four spaces indentation produces an indented code block: +Indentation of 4 spaces produces an indented code block: ```````````````````````````````` example ``` @@ -2050,7 +2050,7 @@ as raw HTML (and will not be escaped in HTML output). There are seven kinds of [HTML block], which can be defined 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 3 spaces optional indentation). It ends with the first subsequent line that meets a matching [end condition](@), or the last line of the document or other [container block]), if no line is encountered that meets the @@ -2789,7 +2789,7 @@ lines. ## Link reference definitions A [link reference definition](@) -consists of a [link label], indented up to three spaces, followed +consists of a [link label], indented up to 3 spaces, followed by a colon (`:`), optional [whitespace] (including up to one [line ending]), a [link destination], optional [whitespace] (including up to one @@ -3002,7 +3002,7 @@ This is a link reference definition, but it has no title: This is not a link reference definition, because it is indented -four spaces: +4 spaces: ```````````````````````````````` example [foo]: /url "title" @@ -3171,7 +3171,7 @@ ccc

```````````````````````````````` -However, the first line may be indented at most three spaces, +However, the first line may be indented at most 3 spaces, or an indented code block will be triggered: ```````````````````````````````` example @@ -3323,7 +3323,7 @@ baz

```````````````````````````````` -Four spaces gives us a code block: +But 4 spaces gives us a code block: ```````````````````````````````` example > # Foo @@ -3658,7 +3658,7 @@ baz

When including an indented code block in a block quote, remember that the [block quote marker] includes -both the `>` and a following space. So *five spaces* are needed after +both the `>` and a following space. So *5 spaces* are needed after the `>`: ```````````````````````````````` example @@ -3759,9 +3759,9 @@ with two lines.

The most important thing to notice is that the position of the text after the list marker determines how much indentation is needed in subsequent blocks in the list item. If the list -marker takes up two spaces, and there are three spaces between +marker takes up 2 spaces, and there are 3 spaces between the list marker and the next [non-whitespace character], then blocks -must be indented five spaces in order to fall under the list +must be indented 5 spaces in order to fall under the list item. Here are some examples showing how far content must be indented to be @@ -3871,7 +3871,7 @@ far enough past the blockquote marker: ```````````````````````````````` -Note that at least one space is needed between the list marker and +Note that at least 1 space is needed between the list marker and any following content, so these are not list items: ```````````````````````````````` example @@ -4004,7 +4004,7 @@ A start number may not be negative: constitute a sequence of blocks *Bs* starting with an indented code block and not separated from each other by more than one blank line, and *M* is a list marker of width *W* followed by - one space, then the result of prepending *M* and the following + 1 space, then the result of prepending *M* and the following space to the first line of *Ls*, and indenting subsequent lines of *Ls* by *W + 1* spaces, is a list item with *Bs* as its contents. If a line is empty, then it need not be indented. The type of the @@ -4012,7 +4012,7 @@ A start number may not be negative: marker. If the list item is ordered, then it is also assigned a start number, based on the ordered list marker. -An indented code block will have to be indented four spaces beyond +An indented code block will have to be indented 4 spaces beyond the edge of the region where text will be included in the list item. In the following case that is 6 spaces: @@ -4300,7 +4300,7 @@ foo list item with the same contents and attributes. If a line is empty, then it need not be indented. -Indented one space: +Indented 1 space: ```````````````````````````````` example 1. A paragraph @@ -4324,7 +4324,7 @@ with two lines.

```````````````````````````````` -Indented two spaces: +Indented 2 spaces: ```````````````````````````````` example 1. A paragraph @@ -4348,7 +4348,7 @@ with two lines.

```````````````````````````````` -Indented three spaces: +Indented 3 spaces: ```````````````````````````````` example 1. A paragraph @@ -4372,7 +4372,7 @@ with two lines.

```````````````````````````````` -Four spaces indent gives a code block: +But 4 spaces indent gives a code block: ```````````````````````````````` example 1. A paragraph @@ -4483,7 +4483,7 @@ The rules for sublists follow from the general rules above. A sublist must be indented the same number of spaces a paragraph would need to be in order to be included in the list item. -So, in this case we need two spaces indent: +So, in this case we need 2 spaces indent: ```````````````````````````````` example - foo @@ -4613,7 +4613,7 @@ baz John Gruber's Markdown spec says the following about list items: 1. "List markers typically start at the left margin, but may be indented - by up to three spaces. List markers must be followed by one or more + by up to 3 spaces. List markers must be followed by one or more spaces or a tab." 2. "To make lists look nice, you can wrap items with hanging indents.... @@ -4633,23 +4633,23 @@ John Gruber's Markdown spec says the following about list items: indented twice — 8 spaces or two tabs." These rules specify that a paragraph under a list item must be indented -four spaces (presumably, from the left margin, rather than the start of +4 spaces (presumably, from the left margin, rather than the start of the list marker, but this is not said), and that code under a list item -must be indented eight spaces instead of the usual four. They also say +must be indented eight spaces instead of the usual 4. They also say that a block quote must be indented, but not by how much; however, the -example given has four spaces indentation. Although nothing is said +example given has 4 spaces indentation. Although nothing is said about other kinds of block-level content, it is certainly reasonable to infer that *all* block elements under a list item, including other -lists, must be indented four spaces. This principle has been called the +lists, must be indented 4 spaces. This principle has been called the *four-space rule*. The four-space rule is clear and principled, and if the reference implementation `Markdown.pl` had followed it, it probably would have become the standard. However, `Markdown.pl` allowed paragraphs and -sublists to start with only two spaces indentation, at least on the +sublists to start with only 2 spaces indentation, at least on the outer level. Worse, its behavior was inconsistent: a sublist of an -outer-level list needed two spaces indentation, but a sublist of this -sublist needed three spaces. It is not surprising, then, that different +outer-level list needed 2 spaces indentation, but a sublist of this +sublist needed 3 spaces. It is not surprising, then, that different implementations of Markdown have developed very different rules for determining what comes under a list item. (Pandoc and python-Markdown, for example, stuck with Gruber's syntax description and the four-space @@ -4709,7 +4709,7 @@ as the four-space rule demands, rather than a single list, ``` -The choice of four spaces is arbitrary. It can be learned, but it is +The choice of 4 spaces is arbitrary. It can be learned, but it is not likely to be guessed, and it trips up beginners regularly. Would it help to adopt a two-space rule? The problem is that such @@ -4759,7 +4759,7 @@ as This is extremely unintuitive. Rather than requiring a fixed indent from the margin, we could require -a fixed indent (say, two spaces, or even one space) from the list marker (which +a fixed indent (say, 2 spaces, or even 1 space) from the list marker (which may itself be indented). This proposal would remove the last anomaly discussed. Unlike the spec presented above, it would count the following as a list item with a subparagraph, even though the paragraph `bar` @@ -4773,7 +4773,7 @@ is not indented as far as the first paragraph `foo`: Arguably this text does read like a list item with `bar` as a subparagraph, which may count in favor of the proposal. However, on this proposal indented -code would have to be indented six spaces after the list marker. And this +code would have to be indented 6 spaces after the list marker. And this would break a lot of existing Markdown, which has the pattern: ``` markdown @@ -4782,17 +4782,17 @@ would break a lot of existing Markdown, which has the pattern: indented code ``` -where the code is indented eight spaces. The spec above, by contrast, will +where the code is indented 8 spaces. The spec above, by contrast, will parse this text as expected, since the code block's indentation is measured from the beginning of `foo`. The one case that needs special treatment is a list item that *starts* with indented code. How much indentation is required in that case, since 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 -(and then the normal four spaces for the indented code). This will match the +that in such cases, we require 1 space indentation from the list marker +(and then the normal 4 spaces for the indented code). This will match the 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 4 spaces (a common case), but diverge in other cases. ## Lists @@ -7786,7 +7786,7 @@ Unicode case fold is used: ```````````````````````````````` -Consecutive internal [whitespace] is treated as one space for +Consecutive internal [whitespace] is treated as 1 space for purposes of determining matching: ```````````````````````````````` example @@ -8851,7 +8851,7 @@ baz

For a more visible alternative, a backslash before the -[line ending] may be used instead of two spaces: +[line ending] may be used instead of 2 spaces: ```````````````````````````````` example foo\ @@ -8862,7 +8862,7 @@ baz

```````````````````````````````` -More than two spaces can be used: +More than 2 spaces can be used: ```````````````````````````````` example foo From a2446cecb0d454eee486ffe6f5986962c38e6664 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Christoph=20P=C3=A4per?= Date: Mon, 30 Oct 2017 18:12:49 +0100 Subject: [PATCH 6/7] undo digits instead of words for numbers --- spec.txt | 168 ++++++++++++++++++++++++------------------------------- 1 file changed, 74 insertions(+), 94 deletions(-) diff --git a/spec.txt b/spec.txt index 2bbee1d5..95aed3d5 100644 --- a/spec.txt +++ b/spec.txt @@ -106,9 +106,9 @@ does not specify the syntax unambiguously. Here are some examples of questions it does not answer: 1. How much indentation is needed for a sublist? The spec says that - continuation paragraphs need to be indented 4 spaces, but is + continuation paragraphs need to be indented four spaces, but is not fully explicit about sublists. It is natural to think that - they, too, must be indented 4 spaces, but `Markdown.pl` does + they, too, must be indented four spaces, but `Markdown.pl` does not require that. This is hardly a "corner case," and divergences between implementations on this issue often lead to surprises for users in real documents. (See [this comment by John @@ -342,7 +342,7 @@ in contexts where whitespace helps to define block structure, tabs behave as if they were replaced by spaces with a tab stop of 4 characters. -Thus, for example, a tab can be used instead of 4 spaces +Thus, for example, a tab can be used instead of four spaces in an indented code block. (Note, however, that internal tabs are passed through as literal tabs, not expanded to spaces.) @@ -372,7 +372,7 @@ spaces.) In the following example, a continuation paragraph of a list item is indented with a tab; this has exactly the same effect -as indentation with 4 spaces would: +as indentation with four spaces would: ```````````````````````````````` example - foo @@ -406,9 +406,9 @@ optionally by a space, which is not considered part of the content. In the following case `>` is followed by a tab, which is treated as if it were expanded into spaces. Since one of theses spaces is considered part of the -delimiter, `foo` is considered to be indented 6 spaces +delimiter, `foo` is considered to be indented six spaces inside the block quote context, so we get an indented -code block starting with 2 spaces. +code block starting with two spaces. ```````````````````````````````` example >→→foo @@ -525,7 +525,7 @@ Markdown document. ## Thematic breaks -A line consisting of 0-3 spaces of indentation, followed by a sequence +A line consisting of up to three spaces of indentation, followed by a sequence of 3 or more matching `-`, `_`, or `*` characters, each followed optionally by any number of spaces, forms a [thematic break](@). @@ -570,7 +570,7 @@ __

```````````````````````````````` -Indentation of 1–3 spaces are allowed: +Indentation of one to three spaces is allowed: ```````````````````````````````` example *** @@ -581,9 +581,7 @@ Indentation of 1–3 spaces are allowed:
```````````````````````````````` - - -4 spaces is too many: +Four spaces is too many: ```````````````````````````````` example *** @@ -657,7 +655,7 @@ a------

---a---

```````````````````````````````` -Unlike within text, 2 spaces at the end do not establish a continuation on the next line of code: +Unlike within text, two spaces at the end do not establish a continuation on the next line of code: . --- @@ -771,7 +769,7 @@ closing sequence of any number of unescaped `#` characters. The opening sequence of `#` characters must be followed by a [space] or by the end of line. The optional closing sequence of `#`s must be preceded by a [space] and may be followed by spaces only. The opening -`#` character may be indented 0-3 spaces. The raw contents of the +`#` character may be indented 0-three spaces. The raw contents of the heading are stripped of leading and trailing spaces before being parsed as inline content. The heading level is equal to the number of `#` characters in the opening sequence. @@ -804,7 +802,7 @@ More than six `#` characters is not a heading: ```````````````````````````````` -At least 1 space is required between the `#` characters and the +At least one space is required between the `#` characters and the heading's contents, unless the heading is empty. Note that many implementations currently do not require the space. However, the space was required by the @@ -847,9 +845,7 @@ Leading and trailing blanks are ignored in parsing inline content: .

foo

```````````````````````````````` - - -One to 3 spaces indentation are allowed: +One to three spaces indentation are allowed: ```````````````````````````````` example ### foo @@ -862,7 +858,7 @@ One to 3 spaces indentation are allowed: ```````````````````````````````` -But 4 spaces are too much: +But four spaces are too much: ```````````````````````````````` example # foo @@ -1037,7 +1033,7 @@ as required to conform to the requirements of the target language. A [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 +character], with no more than three 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 @@ -1103,7 +1099,7 @@ Foo ```````````````````````````````` -The heading content can be indented up to 3 spaces, and need +The heading content can be indented up to three spaces, and need not line up with the underlining: ```````````````````````````````` example @@ -1120,9 +1116,7 @@ not line up with the underlining:

Foo

Foo

```````````````````````````````` - - -4 spaces indent is too much: +Four spaces indent is too much: ```````````````````````````````` example Foo @@ -1139,7 +1133,7 @@ Foo
```````````````````````````````` -The setext heading underline can be indented up to 3 spaces, and +The setext heading underline can be indented up to three spaces, and may have trailing spaces: ```````````````````````````````` example @@ -1148,9 +1142,7 @@ Foo .

Foo

```````````````````````````````` - - -4 spaces is too much: +Four spaces is too much: ```````````````````````````````` example Foo @@ -1361,9 +1353,7 @@ Foo bar --- baz -``` - -One can find four different interpretations: +```One can find four different interpretations: 1. paragraph "Foo", heading "bar", paragraph "baz" 2. paragraph "Foo bar", thematic break, paragraph "baz" @@ -1444,7 +1434,7 @@ An [indented code block](@) is composed of one or more An [indented chunk](@) is a sequence of non-blank lines, each indented four or more spaces. The contents of the code block are the literal contents of the lines, including trailing -[line endings], minus 4 spaces of indentation. +[line endings], minus four spaces of indentation. An indented code block has no [info string]. An indented code block cannot interrupt a paragraph, so there must be @@ -1599,7 +1589,7 @@ Heading ```````````````````````````````` -The first line can be indented more than 4 spaces: +The first line can be indented more than four spaces: ```````````````````````````````` example foo @@ -1643,7 +1633,7 @@ A [code fence](@) is a sequence of at least three consecutive backtick characters (`` ` ``) or tildes (`~`). (Tildes and backticks cannot be mixed.) A [fenced code block](@) -begins with a code fence, indented no more than 3 spaces. +begins with a code fence, indented no more than three spaces. The line with the opening code fence may optionally contain some text following the code fence; this is trimmed of leading and trailing @@ -1662,7 +1652,7 @@ each line of the content (if present). (If a content line is not indented, it is preserved unchanged. If it is indented less than N spaces, all of the indentation is removed.) -The closing code fence may be indented up to 3 spaces, and may be +The closing code fence may be indented up to three spaces, and may be followed only by spaces, which are ignored. If the end of the containing block (or document) is reached and no closing code fence has been found, the code block contains all of the lines after the @@ -1870,7 +1860,7 @@ aaa ```````````````````````````````` -Indentation of 4 spaces produces an indented code block: +Indentation of four spaces produces an indented code block: ```````````````````````````````` example ``` @@ -1884,7 +1874,7 @@ aaa ```````````````````````````````` -Closing fences may be indented by 0-3 spaces, and their indentation +Closing fences may be indented by 0-three spaces, and their indentation need not match that of the opening fence: ```````````````````````````````` example @@ -1907,7 +1897,7 @@ aaa ```````````````````````````````` -This is not a closing fence, because it is indented 4 spaces: +This is not a closing fence, because it is indented four spaces: ```````````````````````````````` example ``` @@ -2050,7 +2040,7 @@ as raw HTML (and will not be escaped in HTML output). There are seven kinds of [HTML block], which can be defined by their start and end conditions. The block begins with a line that -meets a [start condition](@) (after up to 3 spaces +meets a [start condition](@) (after up to three spaces optional indentation). It ends with the first subsequent line that meets a matching [end condition](@), or the last line of the document or other [container block]), if no line is encountered that meets the @@ -2596,7 +2586,7 @@ function matchwo(a,b) ```````````````````````````````` -The opening tag can be indented 1-3 spaces, but not 4: +The opening tag can be indented 1-three spaces, but not 4: ```````````````````````````````` example @@ -2789,7 +2779,7 @@ lines. ## Link reference definitions A [link reference definition](@) -consists of a [link label], indented up to 3 spaces, followed +consists of a [link label], indented up to three spaces, followed by a colon (`:`), optional [whitespace] (including up to one [line ending]), a [link destination], optional [whitespace] (including up to one @@ -3002,7 +2992,7 @@ This is a link reference definition, but it has no title: This is not a link reference definition, because it is indented -4 spaces: +four spaces: ```````````````````````````````` example [foo]: /url "title" @@ -3171,7 +3161,7 @@ ccc

```````````````````````````````` -However, the first line may be indented at most 3 spaces, +However, the first line may be indented at most three spaces, or an indented code block will be triggered: ```````````````````````````````` example @@ -3253,7 +3243,7 @@ these constructions. (A recipe is provided below in the section entitled ## Block quotes A [block quote marker](@) -consists of 0-3 spaces of initial indent, plus (a) the character `>` together +consists of 0-three spaces of initial indent, plus (a) the character `>` together with a following space, or (b) a single character `>` not followed by a space. The following rules define [block quotes]: @@ -3308,7 +3298,7 @@ baz

```````````````````````````````` -The `>` characters can be indented 1-3 spaces: +The `>` characters can be indented 1-three spaces: ```````````````````````````````` example > # Foo @@ -3323,7 +3313,7 @@ baz

```````````````````````````````` -But 4 spaces gives us a code block: +But four spaces gives us a code block: ```````````````````````````````` example > # Foo @@ -3658,7 +3648,7 @@ baz

When including an indented code block in a block quote, remember that the [block quote marker] includes -both the `>` and a following space. So *5 spaces* are needed after +both the `>` and a following space. So *five spaces* are needed after the `>`: ```````````````````````````````` example @@ -3696,7 +3686,7 @@ The following rules define [list items]: 1. **Basic case.** If a sequence of lines *Ls* constitute a sequence of 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 - marker of width *W* followed by 1 ≤ *N* ≤ 4 spaces, then the result + marker of width *W* followed by 1 ≤ *N* ≤ four spaces, then the result 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 list item with *Bs* as its contents. The type of the list item @@ -3759,9 +3749,9 @@ with two lines.

The most important thing to notice is that the position of the text after the list marker determines how much indentation is needed in subsequent blocks in the list item. If the list -marker takes up 2 spaces, and there are 3 spaces between +marker takes up two spaces, and there are three spaces between the list marker and the next [non-whitespace character], then blocks -must be indented 5 spaces in order to fall under the list +must be indented five spaces in order to fall under the list item. Here are some examples showing how far content must be indented to be @@ -3871,7 +3861,7 @@ far enough past the blockquote marker: ```````````````````````````````` -Note that at least 1 space is needed between the list marker and +Note that at least one space is needed between the list marker and any following content, so these are not list items: ```````````````````````````````` example @@ -4004,7 +3994,7 @@ A start number may not be negative: constitute a sequence of blocks *Bs* starting with an indented code block and not separated from each other by more than one blank line, and *M* is a list marker of width *W* followed by - 1 space, then the result of prepending *M* and the following + one space, then the result of prepending *M* and the following space to the first line of *Ls*, and indenting subsequent lines of *Ls* by *W + 1* spaces, is a list item with *Bs* as its contents. If a line is empty, then it need not be indented. The type of the @@ -4012,9 +4002,9 @@ A start number may not be negative: marker. If the list item is ordered, then it is also assigned a start number, based on the ordered list marker. -An indented code block will have to be indented 4 spaces beyond +An indented code block will have to be indented four spaces beyond the edge of the region where text will be included in the list item. -In the following case that is 6 spaces: +In the following case that is six spaces: ```````````````````````````````` example - foo @@ -4031,7 +4021,7 @@ In the following case that is 6 spaces: ```````````````````````````````` -And in this case it is 11 spaces: +And in this case it is 1one spaces: ```````````````````````````````` example 10. foo @@ -4139,7 +4129,7 @@ bar This is not a significant restriction, because when a block begins -with 1-3 spaces indent, the indentation can always be removed without +with 1-three spaces indent, the indentation can always be removed without a change in interpretation, allowing rule #1 to be applied. So, in the above case: @@ -4296,11 +4286,11 @@ foo 4. **Indentation.** If a sequence of lines *Ls* constitutes a list item according to rule #1, #2, or #3, then the result of indenting each line - of *Ls* by 1-3 spaces (the same for each line) also constitutes a + of *Ls* by 1-three spaces (the same for each line) also constitutes a list item with the same contents and attributes. If a line is empty, then it need not be indented. -Indented 1 space: +Indented one space: ```````````````````````````````` example 1. A paragraph @@ -4324,7 +4314,7 @@ with two lines.

```````````````````````````````` -Indented 2 spaces: +Indented two spaces: ```````````````````````````````` example 1. A paragraph @@ -4348,7 +4338,7 @@ with two lines.

```````````````````````````````` -Indented 3 spaces: +Indented three spaces: ```````````````````````````````` example 1. A paragraph @@ -4372,7 +4362,7 @@ with two lines.

```````````````````````````````` -But 4 spaces indent gives a code block: +But four spaces indent gives a code block: ```````````````````````````````` example 1. A paragraph @@ -4483,7 +4473,7 @@ The rules for sublists follow from the general rules above. A sublist must be indented the same number of spaces a paragraph would need to be in order to be included in the list item. -So, in this case we need 2 spaces indent: +So, in this case we need two spaces indent: ```````````````````````````````` example - foo @@ -4507,8 +4497,6 @@ So, in this case we need 2 spaces indent: ```````````````````````````````` - - One is not enough: ```````````````````````````````` example @@ -4540,8 +4528,6 @@ Here we need four, because the list marker is wider: ```````````````````````````````` - - Three is not enough: ```````````````````````````````` example @@ -4613,14 +4599,14 @@ baz John Gruber's Markdown spec says the following about list items: 1. "List markers typically start at the left margin, but may be indented - by up to 3 spaces. List markers must be followed by one or more + by up to three spaces. List markers must be followed by one or more spaces or a tab." 2. "To make lists look nice, you can wrap items with hanging indents.... But if you don't want to, you don't have to." 3. "List items may consist of multiple paragraphs. Each subsequent - paragraph in a list item must be indented by either 4 spaces or one + paragraph in a list item must be indented by either four spaces or one tab." 4. "It looks nice if you indent every line of the subsequent paragraphs, @@ -4630,26 +4616,26 @@ John Gruber's Markdown spec says the following about list items: delimiters need to be indented." 6. "To put a code block within a list item, the code block needs to be - indented twice — 8 spaces or two tabs." + indented twice — eight spaces or two tabs." These rules specify that a paragraph under a list item must be indented -4 spaces (presumably, from the left margin, rather than the start of +four spaces (presumably, from the left margin, rather than the start of the list marker, but this is not said), and that code under a list item must be indented eight spaces instead of the usual 4. They also say that a block quote must be indented, but not by how much; however, the -example given has 4 spaces indentation. Although nothing is said +example given has four spaces indentation. Although nothing is said about other kinds of block-level content, it is certainly reasonable to infer that *all* block elements under a list item, including other -lists, must be indented 4 spaces. This principle has been called the +lists, must be indented four spaces. This principle has been called the *four-space rule*. The four-space rule is clear and principled, and if the reference implementation `Markdown.pl` had followed it, it probably would have become the standard. However, `Markdown.pl` allowed paragraphs and -sublists to start with only 2 spaces indentation, at least on the +sublists to start with only two spaces indentation, at least on the outer level. Worse, its behavior was inconsistent: a sublist of an -outer-level list needed 2 spaces indentation, but a sublist of this -sublist needed 3 spaces. It is not surprising, then, that different +outer-level list needed two spaces indentation, but a sublist of this +sublist needed three spaces. It is not surprising, then, that different implementations of Markdown have developed very different rules for determining what comes under a list item. (Pandoc and python-Markdown, for example, stuck with Gruber's syntax description and the four-space @@ -4709,11 +4695,11 @@ as the four-space rule demands, rather than a single list, ``` -The choice of 4 spaces is arbitrary. It can be learned, but it is +The choice of four spaces is arbitrary. It can be learned, but it is not likely to be guessed, and it trips up beginners regularly. Would it help to adopt a two-space rule? The problem is that such -a rule, together with the rule allowing 1--3 spaces indentation of the +a rule, together with the rule allowing 1--three spaces indentation of the initial list marker, allows text that is indented *less than* the original list marker to be included in the list item. For example, `Markdown.pl` parses @@ -4759,7 +4745,7 @@ as This is extremely unintuitive. Rather than requiring a fixed indent from the margin, we could require -a fixed indent (say, 2 spaces, or even 1 space) from the list marker (which +a fixed indent (say, two spaces, or even one space) from the list marker (which may itself be indented). This proposal would remove the last anomaly discussed. Unlike the spec presented above, it would count the following as a list item with a subparagraph, even though the paragraph `bar` @@ -4773,7 +4759,7 @@ is not indented as far as the first paragraph `foo`: Arguably this text does read like a list item with `bar` as a subparagraph, which may count in favor of the proposal. However, on this proposal indented -code would have to be indented 6 spaces after the list marker. And this +code would have to be indented six spaces after the list marker. And this would break a lot of existing Markdown, which has the pattern: ``` markdown @@ -4782,25 +4768,23 @@ would break a lot of existing Markdown, which has the pattern: indented code ``` -where the code is indented 8 spaces. The spec above, by contrast, will +where the code is indented eight spaces. The spec above, by contrast, will parse this text as expected, since the code block's indentation is measured from the beginning of `foo`. The one case that needs special treatment is a list item that *starts* with indented code. How much indentation is required in that case, since we don't have a "first paragraph" to measure from? Rule #2 simply stipulates -that in such cases, we require 1 space indentation from the list marker -(and then the normal 4 spaces for the indented code). This will match the +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 four-space rule in cases where the list marker plus its initial indentation -takes 4 spaces (a common case), but diverge in other cases. +takes four spaces (a common case), but diverge in other cases. ## Lists A [list](@) is a sequence of one or more list items [of the same type]. The list items -may be separated by any number of blank lines. - -Two list items are [of the same type](@) +may be separated by any number of blank lines.Two list items are [of the same type](@) if they begin with a [list marker] of the same type. Two list markers are of the same type if (a) they are bullet list markers using the same character @@ -7316,9 +7300,7 @@ Parentheses inside the link destination may be escaped: [link](\(foo\)) .

link

-```````````````````````````````` - -One level of balanced parentheses is allowed without escaping: +````````````````````````````````One level of balanced parentheses is allowed without escaping: ```````````````````````````````` example [link]((foo)and(bar)) @@ -7622,9 +7604,7 @@ with the first right bracket (`]`) that is not backslash-escaped. Between these brackets there must be at least one [non-whitespace character]. Unescaped square bracket characters are not allowed in [link labels]. A link label can have at most 999 -characters inside the square brackets. - -One label [matches](@) +characters inside the square brackets.One label [matches](@) another just in case their normalized forms are equal. To normalize a label, perform the *Unicode case fold* and collapse consecutive internal [whitespace] to a single space. If there are multiple @@ -7786,7 +7766,7 @@ Unicode case fold is used: ```````````````````````````````` -Consecutive internal [whitespace] is treated as 1 space for +Consecutive internal [whitespace] is treated as one space for purposes of determining matching: ```````````````````````````````` example @@ -8851,7 +8831,7 @@ baz

For a more visible alternative, a backslash before the -[line ending] may be used instead of 2 spaces: +[line ending] may be used instead of two spaces: ```````````````````````````````` example foo\ @@ -8862,7 +8842,7 @@ baz

```````````````````````````````` -More than 2 spaces can be used: +More than two spaces can be used: ```````````````````````````````` example foo From ac4d9fb4f447c4abbc60c51165eadd14eb5e4b20 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Christoph=20P=C3=A4per?= Date: Mon, 30 Oct 2017 18:38:57 +0100 Subject: [PATCH 7/7] more minor cleanup --- spec.txt | 55 ++++++++++++++++++++++++++++++++----------------------- 1 file changed, 32 insertions(+), 23 deletions(-) diff --git a/spec.txt b/spec.txt index 95aed3d5..db58c3dd 100644 --- a/spec.txt +++ b/spec.txt @@ -526,7 +526,7 @@ Markdown document. ## Thematic breaks A line consisting of up to three spaces of indentation, followed by a sequence -of 3 or more matching `-`, `_`, or `*` characters, each followed +of three or more matching `-`, `_`, or `*` characters, each followed optionally by any number of spaces, forms a [thematic break](@). @@ -600,7 +600,7 @@ Foo ```````````````````````````````` -More than 3 characters may be used: +More than three characters may be used: ```````````````````````````````` example _____________________________________ @@ -769,7 +769,7 @@ closing sequence of any number of unescaped `#` characters. The opening sequence of `#` characters must be followed by a [space] or by the end of line. The optional closing sequence of `#`s must be preceded by a [space] and may be followed by spaces only. The opening -`#` character may be indented 0-three spaces. The raw contents of the +`#` character may be indented up to three spaces. The raw contents of the heading are stripped of leading and trailing spaces before being parsed as inline content. The heading level is equal to the number of `#` characters in the opening sequence. @@ -858,7 +858,7 @@ One to three spaces indentation are allowed: ```````````````````````````````` -But four spaces are too much: +Four spaces are too much: ```````````````````````````````` example # foo @@ -1353,7 +1353,9 @@ Foo bar --- baz -```One can find four different interpretations: +``` + +One can find four different interpretations: 1. paragraph "Foo", heading "bar", paragraph "baz" 2. paragraph "Foo bar", thematic break, paragraph "baz" @@ -1504,7 +1506,7 @@ as Markdown: ```````````````````````````````` -Here we have 3 chunks separated by blank lines: +Here we have three chunks separated by blank lines: ```````````````````````````````` example chunk1 @@ -1526,7 +1528,7 @@ chunk3 ```````````````````````````````` -Any initial spaces beyond 4 will be included in the content, even +Any initial spaces beyond four will be included in the content, even in interior blank lines: ```````````````````````````````` example @@ -1554,7 +1556,7 @@ bar

```````````````````````````````` -However, any non-blank line with fewer than 4 leading spaces ends +However, any non-blank line with fewer than four leading spaces ends the code block immediately. So a paragraph may occur immediately after indented code: @@ -1874,7 +1876,7 @@ aaa ```````````````````````````````` -Closing fences may be indented by 0-three spaces, and their indentation +Closing fences may be indented by up to three spaces, and their indentation need not match that of the opening fence: ```````````````````````````````` example @@ -2586,7 +2588,7 @@ function matchwo(a,b) ```````````````````````````````` -The opening tag can be indented 1-three spaces, but not 4: +The opening tag can be indented one to three spaces, but not four: ```````````````````````````````` example @@ -3243,7 +3245,7 @@ these constructions. (A recipe is provided below in the section entitled ## Block quotes A [block quote marker](@) -consists of 0-three spaces of initial indent, plus (a) the character `>` together +consists of up to three spaces of initial indent, plus (a) the character `>` together with a following space, or (b) a single character `>` not followed by a space. The following rules define [block quotes]: @@ -3298,7 +3300,7 @@ baz

```````````````````````````````` -The `>` characters can be indented 1-three spaces: +The `>` characters can be indented one to three spaces: ```````````````````````````````` example > # Foo @@ -3313,7 +3315,7 @@ baz

```````````````````````````````` -But four spaces gives us a code block: +Four spaces gives us a code block: ```````````````````````````````` example > # Foo @@ -3686,7 +3688,7 @@ The following rules define [list items]: 1. **Basic case.** If a sequence of lines *Ls* constitute a sequence of 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 - marker of width *W* followed by 1 ≤ *N* ≤ four 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 *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 @@ -4021,7 +4023,7 @@ In the following case that is six spaces: ```````````````````````````````` -And in this case it is 1one spaces: +And in this case it is eleven spaces: ```````````````````````````````` example 10. foo @@ -4129,7 +4131,7 @@ bar This is not a significant restriction, because when a block begins -with 1-three spaces indent, the indentation can always be removed without +with one to three spaces indent, the indentation can always be removed without a change in interpretation, allowing rule #1 to be applied. So, in the above case: @@ -4286,7 +4288,7 @@ foo 4. **Indentation.** If a sequence of lines *Ls* constitutes a list item according to rule #1, #2, or #3, then the result of indenting each line - of *Ls* by 1-three spaces (the same for each line) also constitutes a + of *Ls* by one to three spaces (the same for each line) also constitutes a list item with the same contents and attributes. If a line is empty, then it need not be indented. @@ -4362,7 +4364,7 @@ with two lines.

```````````````````````````````` -But four spaces indent gives a code block: +Four spaces indent gives a code block: ```````````````````````````````` example 1. A paragraph @@ -4497,6 +4499,7 @@ So, in this case we need two spaces indent: ```````````````````````````````` + One is not enough: ```````````````````````````````` example @@ -4528,6 +4531,7 @@ Here we need four, because the list marker is wider: ```````````````````````````````` + Three is not enough: ```````````````````````````````` example @@ -4621,7 +4625,7 @@ John Gruber's Markdown spec says the following about list items: These rules specify that a paragraph under a list item must be indented four spaces (presumably, from the left margin, rather than the start of the list marker, but this is not said), and that code under a list item -must be indented eight spaces instead of the usual 4. They also say +must be indented eight spaces instead of the usual four. They also say that a block quote must be indented, but not by how much; however, the example given has four spaces indentation. Although nothing is said about other kinds of block-level content, it is certainly reasonable to @@ -4699,7 +4703,7 @@ The choice of four spaces is arbitrary. It can be learned, but it is not likely to be guessed, and it trips up beginners regularly. Would it help to adopt a two-space rule? The problem is that such -a rule, together with the rule allowing 1--three spaces indentation of the +a rule, together with the rule allowing one to three spaces indentation of the initial list marker, allows text that is indented *less than* the original list marker to be included in the list item. For example, `Markdown.pl` parses @@ -4784,7 +4788,8 @@ takes four spaces (a common case), but diverge in other cases. A [list](@) is a sequence of one or more list items [of the same type]. The list items -may be separated by any number of blank lines.Two list items are [of the same type](@) +may be separated by any number of blank lines. +Two list items are [of the same type](@) if they begin with a [list marker] of the same type. Two list markers are of the same type if (a) they are bullet list markers using the same character @@ -7300,7 +7305,9 @@ Parentheses inside the link destination may be escaped: [link](\(foo\)) .

link

-````````````````````````````````One level of balanced parentheses is allowed without escaping: +```````````````````````````````` + +One level of balanced parentheses is allowed without escaping: ```````````````````````````````` example [link]((foo)and(bar)) @@ -7604,7 +7611,9 @@ with the first right bracket (`]`) that is not backslash-escaped. Between these brackets there must be at least one [non-whitespace character]. Unescaped square bracket characters are not allowed in [link labels]. A link label can have at most 999 -characters inside the square brackets.One label [matches](@) +characters inside the square brackets. + +One label [matches](@) another just in case their normalized forms are equal. To normalize a label, perform the *Unicode case fold* and collapse consecutive internal [whitespace] to a single space. If there are multiple