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

[Michel Fortin]

Le 2007-10-06 à 23:55, John MacFarlane a écrit :


>> So I'm seriously thinking about adding a second (unindented) code  

>> block

>> syntax to PHP Markdown Extra that would avoid this issue entirely.

>> Something like this:

>>

>>     Regular paragraph

>>

>>     ~~~

>>     Code block

>>     ~~~

>

> I like the idea of doing something about this problem.  I've been

> thinking about adding something like this to pandoc, too, and it

> would be good if possible to reach some agreement on a syntax.


That would be good indeed. Here's what I have in mind at the moment:  
the *flat* code block starts on a line with zero to three spaces, is  
followed by three or more tilde `~`, then followed by optional space  
and tabs and a newline. The code block spans until an identical line  
is found, not counting whitespace after the marker.

If the marker is indented by 1 to 3 spaces, the corresponding number  
of space is removed from the start of each line in the code block.  
This means that, if you wish, you may indent the code block a little  
to make it stand out more.

So basically it looks like this:

     To install a package, you can now use this:

     ~~~
     pear install michelf/package
     ~~~

     where package is the name of the package to install from this
     channel.

But since I didn't require a newline neither before nor after the  
code block, you can write it in a more compact way if you prefer:

     To install a package, you can now use this:
     ~~~
     pear install michelf/package
     ~~~
     where package is the name of the package to install from this
     channel.

Using indentation, it looks like this:

     To install a package, you can now use this:
       ~~~
       pear install michelf/package
       ~~~
     where package is the name of the package to install from this
     channel.

or this:

     To install a package, you can now use this:

       ~~~
       pear install michelf/package
       ~~~

     where package is the name of the package to install from this
     channel.

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?



> If I recall, in the previous thread there were two suggestions for

> solving the problem:

>

> 1.  adding delimited unindented code blocks, along the lines of

>     what you suggested above

>

> 2.  adopting the convention that two blank lines end a list (or

>     footnote or other block element in which indentation is used

>     to indicate continuation blocks).

>

> Do people have views about the comparative advantages and  

> disadvantages

> of these approaches?

>

> An advantage of (2) is that it provides a clean way to have two

> consecutive lists of the same type.


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.

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.



> An advantage of (1) is that it allows you to cut and paste code  

> without

> adding or removing indentation. It's also something that you see quite

> often in emails, and thus goes along with markdown's general  

> philosophy

> of using established conventions.


I will add that it makes possible white lines at the start or at the  
end of a code block, as well as multiple consecutive code blocks.



> However, I prefer ======== to ~~~~~~~~~~ for this purpose, because

> ====== is vertically centered on the line and gives you a more

> symmetrical look.


That depends on the font. For instance, tildes are vertically  
centered as I look at them in Monaco 13 in my email client. I agree  
it's a drawback however: many fonts display tildes above the middle  
line.



> As long as a blank line is required before the string of ======='s,

> there is no danger of confusing this with a Setext-style header.


For a parser aware of the new syntax, you're right. To a regular  
Markdown parser, it'll look like a paragraph followed by a header. To  
a regular Markdown user, it'll just look odd, especially if you add  
more lines and blank lines in your code block. For instance:

     =========
     foreach ($this->document_gamut as $method => $priority) {
         $text = $this->$method($text);
     }

     return $text;
     =========

I share your concern about tilde being not always vertically  
centered, but I still think it's better -- and less confusing -- to  
use something clearly different from other Markdown constructs.


Michel Fortin
michel.fortin at michelf.com
http://michelf.com/