Flat code block syntax (was seemingly no good way to end bulleted list and start code block)

Michel Fortin michel.fortin at michelf.com
Mon Oct 8 07:39:13 EDT 2007

Le 2007-10-07 à 12:10, John MacFarlane a écrit :

>> I'm not sure the indentation feature is so useful. After all, you

>> can use

>> the old syntax if you want indentation. What do you think?


> I'd prefer to keep it simple and leave out the indentation feature.

Ok. Noted.

>> I'm not against option 2, but I don't see it as a replacement to

>> option 1

>> (for the reasons enumerated below).


>> It also has more potential of breaking existing documents. Imagine if

>> someone put multiple paragraphs and headers in a big list item,

>> and one

>> header is preceded by two blank lines to make it stand out more. The

>> content of that list item would become a code block. Not pretty.


> Good point.


>> We could allow this only between list items: add an additional

>> blank line

>> to break out of the current list; but not working for code blocks.

>> The

>> worse that could happen to existing documents then is that some

>> lists could

>> be broken into separate consecutive lists; that's much less

>> damaging than

>> turning some list item's content into a code block.


> This would complicate parsing quite a bit. At this point I'm inclined

> to keep changes as simple as possible, and just to implement option

> (1)

> without any version of (2).

Meanwhile, the HTML comment trick works to separate consecutive
lists. :-)

> On the issue of ~~~ vs ===, you give two reasons for preferring ~~~:


> (a) Because ~~~ is not used for Setext headers, we would not need to

> require a blank line before a code block. You could have a code block

> ~~~

> like this

> ~~~

> which would not be possible with ===.

I hadn't thought about this one, but it's true indeed.

> On (a): Partly because ~ already has a use in pandoc for inline

> text formatting (~~strikeout~~ and ~subscript~), and partly because

> it makes parsing easier, I'd be in favor of requiring blank lines

> before

> and after the new-style code blocks.

Yeah, but one is a block-level construct (code block) and the two
others are span-level. It isn't more ambiguous than, say, asterisks
as unordered list item markers and emphasis markers. Moreover, in our
case, it's even more different since the tilde are expected to be
three or more and to be alone on one line while your syntax for
strikeout and subscript is limited to two consecutive tilde which are
unlikely to be alone on their line.

> (b) Because === already has a use in markdown, using it to mark off

> unindented code blocks might confuse people and parsers who aren't

> familiar with the new syntax. Non-extended markdown parsers would

> parse these code blocks as a regular paragraph followed by a header.


> [...]


> On (b): Non-extended markdown parsers will make a mess of the

> new code blocks with either syntax, since they won't know to interpret

> the text between ~~~ as verbatim text. I don't see a big advantage

> here for the ~~~ syntax. Also, as I noted, in pandoc ~s are already

> used

> to indicate ~~strikeout text~~ and ~subscripts~. I can see that the

> ===

> syntax might cause problems with existing syntax highlighters, though.

The mess it'll make depends of the content of the code block, but
I'll have to agree that it was a weak argument. I still think it's
easier to read if we use a different character though.

> Perhaps an alternative would be to use ++++s instead of ~~~~s.

> Advantages: Not currently used for anything in markdown or extensions,

> vertically centered on the line in most fonts. Disadvantage: ugly?

Ugly indeed. What I've seen used for that is a line of dash: ----,
but that would trigger a horizontal line and I don't feel like
overriding that.

> I'd be interested in hearing what others think. Although I have a

> preference for ===, I'd be willing to go with ~~~ just to prevent a

> proliferation of different syntax extensions.

Me too. Let's wait until we have more comment on this.

> One more thought. I think it would be useful to allow something like

> this:


> ~~~(haskell)~~~~~~~~~~~~~~~~~~~~~~~~~~~~

> inlineNote = try $ do

> failIfStrict

> char '^'

> contents <- inlinesInBalanced "[" "]"

> return $ Note [Para contents]

> ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

The idea is nice, although I'm not sure it's the right syntax. My
idea has always been to end the code block on the first like having
with the same number of tilde so you can easily write an example of a
Markdown code block inside a code block by using various marker
lengths, much like it works for code spans. For instance:

You can write a code block like this:

Regular paragraph.

Code block

So I'd be more in favor of something that doesn't interfere when
counting the tilde, like this:

inlineNote = try $ do
char '^'
contents <- inlinesInBalanced "[" "]"
return $ Note [Para contents]

or this:

inlineNote = try $ do
char '^'
contents <- inlinesInBalanced "[" "]"
return $ Note [Para contents]

or this:

~~~~~ {.haskell}
inlineNote = try $ do
char '^'
contents <- inlinesInBalanced "[" "]"
return $ Note [Para contents]

Here I've followed the planned syntax for adding attributes to
Markdown elements which was discussed some time ago on this list,
where attributes are in braces and class names can be added by
preceding them with a dot. It is still unimplemented in PHP Markdown
Extra, but I think Markuru has most of it. I think it's better to
reuse that than to create an entirely new syntax for the same purpose.

Michel Fortin
michel.fortin at michelf.com

More information about the Markdown-Discuss mailing list