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

[Michel Fortin]

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:

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

or this:

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

or this:

     ~~~~~ {.haskell}
     inlineNote = try $ do
       failIfStrict
       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
http://michelf.com/