[kramdown-users] Bug in list parsing

Shawn Van Ittersum svicalifornia at gmail.com
Thu Aug 19 16:43:30 EDT 2010


Hi Thomas,

Thanks for your reply.

Gmail sends messages with two MIME parts: one text/plain, and one HTML.  When you copied my list, I think you may have been looking at the HTML part, instead of the text/plain part.  The text/plain part is usually wrapped to less than 78 characters per line, according to RFC 2822:

> There are two limits that this standard places on the number of characters in a line. Each line of characters MUST be no more than 998 characters, and SHOULD be no more than 78 characters, excluding the CRLF.

For more info, see: http://mailformat.dan.info/body/linelength.html

I want for my users to be able to send Markdown-format messages by email to an automated system that reads the Markdown and renders HTML.  However, if the mail transport systems wrap the Markdown text, following RFC 2822, then kramdown does not parse it correctly.  So the problem with the indentation, in this case, is that it is outside my control and my users' control, because the mail system is wrapping the lines.

John Gruber's syntax for Markdown allows this kind of wrapping.  kramdown does not.  Even if my users are careful about indenting paragraphs as kramdown prescribes, they must also wrap their text to less than 78 characters per line to prevent the mail system from doing it for them and messing up the indentation.  These users should not have to worry about things like this, because Markdown says that lazy indentation is okay, and kramdown claimed to be a superset of Markdown.

If we make a rule that blocks are separated by white-space lines (with the exceptions that I've already explained), then kramdown could be made to handle both lazy indentation and email-wrapping.  And I believe it would make the kramdown syntax much, much simpler to parse and to explain.

It will be much easier to explain to my users that paragraphs, lists, and tables should be separated by blank lines, than to tell them that they need a specialized text editor (Notepad won't cut it) to count characters and wrap lines.  No text editor, even Textmate, will wrap to kramdown's specifications out-of-the-box.  They'd have to wrap one line at a time: indent, wrap, indent, wrap, etc.  This should not be a requirement, because kramdown can and should allow lazy indentation as Markdown does, by enforcing blank lines between blocks.

Thanks,
Shawn

On Thu, 19 Aug 2010 20:45:35 +0200, Thomas Leitner wrote:
>> In its current state, kramdown is not what Markdown should have been,
>> unless you believe that kramdown should only be used by engineers.
>> Markdown was designed to make document markup more accessible to the
>> common man.  kramdown, as evidenced by its many obtuse rules (just
>> read the kramdown syntax page) has become anything but simple.  It
>> has lost its simplicity and flexibility, imposing a rigid structure
>> of precise indentation, taking it further and further away from the
>> common man.  This is clearly not in the spirit of Markdown (see the
>> Markdown philosophy page).
> 
> I consider having a complete syntax documentation a plus because you
> can read it and know what output you can expect. Contrast that with the
> documentation of Markdown...
> 
> However, you are right that there may be some rules that only exist
> because they simplify parsing or they allow much more fine grained
> control. The syntax and its documentation grew with the new features
> and both should probably be revised before the 1.0 release. Help with
> that would be very appreciated!
> 
>> My users -- regular people, not computer experts -- won't understand
>> why text wrapping by email clients makes a difference to their
>> messages.  They will not follow kramdown's precise instructions for
>> indentation.  They won't bother to learn other workarounds.  Instead,
>> they will say that the software doesn't work, or it's too hard, and
>> in any case, they won't use it.
> 
> Text wrapping aside, what is the problem regarding indentation?
> 
>> I don't believe it is Thomas's intention to abandon such core
>> principles of Markdown and make it difficult to use by the common
>> man.  It appears that this has happened by accident, and that there
>> is still a chance to simplify kramdown and make it easier for end
>> users.
> 
> I'm all for simplifying but I don't want to loose advanced functionality
> in the process. So if we come up with a different syntax for something
> that seems to be too difficult to use by the common man, I'm willing to
> implement it.
> 
>> The parsing behavior I've described is completely predictable.  The
>> syntax is much simpler for users whose text editors, email clients,
>> or web browsers are wrapping their text without their knowledge.  So
>> again I ask, what is the problem with separating blocks by white
>> space, and then supporting lazy indentation within blocks?
> 
> There is nothing wrong with separating block level elements by blank
> lines, you can do that already - but it is not enforced.
> 
> Lazy indentation is another beast that we can tackle if it is really
> needed. I will write something up based on your previous email (and
> probably after combing through the Markdown ML archives) and start a new
> thread where we can discuss this further. However, I really think that
> it is not that easy to get it right...
> 
> -- Thomas
> _______________________________________________
> kramdown-users mailing list
> kramdown-users at rubyforge.org
> http://rubyforge.org/mailman/listinfo/kramdown-users


More information about the kramdown-users mailing list