Flat code block syntax

[Paul M Jones]

On 04 Dec 2007, at 16:29, Thomas Nichols wrote:


> I've been using the ~~~ syntax for marking code blocks for a few  

> weeks,

> and it's certainly an improvement over the existing four-space indent.

> However, it can be difficult to see at a glance where one code block

> begins and another ends, as in the following example:

>

> some normal text

>

> ~~~~

>

> some code

>

> ~~~~

>

> some more code... no, wait...

>

> ~~~~

>

> now *this* is code

>

> ~~~~

>

> and this ... errrr ...

>

> ~~~~

>

> You get the idea. This mostly becomes a problem when writing technical

> docs with frequent chunks of embedded code, and the solution would

> appear to be to have different markup for begin-block and end-block.

> This is the approach that the Trac wiki syntax takes, using

>

> {{{

> chunk of code here

> }}}

>

> Is there any enthusiasm are doing something similar for the proposed

> Markdown extension syntax? Or will this cause conflicts (for example,

> with Maruku's metadata syntax, or maybe with Pandoc)? I'm not too

> concerned about the specific characters selected; perhaps

>

> {~~~~

> code

> ~~~~}

>

> or

>

> <~~~~

> code

> ~~~~>

>

> might cause fewer conflicts but remain easy to read.

>

> Does anyone else feel that separate begin-block and end-block markers

> would, in this rather special case where it is expected that the  

> content

> will be output verbatim, be an improvement?


A specialized extension to Markdown that I've added in the  
Solar_Markdown implementation looks like this:

{{code:
     code
     goes
     here
}}

Having separate open/close markers has been helpful, esp. when  
combined with the fact that we retain the indenting -- it sets off  
nicely from the rest of the document.  In addition, we have the  
ability to define what kind of code is represented as part of the  
opening marker ...

{{code: php
     ...
}}

{{code: sql
     ...
}}

{{code: bash
     ...
}}

... and apply the correct code-colorization (if desired) when rendering.

Hope this is useful feedback.


--

Paul M. Jones  <http://paul-m-jones.com>

Solar: Simple Object Library and Application Repository
for PHP5.  <http://solarphp.com>

Join the Solar community wiki!  <http://solarphp.org>

Savant: The simple, elegant, and powerful solution for
templates in PHP.  <http://phpsavant.com>