[kramdown-users] RFC: Lazy syntax / blank line usage

Thomas Leitner t_leitner at gmx.at
Sun Sep 5 02:52:26 EDT 2010


I have just started implementing the lazy syntax and I've come across a
problem of how to implement them.

You see if it is not allowed to use lazy syntax, basically every block
level element can follow another block level element except if they use
the same syntax (as with lists followed by a code block).

However, this breaks down once we allow the lazy syntax... Since
blockquotes and lists start with a special character at the beginning
of a line, it is possible that such a character appears at the
beginning of a line due to line wrapping. Then we have an ambiguous
situation. Let's look at the examples given in my previous email:

> PA1. First example:
>     * this is list item
>     > * this item is in a block quote  
>     more block quoting?

In the previous mail I said that this would be a list followed by a
blockquote. However, if we strictly follow the line wrapping approach
it would need to be a list with a single item (PHP Markdown, Pandoc
extended interpret it this way)...

> PA4. Fourth example:
>     > * foo
>     > > bar
>     > > baz 

And this would need to be a list with a single item inside a blockquote
(again, PHP Markdown, Pandoc extended interpret it this way).

Here are some problematic examples and how they are interpreted by
different Markdown implementations:


So what do about this? I have come to think of two choices:

1. Do it like Markdown: It allows certain block level elements directly
   after another one but not all, for example

   - paragraph followed directly by blockquote|header|hr
     results in a paragraph and a blockquote|header|hr

   - paragraph followed directly by list|codeblock
     results in just a paragraph

   And the output of a blockquote after a list or vice versa is also not
   very intuitive.

2. Require the use blank lines between all block level elements, with
   special provisions for compact lists. This would further break
   compatibility with Markdown but kramdown already breaks it. And this
   change should not affect too much documents, only such edge cases
   as mentioned above... or so I think.

   John Gruber once said in the Markdown ML:

   > So while we're fixing Setext-style headings, here are my thoughts
   > on how to make them less ambiguous. One overall problem in
   > Markdown 1.0's syntax is that it isn't clear when you need
   > blank lines to separate block-level constructs.
   > I feel strongly now that this was a mistake, and that the rules
   > should be tightened such that all (or nearly all -- there may be
   > worthwhile exceptions I haven't considered) block level
   > constructs must be both preceded and succeeded by a blank line.
   > (Or they must occur at the start or end of the document, of
   > course.)

I would personally go for option two - what do you think?

Another edge case with code blocks I would like to mention. In my
previous email I said that code blocks should probably not support line
wrapping. But why shouldn't they? If there are long lines inside a code
block they are surely wrapped as with long lines in paragraphs. Since
one should probably surround a code block with blank lines anyway, why
not allow a lazy syntax:

        Some text
    Some code block other text

This would be a code block with one long line, equivalent to this:

        Some text Some code block other text

I would like to it this way to avoid having this as special case
regarding line wrapping.

Thanks for your help!

Best regards,

More information about the kramdown-users mailing list