Sunday, August 26, 2012


People sure hate the pointy brackets.  I've been writing markup since version 2 of  the Text Encoding Initiative Guidelines in SGML in the 1980s, and as easy as modern tools like oXygen make it today, even I'm not crazy about it.  Over the past year or so, I've looked at every "markdown" alternative to markup that I could find:  to name a few, textile, markdown, multimarkdown, reStructuredText, and more wiki languages than I can list.

All of them seem to have a similar history:  somebody wanted to have a quicker and easier way to express HTML, cooked up a tool to convert some simple "markdown" conventions to HTML, and realized, "Hey, this is useful!"  As a result, all of the markdown languages share two main drawbacks.  The first is that they generally express only the semantics of HTML, or a subset of HTML.  That eliminates their application to any writing or editing that requires richer semantics such as an XML language could supply, but more fundamentally, the markdown languages suffer from a long-recognized limitation:  they're not specified.   It should be obvious that "Whatever my converter tool handles" is NOT a specification, but that's the state of most of the markdown schemes.  (See these comments from more than a decade ago about reStructuredText!)

For those cases where I really just want a quick and easy way to bang out HTML-like content, John Grueber's markdown seems to offer the best compromise.  First, if you really need some particular piece of HTML beyond what markdown offers, you can just embed it in your text (although at the price of reintroducing some pointy brackets).  But what really persuades me is the pegdown processor.
Pegdown uses parboiled's "parsing expression grammars" (PEGs) so it comes closer to a separately specified definition of the language than a code library full of regular expressions emitting some kind of converted text.  pegdown will give you an abstract parse tree for your markdown content, which makes me feel much more confident using markdown down from code I write.

Add to that the ever growing number of editors and other tools that support markdown in all kinds of contents, and I'm converted.  So was the text of this post — from markdown to html.