From c7d2ca53b4ba4a57b6e830f2167b327a6224e1fd Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Christoph=20P=C3=A4per?= Date: Fri, 29 Sep 2017 13:24:15 +0200 Subject: [PATCH 1/5] Update spec.txt --- spec.txt | 21 +++++++++++++++------ 1 file changed, 15 insertions(+), 6 deletions(-) diff --git a/spec.txt b/spec.txt index 9fd58413..2bdb2c97 100644 --- a/spec.txt +++ b/spec.txt @@ -749,7 +749,7 @@ If you want a thematic break in a list item, use a different bullet: ## ATX headings -An [ATX heading](@) +An [ATX heading](@) or [prefixed heading](@) consists of a string of characters, parsed as inline content, between an opening sequence of 1--6 unescaped `#` characters and an optional closing sequence of any number of unescaped `#` characters. @@ -968,10 +968,14 @@ ATX headings can be empty:

```````````````````````````````` +Note that MediaWiki markup uses the equals sign `=` for ATX-like headings instead +and uses the number sign `#` for ordered list items. +This constitutes one major incompatibility between CommonMark and MediaWiki. + ## Setext headings -A [setext heading](@) consists of one or more +A [setext heading](@) or [underlined 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 @@ -983,9 +987,9 @@ interpretable as a [code fence], [ATX heading][ATX headings], 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 -empty [list items], it should be interpreted this way +spaces indentation and any number of trailing spaces. +If a line containing a single `-` can be interpreted as an +empty [list item][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 @@ -1307,6 +1311,11 @@ One can find four different interpretations: 3. paragraph "Foo bar --- baz" 4. heading "Foo bar", paragraph "baz" +Interpretation 3 does not comply with the CommonMark rule +that both a [thematic break] and a setext heading +can interrupt a paragraph, +i.e. they do not need a blank line before or after. + 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 @@ -1588,7 +1597,7 @@ spaces and called the [info string](@). The [info string] may not contain any backtick characters. (The reason for this restriction is that otherwise some inline code would be incorrectly interpreted as the -beginning of a fenced code block.) +beginning of a fenced code block.) The content of the code block consists of all subsequent lines, until a closing [code fence] of the same type as the code block From 33e066b788042dbd4bda67389032a046d49b230a Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Christoph=20P=C3=A4per?= Date: Thu, 2 Nov 2017 14:54:52 +0100 Subject: [PATCH 2/5] more info strings - changes whitespace handling in links - changes suffix handling in headings - adds some examples - uses URL instead of URI - prepares change to possibly allow image links in link labels --- spec.txt | 436 +++++++++++++++++++++++++++++++++++++++---------------- 1 file changed, 309 insertions(+), 127 deletions(-) diff --git a/spec.txt b/spec.txt index 2bdb2c97..e3c93d36 100644 --- a/spec.txt +++ b/spec.txt @@ -102,10 +102,10 @@ source, not just in the processed document. ## Why is a spec needed? -John Gruber's [canonical description of Markdown's -syntax](http://daringfireball.net/projects/markdown/syntax) -does not specify the syntax unambiguously. Here are some examples of -questions it does not answer: +John Gruber's [canonical description of Markdown's syntax]( +http://daringfireball.net/projects/markdown/syntax) +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 @@ -898,15 +898,18 @@ Spaces are allowed after the closing sequence: A sequence of `#` characters with anything but [spaces] following it -is not a closing sequence, but counts as part of the contents of the -heading: +is only a closing sequence, if the number of its `#` characters +exactly matches the respective number in the opening sequence. +Whatever is following the first matching closing sequence +is treated as an [info string]. ```````````````````````````````` example ### foo ### b . -

foo ### b

+

foo

```````````````````````````````` +Otherwise it counts as part of the contents of the heading. The closing sequence must be preceded by a space: @@ -968,7 +971,7 @@ ATX headings can be empty:

```````````````````````````````` -Note that MediaWiki markup uses the equals sign `=` for ATX-like headings instead +Note: MediaWiki markup uses the equals sign `=` for ATX-like headings instead and uses the number sign `#` for ordered list items. This constitutes one major incompatibility between CommonMark and MediaWiki. @@ -1872,7 +1875,6 @@ aaa ```````````````````````````````` - Code fences (opening and closing) cannot contain internal spaces: ```````````````````````````````` example @@ -5676,6 +5678,7 @@ A [backtick string](@) is a string of one or more backtick characters (`` ` ``) that is neither preceded nor followed by a backtick. + A [code span](@) begins with a backtick string and ends with a backtick string of equal length. The contents of the code span are the characters between the two backtick strings, with leading and @@ -7177,7 +7180,8 @@ __a ## Links A link contains [link text] (the visible text), a [link destination] -(the URI that is the link destination), and optionally a [link title]. +(the URI that is the link destination), and optionally an [info string] +that usually starts with or only consists of a [link title]. There are two basic kinds of links in Markdown. In [inline links] the destination and title are given immediately after the link text. In [reference links] the destination and title are defined elsewhere in @@ -7217,7 +7221,14 @@ A [link destination](@) consists of either may impose limits on parentheses nesting to avoid performance issues, but at least three levels of nesting should be supported.) -A [link title](@) consists of either +A [link info string](@) works like any other [info string], +but it should contain a [link title], which may be empty +and should come first. It starts after the first run of whitespace +that terminates the [link destination]. +All kinds of brackets should occur either in properly nested pairs +or backslash-escaped inside a link info string. + +A [link title](@) consists of either - a sequence of zero or more characters between straight double-quote characters (`"`), including a `"` character only if it is @@ -7248,22 +7259,30 @@ above. Here is a simple inline link: ```````````````````````````````` example -[link](/uri "title") +[link](/url info string) . -

link

+

link

```````````````````````````````` +The info string is usually just a title: + +```````````````````````````````` example +[link](/url "title") +. +

link

+```````````````````````````````` -The title may be omitted: + +The info string may be omitted: ```````````````````````````````` example -[link](/uri) +[link](/url) . -

link

+

link

```````````````````````````````` -Both the title and the destination may be omitted: +Both the info string and the destination may be omitted: ```````````````````````````````` example [link]() @@ -7278,32 +7297,61 @@ Both the title and the destination may be omitted:

link

```````````````````````````````` +The link text may be empty, but this will +usually render the link inaccessible in the output. + +```````````````````````````````` example +[](/url "title") +. +

+```````````````````````````````` The destination cannot contain spaces or line breaks, -even if enclosed in pointy brackets: +i.e. whitespace. + +```````````````````````````````` example +[link](/foo bar) +. +

[link](/foo bar)

<-- legacy +

link

+```````````````````````````````` + +Except if enclosed in pointy brackets: ```````````````````````````````` example -[link](/my uri) +[link]() . -

[link](/my uri)

+

link

```````````````````````````````` +There can be a line break before or after an info string: + +```````````````````````````````` example +[link](foo +bar) +. +

link

+```````````````````````````````` ```````````````````````````````` example -[link]() +[link](foo bar +) . -

[link](</my uri>)

+

link

```````````````````````````````` +But no empty line: ```````````````````````````````` example [link](foo + bar) . -

[link](foo -bar)

+

[link](foo

+

bar)

```````````````````````````````` +There can also be no line break inside the target with angular brackets: ```````````````````````````````` example [link](link

```````````````````````````````` -Any number of parentheses are allowed without escaping, as long as they are -balanced: +Any number of parentheses are allowed without escaping, +as long as they are balanced: ```````````````````````````````` example [link](foo(and(bar))) @@ -7330,8 +7378,8 @@ balanced:

link

```````````````````````````````` -However, if you have unbalanced parentheses, you need to escape or use the -`<...>` form: +However, if you have unbalanced parentheses, +you need to escape them: ```````````````````````````````` example [link](foo\(and\(bar\)) @@ -7339,6 +7387,7 @@ However, if you have unbalanced parentheses, you need to escape or use the

link

```````````````````````````````` +Or use the `<...>` form: ```````````````````````````````` example [link]() @@ -7364,15 +7413,22 @@ A link can contain fragment identifiers and queries: [link](http://example.com#fragment) +[link](?foo=3) + [link](http://example.com?foo=3#frag) .

link

link

+

link

link

```````````````````````````````` -Note that a backslash before a non-escapable character is +Note: Optional extensions to this specification may make variables +from query parameters available for transclusion in the text +via templates or variables, e.g. `{{foo}}` or `$foo$` possibly. + +As usual, a backslash before a non-escapable character is just a backslash: ```````````````````````````````` example @@ -7397,10 +7453,11 @@ about how to escape or normalize URLs in the output.

link

```````````````````````````````` +(`auml;` = _รค_ = U+00E4 = 0xC3A4 in UTF-8.) Note that, because titles can often be parsed as destinations, -if you try to omit the destination and keep the title, you'll -get unexpected results: +trying to omit the destination and keep the title, +will lead to unexpected results: ```````````````````````````````` example [link]("title") @@ -7408,17 +7465,30 @@ get unexpected results:

link

```````````````````````````````` +This can be avoided by usually harmless dummy destinations +that refer to the document itself: + +```````````````````````````````` example +[link](# "title") + +[link](? "title") +. +

link

+

link

+```````````````````````````````` Titles may be in single quotes, double quotes, or parentheses: ```````````````````````````````` example [link](/url "title") + [link](/url 'title') + [link](/url (title)) . -

link -link -link

+

link

+

link

+

link

```````````````````````````````` @@ -7426,13 +7496,15 @@ Backslash escapes and entity and numeric character references may be used in titles: ```````````````````````````````` example -[link](/url "title \""") +[link](/url "title \""""") . -

link

+

link

```````````````````````````````` +(Whether or not character references are normalized to a canonic form +should probably be left to the implementation and output format.) -Titles must be separated from the link using a [whitespace]. +Info strings must be separated from the destination using a [whitespace]. Other [Unicode whitespace] like non-breaking space doesn't work. ```````````````````````````````` example @@ -7475,13 +7547,13 @@ titles with no closing quotation mark, though 1.0.2b8 does not. It seems preferable to adopt a simple, rational rule that works the same way in inline links and link reference definitions.) -[Whitespace] is allowed around the destination and title: +[Whitespace] is allowed around the destination and info string: ```````````````````````````````` example -[link]( /uri +[link]( /url "title" ) . -

link

+

link

```````````````````````````````` @@ -7489,79 +7561,87 @@ But it is not allowed between the link text and the following parenthesis: ```````````````````````````````` example -[link] (/uri) +[link] (/url) . -

[link] (/uri)

+

[link] (/url)

```````````````````````````````` -The link text may contain balanced brackets, but not unbalanced ones, -unless they are escaped: +The link text may contain balanced brackets: ```````````````````````````````` example -[link [foo [bar]]](/uri) +[link [foo [bar]]](/url) . -

link [foo [bar]]

+

link [foo [bar]]

```````````````````````````````` +But not unbalanced ones: ```````````````````````````````` example -[link] bar](/uri) +[link] bar](/url) . -

[link] bar](/uri)

+

[link] bar](/url)

```````````````````````````````` - ```````````````````````````````` example -[link [bar](/uri) +[link [bar](/url) . -

[link bar

+

[link bar

```````````````````````````````` +Unless they are escaped: + ```````````````````````````````` example -[link \[bar](/uri) +[link \[bar](/url) . -

link [bar

+

link [bar

```````````````````````````````` The link text may contain inline content: ```````````````````````````````` example -[link *foo **bar** `#`*](/uri) +[link *foo **bar** `#`*](/url) . -

link foo bar #

+

link foo bar #

```````````````````````````````` ```````````````````````````````` example -[![moon](moon.jpg)](/uri) +[![moon](moon.jpg)](/url) . -

moon

+

moon

```````````````````````````````` However, links may not contain other links, at any level of nesting. ```````````````````````````````` example -[foo [bar](/uri)](/uri) +[foo [bar](/url)](/url) . -

[foo bar](/uri)

+

[foo bar](/url)

```````````````````````````````` ```````````````````````````````` example -[foo *[bar [baz](/uri)](/uri)*](/uri) +[foo *[bar [baz](/url)](/url)*](/url) . -

[foo [bar baz](/uri)](/uri)

+

[foo [bar baz](/url)](/url)

```````````````````````````````` ```````````````````````````````` example -![[[foo](uri1)](uri2)](uri3) +![[[foo](url1)](url2)](url3) . -

[foo](uri2)

+

[foo](url2)

+```````````````````````````````` + + +```````````````````````````````` example +[![[foo](url1)](url2)](url3) +. +

[foo](url1)

```````````````````````````````` @@ -7569,9 +7649,9 @@ These cases illustrate the precedence of link text grouping over emphasis grouping: ```````````````````````````````` example -*[foo*](/uri) +*[foo*](/url) . -

*foo*

+

*foo*

```````````````````````````````` @@ -7603,9 +7683,9 @@ and autolinks over link grouping: ```````````````````````````````` example -[foo`](/uri)` +[foo`](/url)` . -

[foo](/uri)

+

[foo](/url)

```````````````````````````````` @@ -7655,7 +7735,6 @@ Here is a simple example:

foo

```````````````````````````````` - The rules for the [link text] are the same as with [inline links]. Thus: @@ -7665,18 +7744,18 @@ unless they are escaped: ```````````````````````````````` example [link [foo [bar]]][ref] -[ref]: /uri +[ref]: /url . -

link [foo [bar]]

+

link [foo [bar]]

```````````````````````````````` ```````````````````````````````` example [link \[bar][ref] -[ref]: /uri +[ref]: /url . -

link [bar

+

link [bar

```````````````````````````````` @@ -7685,38 +7764,38 @@ The link text may contain inline content: ```````````````````````````````` example [link *foo **bar** `#`*][ref] -[ref]: /uri +[ref]: /url . -

link foo bar #

+

link foo bar #

```````````````````````````````` ```````````````````````````````` example [![moon](moon.jpg)][ref] -[ref]: /uri +[ref]: /url . -

moon

+

moon

```````````````````````````````` However, links may not contain other links, at any level of nesting. ```````````````````````````````` example -[foo [bar](/uri)][ref] +[foo [bar](/url)][ref] -[ref]: /uri +[ref]: /url . -

[foo bar]ref

+

[foo bar]ref

```````````````````````````````` ```````````````````````````````` example [foo *bar [baz][ref]*][ref] -[ref]: /uri +[ref]: /url . -

[foo bar baz]ref

+

[foo bar baz]ref

```````````````````````````````` @@ -7729,18 +7808,18 @@ emphasis grouping: ```````````````````````````````` example *[foo*][ref] -[ref]: /uri +[ref]: /url . -

*foo*

+

*foo*

```````````````````````````````` ```````````````````````````````` example [foo *bar][ref] -[ref]: /uri +[ref]: /url . -

foo *bar

+

foo *bar

```````````````````````````````` @@ -7750,7 +7829,7 @@ and autolinks over link grouping: ```````````````````````````````` example [foo -[ref]: /uri +[ref]: /url .

[foo

```````````````````````````````` @@ -7759,7 +7838,7 @@ and autolinks over link grouping: ```````````````````````````````` example [foo`][ref]` -[ref]: /uri +[ref]: /url .

[foo][ref]

```````````````````````````````` @@ -7768,7 +7847,7 @@ and autolinks over link grouping: ```````````````````````````````` example [foo -[ref]: /uri +[ref]: /url .

[foohttp://example.com/?search=][ref]

```````````````````````````````` @@ -7843,13 +7922,16 @@ link text and the link label, then in the following we will have a single reference link, not two shortcut reference links, as intended: -``` markdown +```````````````````````````````` example [foo] [bar] [foo]: /url1 [bar]: /url2 -``` +. +

foo +bar

+```````````````````````````````` (Note that [shortcut reference links] were introduced by Gruber himself in a beta version of `Markdown.pl`, but never included @@ -7886,26 +7968,41 @@ labels define equivalent inline content: ```````````````````````````````` -[Link labels] cannot contain brackets, unless they are -backslash-escaped: +The normalized labels contain any formatting characters verbatim: + +```````````````````````````````` example +[foo][bar] + +[foo][*bar*] + +[*bar*]: /url1 + +[bar]: /url2 +. +

foo

+

foo

+```````````````````````````````` + + +[Link labels] cannot contain brackets: ```````````````````````````````` example [foo][ref[] -[ref[]: /uri +[ref[]: /url .

[foo][ref[]

-

[ref[]: /uri

+

[ref[]: /url

```````````````````````````````` ```````````````````````````````` example [foo][ref[bar]] -[ref[bar]]: /uri +[ref[bar]]: /url .

[foo][ref[bar]]

-

[ref[bar]]: /uri

+

[ref[bar]]: /url

```````````````````````````````` @@ -7919,23 +8016,72 @@ backslash-escaped: ```````````````````````````````` +```````````````````````````````` example +[[[foo]]] + +[foo]: /url +. +

[[foo]]

+```````````````````````````````` + + +Unless they are backslash-escaped: + ```````````````````````````````` example [foo][ref\[] -[ref\[]: /uri +[ref\[]: /url . -

foo

+

foo

```````````````````````````````` Note that in this example `]` is not backslash-escaped: ```````````````````````````````` example -[bar\\]: /uri +[bar\\]: /url [bar\\] . -

bar\

+

bar\

+```````````````````````````````` + + +Since unescaped square brackets are not allowed in link labels, +they can never look like links or image references: + +```````````````````````````````` example +[foo][[foo](bar)] + +[[foo](bar)]: /url1 + +[[foo]]: /url2 + +[foo]: /url3 +. +

foo[foo]

+

[foo]: /url1

+

[foo]: /url2

+```````````````````````````````` + +In particular, labels that would make valid image links +are not collapsed to their link text: + +```````````````````````````````` example +[foo][![alt](/url1)] + +[foo][![alt]] + +[![alt]] + +[alt]: /url2 + +[![alt]]: /url3 +. +

[foo][alt]

+

[foo][alt]

+

[alt]

+

[alt]: /url3

```````````````````````````````` @@ -7944,10 +8090,10 @@ A [link label] must contain at least one [non-whitespace character]: ```````````````````````````````` example [] -[]: /uri +[]: /url .

[]

-

[]: /uri

+

[]: /url

```````````````````````````````` @@ -7956,12 +8102,12 @@ A [link label] must contain at least one [non-whitespace character]: ] [ - ]: /uri + ]: /url .

[ ]

[ -]: /uri

+]: /url

```````````````````````````````` @@ -7970,7 +8116,7 @@ consists of a [link label] that [matches] a [link reference definition] elsewhere in the document, followed by the string `[]`. The contents of the first link label are parsed as inlines, -which are used as the link's text. The link's URI and title are +which are used as the link's text. The link's destination and title are provided by the matching reference link definition. Thus, `[foo][]` is equivalent to `[foo][foo]`. @@ -8003,9 +8149,9 @@ The link labels are case-insensitive: ```````````````````````````````` - As with full reference links, [whitespace] is not -allowed between the two sets of brackets: +allowed between the two sets of brackets, +so the first pair is treated as a [shortcut reference link]: ```````````````````````````````` example [foo] @@ -8023,9 +8169,9 @@ consists of a [link label] that [matches] a [link reference definition] elsewhere in the document and is not followed by `[]` or a link label. The contents of the first link label are parsed as inlines, -which are used as the link's text. The link's URI and title +which are used as the link's text. The link's destination and title are provided by the matching link reference definition. -Thus, `[foo]` is equivalent to `[foo][]`. +Thus, `[foo]` is equivalent to `[foo][]` and `[foo][foo]`. ```````````````````````````````` example [foo] @@ -8139,13 +8285,6 @@ Inline links also take precedence:

foo

```````````````````````````````` -```````````````````````````````` example -[foo](not a link) - -[foo]: /url1 -. -

foo(not a link)

-```````````````````````````````` In the following case `[bar][baz]` is parsed as a reference, `[foo]` as normal text: @@ -8172,8 +8311,9 @@ Here, though, `[foo][bar]` is parsed as a reference, since ```````````````````````````````` -Here `[foo]` is not parsed as a shortcut reference, because it -is followed by a link label (even though `[bar]` is not defined): +Here, `[foo]` is not parsed as a shortcut reference, because it +is followed by a link label (even though `[bar]` is not defined +and is then found to be a link text instead): ```````````````````````````````` example [foo][bar][baz] @@ -8204,6 +8344,9 @@ this is standardly used as the image's `alt` attribute.

foo

```````````````````````````````` +Though this spec is concerned with parsing, not rendering, it is +recommended that in rendering to HTML, only the plain string content +of the [image description] be used: ```````````````````````````````` example ![foo *bar*] @@ -8228,12 +8371,20 @@ this is standardly used as the image's `alt` attribute. ```````````````````````````````` -Though this spec is concerned with parsing, not rendering, it is -recommended that in rendering to HTML, only the plain string content -of the [image description] be used. Note that in +Note that in the above example, the alt attribute's value is `foo bar`, not `foo [bar](/url)` or `foo bar`. Only the plain string content is rendered, without formatting. +With an implementation that treated an image as a floating figure +if it is the only content of a paragraph, +the HTML output for this example would differ: + +``` HTML +
foo bar
foo bar
+``` + + +The rules for inline formatting other than links is the same as for links: ```````````````````````````````` example ![foo *bar*][] @@ -8253,6 +8404,8 @@ content is rendered, without formatting. ```````````````````````````````` +Inline image: + ```````````````````````````````` example ![foo](train.jpg) . @@ -8415,7 +8568,7 @@ If you want a link after a literal `!`, backslash-escape the ## Autolinks -[Autolink](@)s are absolute URIs and email addresses inside +[Autolink](@)s are absolute URLs and email addresses inside `<` and `>`. They are parsed as links, with the URL or email address as the link label. @@ -8500,14 +8653,33 @@ with their syntax: ```````````````````````````````` -Spaces are not allowed in autolinks: +Spaces are not allowed in autolink URLs. +The first whitespace is used to separate the URL from the optional [info string] +which is retained for the link text: ```````````````````````````````` example - + . -

<http://foo.bar/baz bim>

+

http://foo.bar/baz info string

```````````````````````````````` +If the URL is enclosed in another set of angular brackets, +it may contain whitespace: + +```````````````````````````````` example +<> +. +

http://foo.bar/baz bim

+```````````````````````````````` + +These can also contain relative targets, +because they can never be confused with HTML tags: + +```````````````````````````````` example +<> +. +

/url

+```````````````````````````````` Backslash-escapes do not work inside autolinks: @@ -8528,8 +8700,11 @@ for these purposes, is anything that matches the [non-normative regex from the HTML5 spec](https://html.spec.whatwg.org/multipage/forms.html#e-mail-state-(type=email)): - /^[a-zA-Z0-9.!#$%&'*+/=?^_`{|}~-]+@[a-zA-Z0-9](?:[a-zA-Z0-9-]{0,61}[a-zA-Z0-9])? - (?:\.[a-zA-Z0-9](?:[a-zA-Z0-9-]{0,61}[a-zA-Z0-9])?)*$/ +``` regex +/^[a-zA-Z0-9.!#$%&'*+/=?^_`{|}~-]+@[a-zA-Z0-9](?:[a-zA-Z0-9-]{0,61}[a-zA-Z0-9])? +(?:\.[a-zA-Z0-9](?:[a-zA-Z0-9-]{0,61}[a-zA-Z0-9])?)*$/ +``` + Examples of email autolinks: @@ -8547,6 +8722,13 @@ Examples of email autolinks: ```````````````````````````````` +```````````````````````````````` example + +. +

foo@bar.example.com "My Name"

+```````````````````````````````` + + Backslash-escapes do not work inside email autolinks: ```````````````````````````````` example From b164ca6f1197916518637c716a17a993ecbbe8be Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Christoph=20P=C3=A4per?= Date: Fri, 19 Oct 2018 11:16:11 +0200 Subject: [PATCH 3/5] revert some minor changes --- spec.txt | 26 ++++++++------------------ 1 file changed, 8 insertions(+), 18 deletions(-) diff --git a/spec.txt b/spec.txt index e3c93d36..021ed848 100644 --- a/spec.txt +++ b/spec.txt @@ -102,8 +102,8 @@ source, not just in the processed document. ## Why is a spec needed? -John Gruber's [canonical description of Markdown's syntax]( -http://daringfireball.net/projects/markdown/syntax) +John Gruber's [canonical description of Markdown's +syntax](http://daringfireball.net/projects/markdown/syntax) does not specify the syntax unambiguously. Here are some examples of questions it does not answer: @@ -749,7 +749,7 @@ If you want a thematic break in a list item, use a different bullet: ## ATX headings -An [ATX heading](@) or [prefixed heading](@) +An [ATX heading](@) consists of a string of characters, parsed as inline content, between an opening sequence of 1--6 unescaped `#` characters and an optional closing sequence of any number of unescaped `#` characters. @@ -971,14 +971,10 @@ ATX headings can be empty:

```````````````````````````````` -Note: MediaWiki markup uses the equals sign `=` for ATX-like headings instead -and uses the number sign `#` for ordered list items. -This constitutes one major incompatibility between CommonMark and MediaWiki. - ## Setext headings -A [setext heading](@) or [underlined heading](@) consists of one or more +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 a [setext heading underline]. The lines of text must be such @@ -990,8 +986,8 @@ interpretable as a [code fence], [ATX heading][ATX headings], 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 +spaces indentation and any number of trailing spaces. If a line +containing a single `-` can be interpreted as an empty [list item][list items], it *should* be interpreted this way and not as a [setext heading underline]. @@ -1314,11 +1310,6 @@ One can find four different interpretations: 3. paragraph "Foo bar --- baz" 4. heading "Foo bar", paragraph "baz" -Interpretation 3 does not comply with the CommonMark rule -that both a [thematic break] and a setext heading -can interrupt a paragraph, -i.e. they do not need a blank line before or after. - 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 @@ -1600,7 +1591,7 @@ spaces and called the [info string](@). The [info string] may not contain any backtick characters. (The reason for this restriction is that otherwise some inline code would be incorrectly interpreted as the -beginning of a fenced code block.) +beginning of a fenced code block.) The content of the code block consists of all subsequent lines, until a closing [code fence] of the same type as the code block @@ -7180,7 +7171,7 @@ __a ## Links A link contains [link text] (the visible text), a [link destination] -(the URI that is the link destination), and optionally an [info string] +(the URL that is the link destination), and optionally an [info string] that usually starts with or only consists of a [link title]. There are two basic kinds of links in Markdown. In [inline links] the destination and title are given immediately after the link text. In @@ -7312,7 +7303,6 @@ i.e. whitespace. ```````````````````````````````` example [link](/foo bar) . -

[link](/foo bar)

<-- legacy

link

```````````````````````````````` From 41b9a363d30be4445471018c40e64c7fee13fb61 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Christoph=20P=C3=A4per?= Date: Fri, 19 Oct 2018 11:30:39 +0200 Subject: [PATCH 4/5] more retroactive cleanup --- spec.txt | 94 +++++--------------------------------------------------- 1 file changed, 8 insertions(+), 86 deletions(-) diff --git a/spec.txt b/spec.txt index 021ed848..f4cccbc9 100644 --- a/spec.txt +++ b/spec.txt @@ -5669,7 +5669,6 @@ A [backtick string](@) is a string of one or more backtick characters (`` ` ``) that is neither preceded nor followed by a backtick. - A [code span](@) begins with a backtick string and ends with a backtick string of equal length. The contents of the code span are the characters between the two backtick strings, with leading and @@ -7359,8 +7358,8 @@ Parentheses inside the link destination may be escaped:

link

```````````````````````````````` -Any number of parentheses are allowed without escaping, -as long as they are balanced: +Any number of parentheses are allowed without escaping, as long as they are +balanced: ```````````````````````````````` example [link](foo(and(bar))) @@ -7368,8 +7367,7 @@ as long as they are balanced:

link

```````````````````````````````` -However, if you have unbalanced parentheses, -you need to escape them: +However, if you have unbalanced parentheses, you need to escape them: ```````````````````````````````` example [link](foo\(and\(bar\)) @@ -7414,10 +7412,6 @@ A link can contain fragment identifiers and queries: ```````````````````````````````` -Note: Optional extensions to this specification may make variables -from query parameters available for transclusion in the text -via templates or variables, e.g. `{{foo}}` or `$foo$` possibly. - As usual, a backslash before a non-escapable character is just a backslash: @@ -7958,23 +7952,8 @@ labels define equivalent inline content: ```````````````````````````````` -The normalized labels contain any formatting characters verbatim: - -```````````````````````````````` example -[foo][bar] - -[foo][*bar*] - -[*bar*]: /url1 - -[bar]: /url2 -. -

foo

-

foo

-```````````````````````````````` - - -[Link labels] cannot contain brackets: +[Link labels] cannot contain brackets, unless they are +backslash-escaped: ```````````````````````````````` example [foo][ref[] @@ -8006,17 +7985,6 @@ The normalized labels contain any formatting characters verbatim: ```````````````````````````````` -```````````````````````````````` example -[[[foo]]] - -[foo]: /url -. -

[[foo]]

-```````````````````````````````` - - -Unless they are backslash-escaped: - ```````````````````````````````` example [foo][ref\[] @@ -8037,44 +8005,6 @@ Note that in this example `]` is not backslash-escaped: ```````````````````````````````` -Since unescaped square brackets are not allowed in link labels, -they can never look like links or image references: - -```````````````````````````````` example -[foo][[foo](bar)] - -[[foo](bar)]: /url1 - -[[foo]]: /url2 - -[foo]: /url3 -. -

foo[foo]

-

[foo]: /url1

-

[foo]: /url2

-```````````````````````````````` - -In particular, labels that would make valid image links -are not collapsed to their link text: - -```````````````````````````````` example -[foo][![alt](/url1)] - -[foo][![alt]] - -[![alt]] - -[alt]: /url2 - -[![alt]]: /url3 -. -

[foo][alt]

-

[foo][alt]

-

[alt]

-

[alt]: /url3

-```````````````````````````````` - - A [link label] must contain at least one [non-whitespace character]: ```````````````````````````````` example @@ -8334,9 +8264,6 @@ this is standardly used as the image's `alt` attribute.

foo

```````````````````````````````` -Though this spec is concerned with parsing, not rendering, it is -recommended that in rendering to HTML, only the plain string content -of the [image description] be used: ```````````````````````````````` example ![foo *bar*] @@ -8361,18 +8288,13 @@ of the [image description] be used: ```````````````````````````````` +Though this spec is concerned with parsing, not rendering, it is +recommended that in rendering to HTML, only the plain string content +of the [image description] be used. Note that in the above example, the alt attribute's value is `foo bar`, not `foo [bar](/url)` or `foo bar`. Only the plain string content is rendered, without formatting. -With an implementation that treated an image as a floating figure -if it is the only content of a paragraph, -the HTML output for this example would differ: - -``` HTML -
foo bar
foo bar
-``` - The rules for inline formatting other than links is the same as for links: From 949086cf9ca17ebc800e9d0d40d03e85ec2b8b4c Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Christoph=20P=C3=A4per?= Date: Fri, 19 Oct 2018 11:37:02 +0200 Subject: [PATCH 5/5] remove info strings from autolinks also removes `` facility --- spec.txt | 34 ++++------------------------------ 1 file changed, 4 insertions(+), 30 deletions(-) diff --git a/spec.txt b/spec.txt index f4cccbc9..dbb5355f 100644 --- a/spec.txt +++ b/spec.txt @@ -7952,8 +7952,8 @@ labels define equivalent inline content: ```````````````````````````````` -[Link labels] cannot contain brackets, unless they are -backslash-escaped: +[Link labels] cannot contain brackets, unless they are +backslash-escaped: ```````````````````````````````` example [foo][ref[] @@ -8566,32 +8566,13 @@ with their syntax: Spaces are not allowed in autolink URLs. -The first whitespace is used to separate the URL from the optional [info string] -which is retained for the link text: ```````````````````````````````` example - + . -

http://foo.bar/baz info string

+

<http://foo.bar/baz bim>

```````````````````````````````` -If the URL is enclosed in another set of angular brackets, -it may contain whitespace: - -```````````````````````````````` example -<> -. -

http://foo.bar/baz bim

-```````````````````````````````` - -These can also contain relative targets, -because they can never be confused with HTML tags: - -```````````````````````````````` example -<> -. -

/url

-```````````````````````````````` Backslash-escapes do not work inside autolinks: @@ -8634,13 +8615,6 @@ Examples of email autolinks: ```````````````````````````````` -```````````````````````````````` example - -. -

foo@bar.example.com "My Name"

-```````````````````````````````` - - Backslash-escapes do not work inside email autolinks: ```````````````````````````````` example