
Why CommonMark Isn't the Solution - ariabuckles
https://ariabuckles.github.io/blog/common-markdown/
======
ChuckMcM
Ok, I had challenges with statements like this in the article:

 _All of this means that it is not possible to write a simple rule for when a
paragraph (or other block element) ends._

Except there is a very simple rule, block elements are terminated with a blank
line. The argument that changing

    
    
       line 1
       ---  < this is inserted between two blocks
       line 2
    

Really changes the 'line1' from a block element to a header element (its no
longer followed by a block line) which has not a lot to do with parsing but
more with lexical analysis. And then later the author reveals what is perhaps
their actual thesis statement _" Markdown became so popular because it was
simple and somewhat extensible."_ which I would agree with if the period had
landed three words earlier in the sentence. :-)

CM is a nice spec for a "markdown like system" :-) with many of the
ambiguities rubbed off the edges. Add tables and I'll totally switch from
multi-markdown to this more 'elucidated' specification.

I'm really surprised that so many people are hung up on Atwood et alia trying
to bring some explicitness here. I've been using Markdown(tm) derived systems
for a few years now and have felt the pain of many of their points directly.

~~~
evv
I think the explicitness is the one aspect which has been widely well-
received. We all know the pain of an inexplicit Markdown, and CM did a
fantastic job of addressing that.

Much of the frustration, at least from my eyes, is because CM attempts to
incorporate too much of the mess that Md once introduced. I understand they
did this in the interest of keeping compatibility with most "Markdown"
documents. But they had the opportunity to fix things up, and really I wish
they did.

The quintessential example here is the inclusion of HTML. By allowing html to
be mixed in, Gruber really allowed a lot of flexibility and versatility, but
that only makes sense if the content could be trusted and that it will only
ever appear on the web. Tables are a great example of reasonable html usage-
they are supported in both Md and CM. There are a lot more examples of
unreasonable HTML usage, which I'd rather not enumerate.

These days, with the proliferation of Md as a widespread content language for
public discussion across mediums, HTML doesn't belong. There are other cruft
and ambiguities that CM could have cleaned up easily. CommonMark had the
chance to improve this situation, but they went to great lengths to embrace
it. If they had considered themselves as a distinct dialect instead of "the"
standard, they may have gone a different route and written something more
modern and clear.

------
brudgers
The project is no called longer "Common Markdown". It's CommonMark [1].

From Atwood's announcement yesterday:

 _Edit: after a long and thoughtful email from John Gruber – which is greatly
appreciated – he indicated that no form of the word "Markdown" is acceptable
to him in this case. We are now using the name CommonMark._ [2]

Anyway, the reason the specification is complicated is because creating a
regular grammar from a rich irregular grammar requires a lot of work. Things
like reading ahead to distinguish between:

    
    
         paragraph 1
         %%%
         paragraph 2
    

and

    
    
         paragraph 1
         ---
         paragraph 2
    

The goal is to help companies like StackExchange and Github get out of the
markup language business by solving a set problems that aren't really on the
radar of individual bloggers using markdown, but that very much impact
websites at scale.

The article is a case in point - StackOverflow can't be efficient if it's
pushing an entire parser into the browser. It needs to degrade gracefully when
javascript is off.

In general, the world will be better off when the canonical markdown
documentation is not written with a tiny font on a grey background. Perhaps
we'll even see markdown [or CommonMark] begin replacing RTF and BBCode more
places.

[1]: [http://commonmark.org/](http://commonmark.org/)

[2]: [http://blog.codinghorror.com/standard-markdown-is-now-
common...](http://blog.codinghorror.com/standard-markdown-is-now-common-
markdown/)

~~~
chasing
Well, I guess now we've learned what it takes to get John Gruber to respond to
an e-mail.

~~~
alexnking
"Are the Yankees the best team in baseball?

We used to think so."

[http://commonmark.org](http://commonmark.org)

------
Thrymr
There is another evaluation of Common/Standard Markdown by the author of vfmd:
[http://roopc.net/posts/2014/eval-stmd](http://roopc.net/posts/2014/eval-stmd)

~~~
spankalee
That's a very good writeup, and his points are important for anyone to
consider before proclaiming support for the CommonMarkdown effort. I wish
there were way more discussions like this of the technical merits of
CommonMarkdown than the name.

While I'm very supportive of some kind of sane Markdown specification, it's
pretty disappointing that those with the biggest audience to push a
specification have created such an apparently poor one. And after 2 years!
Spec-by-examples, especially for an inherently ambiguous and forgiving syntax
like Markdown, should be known to be a bad idea.

------
syntern
I've tried to use Markdown for very simple formatting (to have two consecutive
paragraph have a wrapper style, e.g. to have a note style) - and failed. I've
tried various parsers, wrote my code hacks (also called: extensions), regex
replacers whatnot, just to conclude, that even if I am able to do that, the
live preview will suck.

Fast-forward today: I've started to use Asciidoc with the Atom editor and its
Asciidoc live preview. I'm using asciidoctor to generate docbook, and xslt to
get it formatted in the way I want. I feel productive to write the content,
and I can control every aspect of the output, in the very specific way I see
fit.

A simple blog post with a bunch of paragraphs and bold styles may not be worth
it, but anything more complex will favor asciidoc.

~~~
ivanr
Out of curiosity, why not write DocBook directly using a WYSIWYM editor -- for
example OxygenXML? Edit: I don't think it's worth using for blog posts and
such, but for anything that you plan to publish -- papers and books -- it
works very well.

~~~
syntern
For me it is easier to version-control and review changes in asciidoc than in
docbook.

~~~
ivanr
Do you review your own changes, or someone else's? Asking because the former
is unusual, but the latter works much better with OxygenXML's built-in change
tracking. It's fantastic for working with editors (in combination with, say,
Subversion).

~~~
syntern
Both. Also, I have sometimes a doc edited on google docs, then copied over to
local file and formatted in asciidoc. After that we put it back to the google
doc in asciidoc markup, and subsequent comparison and merging becomes a way
lot simpler.

------
scrollaway
Can't people use "Isn't perfect" instead of "Isn't the solution"? Or does that
highlight too much why the title of this article is stupid?

Not that it's not a good article - it is. But damn do I hate when people go
about yelling "This isn't the solution! You're doing it wrong!". Urgh.

~~~
dangerlibrary
I would agree with you if the article hadn't ended with a link to what the
author considers the solution.

------
Someone1234
Good article. I also agree with his approach of taking Common Markdown and
breaking it up into a core, and then extensions. That means parsers can be
standards compliant while working in environments and situations where certain
features don't make sense (e.g. something that takes in markdown and outputs
to an programmable LED sign, won't need URLs, HTML, and so on just
formatting).

I wish Hacker News had markdown.

Off topic question: Why has rich text fallen so far out of fashion? I really
like Markdown, but why is it that Markdown is now so popular and richtext
boxes that can display a realtime preview (e.g. bolding text, italics, etc)
aren't. What is it markdown offers over that? Is it just transportability?

~~~
josephg
Interesting question.

One nice feature is that markdown makes text annotations explicit and obvious.
There's no hidden styling. Empty lines don't have a font size. Its obvious
when a bolded region doesn't bold the spaces between words. In the Rich
Hickey[1] sense, markdown is much simpler than rich text editing because all
you have to worry about is the semantics of your text (this is a heading) and
not how its actually styled.

Weirdly, its kind of a huge throwback to LaTeX. Thinking of markdown as a
"modern, simplified LaTeX for the web" seriously hits the mark.

[1] [http://www.infoq.com/presentations/Simple-Made-
Easy](http://www.infoq.com/presentations/Simple-Made-Easy)

~~~
shurcooL
Agreed. I would summarize that as: it doesn't have _hidden state_. Which is
nice.

------
coldcode
So why did the common folks not get together with the vdmd folk(s)?

~~~
sheetjs
According to the vfmd spec history[1] the first version appeared in july 2013.
According to the other project[2], they started "about two years" ago. It
would be impossible for the former to discover the latter, given that the work
was behind closed doors. The people in the latter group probably did not
bother to look at alternatives while they were pursuing their own solution.

[1] [https://github.com/vfmd/vfmd-spec/commits/gh-
pages?page=7](https://github.com/vfmd/vfmd-spec/commits/gh-pages?page=7) [2]
[http://blog.codinghorror.com/standard-markdown-is-now-
common...](http://blog.codinghorror.com/standard-markdown-is-now-common-
markdown/)

------
talles
Is it "Common Markdown" or "Standard Markdown"?

~~~
talles
Nevermind: [http://blog.codinghorror.com/standard-markdown-is-now-
common...](http://blog.codinghorror.com/standard-markdown-is-now-common-
markdown/)

~~~
x0x0
wow, gruber is more of an ass than I thought. His modus operandi is blow off
private communications and have a public tantrum

    
    
       We've been working on the Standard Markdown project for about two years now. 
       As we got closer to being ready for public feedback, we emailed John Gruber, 
       the original creator of Markdown, two weeks ago (On August 19th, to be 
       precise) with a link to the Standard Markdown spec, asking him for his 
       feedback. Since John MacFarlane was the primary author of most of the work, 
       we suggested that he be the one to reach out.
       
       We then waited two weeks for a response.
    

[...]

and again:

    
    
       Starting with the name. In his email John graciously indicated that he would 
       "probably" approve a name like "Strict Markdown" or "Pedantic Markdown". 
       Given the very public earlier miscommunication about naming, that 
       consideration is appreciated.
       
       We replied with the following suggestions:
       
       Compatible Markdown
       Regular Markdown
       Community Markdown
       Common Markdown
       Uniform Markdown
       Vanilla Markdown
       We haven't heard back after replying last night, and I'm not sure we ever 
       will,

~~~
mikestew
Gruber's often an insufferable Apple mouthpiece who thinks way too highly of
himself, and has been for the last ten years that I've paid attention. That
doesn't keep me from reading everything in the RSS feed, though. Hell, I've
even spent considerable sums of money to advertise on his podcast. But this
exchange doesn't surprise me.

What _does_ surprise me is how Marco was happy to be one of Gruber's flying
monkeys on Twitter. Maybe Marco has an interest in the fight that is unknown
to me, dunno.

Anyway, I don't care one way or the other. If forced to care, I'd even side
with Gruber on the principles. But don't be shocked that some parties handled
this in a less than graceful manner.

~~~
deong
No, he's just very particular
([https://www.google.com/?gws_rd=ssl#q=john+gruber+%22moto+270...](https://www.google.com/?gws_rd=ssl#q=john+gruber+%22moto+270%22))
about people respecting other people's names for their work.

Stay tuned though. My sources tell me he's going do a really clever thing with
a dollar sign in the middle of "Microsoft" next week.

~~~
rtpg
what's the story behind "Moto 270"?

~~~
deong
Motorola makes a watch, the Moto 360, the name being an obvious hat tip to
being round. There's a bit of black plastic along the bottom though, so the
actual screen takes up a bit less than the full area of the circle. And Gruber
certainly seems to think he's very clever in consistently calling it the "Moto
270".

Maybe he has a good argument that they can't call their thing Markdown, but
certainly if he starts whinging that they aren't properly capitalizing his
trademark, then I think he's behaving in a hypocritical fashion when he quite
clearly takes other people's trademarks so casually.

Also, I think it's just as childish as seeing Micro$oft back in the day, but I
guess that's a matter of taste.

~~~
rtpg
Wow, I really don't understand how this man has such a following. Everything I
hear about him is so petty (not to mention that everything about his blog is
written to somehow conclude that Apple is some sort of god, even when the
source is completely the opposite)

------
peterkelly
If you're writing a parser - or defining a "standard" \- without a formal
grammar, you're doing it wrong.

~~~
zzleeper
Are they working towards building a formal grammar? I thought so from
yesterday's discussion, but I don't know how hard would be to get a sane BNF
for markdown

~~~
chrisseaton
They don't have to use BNF - they can use any reasonable grammar notation for
the spec, and let implementors work out what tech to use.

------
ahoge
[Off topic]

    
    
      <script>
      var CONTENT = '' +
      "Why Common Markdown isn't the Solution\n" + 
      ...
    

That's probably the most roundabout way to put an article on the web. You are
inlining Markdown in an HTML document. Then the browser has to parse and
execute 4.5 MB (!) of JavaScript and then it can finally turn that Markdown
string into HTML.

HTML documents are a pretty good choice for, y'know, HTML.

Well, if your goal was to increase the page weight from 10kB to 2.2Mb, you
surely succeeded.

~~~
ariabuckles
Oh, I'm quite aware :). It's an effort of extreme dogfooding of
[https://github.com/khan/perseus](https://github.com/khan/perseus). This post
doesn't use anything interesting, but if I wanted to post about some of the
interactive math content we're doing there, I could actually embed it. It is
also useful to learn how annoying it is to embed (answer: much more annoying
than I'd like).

~~~
cbhl
Say hi to spicyj for us!

~~~
spicyj
Hi.

------
pbreit
REST:SOAP::RSS:Atom::Markdown:CommonMarkdown

I suspect this pattern will continue into perpetuity because such a large
audience will never come to grips with the fact that "better" isn't always
better.

~~~
aboodman
Do people use RSS anymore? All the stuff I use is Atom.

~~~
aboodman
Answering my own question:
[http://en.wikipedia.org/wiki/Atom_(standard)#Barriers_to_ado...](http://en.wikipedia.org/wiki/Atom_\(standard\)#Barriers_to_adoption)

Sad.

