New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Spec is unclear on how to tell apart fenced code block and code span #197

Open
tabatkins opened this Issue Nov 14, 2014 · 3 comments

Comments

Projects
None yet
3 participants
@tabatkins

tabatkins commented Nov 14, 2014

Per the spec, a fenced code block is started by a line that contains 0-3 spaces, 3 or more backticks, then 0+ non-backtick characters. It's ended by a line that contains 0-3 spaces and at least as many backticks as the start line.

This is ambiguous with code spans, which are simply any sequence of two equal-length backtick strings which contain one or more characters and don't contain an equal-length backtick string inside.

Since code spans can contain newlines, the following are valid code spans:

`
foo
`
``
foo
``

(Verified in the dingus, and the second even shows up as an example in the spec.)

But if you add one more backtick, you instead get a fenced code block:

foo

(Sorry, GitHub's own implementation doesn't work properly here - it allows smaller numbers of backticks to close an open code block.)

The spec doesn't have any text detailing why this last case is one rather than the other.

@jgm jgm added the spec label Nov 17, 2014

@jgm

This comment has been minimized.

Show comment
Hide comment
@jgm

jgm Jan 6, 2015

Member

This is actually a bit of a mess. Given that just about anything can be an info string (with the current spec), the current implementation effectively rules out any code span that begins with a string of three or more backticks and does not end with a closing backtick string on the same line.

So, for example, this does not get parsed as a code span:

``` zounds ##
`##`` kebobble ```

even though this does:

``` zounds `#``
kebobble ```

(because backticks aren't allowed in info strings) and so does this:

`` zounds ##
`##` kebobble ``

Maybe the backtick code block syntax should be reconsidered, though it may be too widely established by now. The original fenced code block proposals discussed on markdown-discuss (long before github) used tildes, which didn't clash with the existing code span syntax. I'm sure github was seeing an analogy to python multiline strings -- which is appealing, but the analogy breaks down because code spans can begin with any number of backticks.

To restore sanity, we might disallow a line break right after opening backticks in a code span -- but that by itself wouldn't be enough, because of info strings.

I wonder if a discussion should be opened up on talk.commonmark.org?

Member

jgm commented Jan 6, 2015

This is actually a bit of a mess. Given that just about anything can be an info string (with the current spec), the current implementation effectively rules out any code span that begins with a string of three or more backticks and does not end with a closing backtick string on the same line.

So, for example, this does not get parsed as a code span:

``` zounds ##
`##`` kebobble ```

even though this does:

``` zounds `#``
kebobble ```

(because backticks aren't allowed in info strings) and so does this:

`` zounds ##
`##` kebobble ``

Maybe the backtick code block syntax should be reconsidered, though it may be too widely established by now. The original fenced code block proposals discussed on markdown-discuss (long before github) used tildes, which didn't clash with the existing code span syntax. I'm sure github was seeing an analogy to python multiline strings -- which is appealing, but the analogy breaks down because code spans can begin with any number of backticks.

To restore sanity, we might disallow a line break right after opening backticks in a code span -- but that by itself wouldn't be enough, because of info strings.

I wonder if a discussion should be opened up on talk.commonmark.org?

@jgm

This comment has been minimized.

Show comment
Hide comment
@jgm

jgm Jan 6, 2015

Member

By the way, I don't think the spec is actually ambiguous on this issue. "Indicators of block structure always take precedence over indicators of inline structure." See Example 3, for example. Your case is just another case of this type. But I think you have raised a good question about how rational/predictable the syntax is.

Member

jgm commented Jan 6, 2015

By the way, I don't think the spec is actually ambiguous on this issue. "Indicators of block structure always take precedence over indicators of inline structure." See Example 3, for example. Your case is just another case of this type. But I think you have raised a good question about how rational/predictable the syntax is.

@Ajedi32

This comment has been minimized.

Show comment
Hide comment
@Ajedi32

Ajedi32 Feb 19, 2015

Discourse discussion related to this topic (initial post by @jgm): A problem with backtick code fences

Ajedi32 commented Feb 19, 2015

Discourse discussion related to this topic (initial post by @jgm): A problem with backtick code fences

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment