YAMF
September 5, 2014 at 1:32 AM by Dr. Drang
You didn’t really think I’d be able to resist writing a post on the Standard Common Markdown clusterfuck, did you? Even though Joe Rosensteel already said a lot of what I was going to say, even though I suggested on Twitter
Existential crisis averted. Also, I can blog about something else tonight.
blog.codinghorror.com/standard-markd…
— Dr. Drang (@drdrang) Sep 4 2014 6:48 PM
that I’d give it a pass, I just can’t. In the words of John Lee Hooker: it’s in me, and it’s got to come out.
I started writing in Markdown in 2004, back when John Gruber was still making changes to the Markdown.pl code and was still accepting suggestions for features and bug fixes. It was the newcomer in the plain text markup field, and I took a risk in adopting it instead of the more established forms like Setext, reStructured Text, Textile, and Pod. But, as I said in this post, I chose Markdown because
- It let me use asterisks for emphasis and strong. I’ve always hated underscores and didn’t want to be forced to use them.
- It let me use underlining for headers, which I thought was much more natural and good looking than hashmark prefixes. As it happens, I eventually changed my mind on this and now use hashmarks exclusively. That I could make this change was a happy result of Markdown’s flexibility.
- The general cleanliness of the format. The other formats tended to have more non-textual punctuation embedded in them.
- The ability to drop down into HTML when necessary. This, I’ve always thought, is Markdown’s secret weapon. It allows you to put any messy HTML you want in a document while keeping Markdown itself simple. This is why Markdown is cleaner than the other formats (it’s also why the other formats are used for in-source documentation).
Fundamentally, Markdown was tolerant and inclusive. At the risk of some ambiguity, it let you write pretty much the way you’d write a nicely formatted plain text email and turned it into HTML for you. It was both easy to write and easy to read in source form. The readability of Markdown was key. If a normal person could read your Markdown source and understand its structure, chances are Markdown.pl could, too.
The ambiguities I mentioned didn’t exist within Markdown.pl, of course. It did what it did the same way every time, as did the other Markdown implementations. But they didn’t all do exactly the same thing, especially when it came to tricky combinations of blank lines and indentation. This bothered a lot of people, most prominently John MacFarlane, who undertook a study of Markdown’s nooks and crannies to find its inconsistencies. He did this to help him write his wonderful Pandoc and PEG-Markdown programs, but I suspect he had a secondary motivation as well. A philosopher who works in logic would naturally rebel against the messiness of Markdown.
Those of us who read MacFarlane’s messages on the Markdown mailing list didn’t need Jeff Atwood to tell us who the primary author of the Standard Markdown spec was. It has MacFarlane’s fingerprints all over it. It’s impressive work, but I have to say I find much of it unnecessary in practice.
Take a look at the ambiguities shown in Section 1.2 of the spec and the lists shown in Section 5.2. Many of these constructions are inherently ambiguous, by which I mean a normal human being would have difficulty interpreting the author’s intent. In my view, Markdown was never meant for these situations, and it’s perfectly fine for different implementations to output different HTML. These inherently ambiguous constructions aren’t readable and therefore aren’t really Markdown. If they produce unpredictable output, so be it—they are garbage input.
(That said, there are some constructions that are unambiguous to any reasonable reader but can produce surprising HTML. The presence or absence of a blank line between list items is an unfortunate example. But you soon learn to deal with it.)
As I read through the spec, I was surprised to see no support for tables, footnotes, or definition lists—common extensions to the feature in Markdown.pl. At first, I thought Standard Markdown truly was just trying to clean up Markdown.pl’s messes. But then I saw the section on fenced code blocks and I realized I’d been duped. Joe Rosensteel put it best:
In the “Standard Markdown” spec, they include GitHub Flavored Markdown’s “fenced code blocks”. Oh! Well, would you look at that! It’s a feature that serves the needs of one of the “Standard Markdown” contributors. It has nothing to do with the original specification of Markdown. This isn’t solely about removing ambiguity, of course, it’s about making the Markdown someone wants in to the correct Markdown.
In other words, Standard Markdown isn’t a solidly built Core Markdown. Nor is it a Comprehensive Markdown with a bunch of helpful features that ol’ bastard Gruber refused to add. What it is is Yet Another Markdown Flavor, with a feature set tied to the needs of Meteor, Reddit, Stack Exchange, and GitHub. There’s nothing wrong with that, but it isn’t setting a Standard. It’s what everyone else does—some better, some worse. And in John MacFarlane’s case, he’s done it better at least three times.
I’ve been writing in Markdown for ten years and have used several implementations. Gruber’s 4,000-word syntax documentation has never led me astray, perhaps because I’ve paid attention to the opening paragraphs:
Markdown is intended to be as easy-to-read and easy-to-write as is feasible.
Readability, however, is emphasized above all else. A Markdown-formatted document should be publishable as-is, as plain text, without looking like it’s been marked up with tags or formatting instructions. While Markdown’s syntax has been influenced by several existing text-to-HTML filters — including Setext, atx, Textile, reStructuredText, Grutatext, and EtText — the single biggest source of inspiration for Markdown’s syntax is the format of plain text email.
I’ve almost never run into the problems that YAMF, with its 15,000-word spec, was designed to solve. And because it’s missing extensions I use every day, YAMF can’t process the blog posts and reports I’ve written over the past decade, nor will it handle what I intend to write in the future. Putting aside the politics of the situation, it just won’t work for me.
