Universal syntax for Markdown

[Fletcher T. Penney]

I think that for any movement towards a "unification" of the Markdown variants to have a chance of success, the first step is to agree on a core set of principles.

For example, one of my core principles for MultiMarkdown is taken from Gruber:


> The overriding design goal for Markdown’s formatting syntax is to make it as readable as possible. The idea is that 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.


Intelligent people can (and do...) quibble about whether I have overstepped this design with some of the features I have added, or whether they could be implemented in a less obtrusive way.  There's always a tradeoff between functionality, versatility, readability, and ease of composing.


Some of the suggestions being thrown around in this discussion, IMHO, are far afield of this principle, to the point where I would not consider implementing them in MMD.  The longer this discussion goes on, the more I find myself reinforced in my belief that MMD represents the compromise point that is best for *me.*  I find myself less interested in the effort it would take to complete this overhaul, if I were to believe that the end result would be a product less suitable to my needs than the current implementation.


Without a clear set of guiding principles, I fear that any effort to create a successor to Markdown is going to end in "design by committee."  The original Markdown syntax seems to have had a clear purpose and vision, which is why it resonates so well with so many.  Sadly, it has been abandoned which means two things:

1) known bugs/edge cases/what have you are not being fixed

2) new features are not being added


#1 is inarguably a problem.

#2 is only a problem depending on your perspective.  The first feature I added was to support the very footnote syntax that Gruber himself had proposed, but never implemented.  It grew from there, but I haven't really added new syntax features to MMD in quite a while, and it becomes increasingly unlikely that new features will be added as time goes on.  I feel that Markdown was incomplete, but I recognize that not everyone feels that way and it is perfectly suitable for some people.



So, as the creator of MultiMarkdown, which from my totally biased perspectives seems to be one of the more popular descendants of Markdown, particularly among those still being actively developed, here is my plan/proposal:


1) I will support efforts to standardize the edge cases of the Markdown syntax to minimize discrepancies between flavors.  My personal vote would be that John MacFarlane's peg-markdown is a good place to start --- it allows a mechanism for clearly defining a syntax, and that definition can easily be pulled directly into Markdown based tools for transformation or syntax highlighting.  Other tools would not necessarily have to be built around a PEG definition, but it would represent the official rulebook on what should happen.  Regardless of the tool chosen, I think such a formal definition would be a "good thing."

2) I will support efforts to create a universal test suite to help measure compliance with such a standard syntax definition.  I have made my own additions to the test suite that John MacFarlane used in peg-markdown, which was originally created by John Gruber.  The actual tool itself doesn't matter to me, but I do think the tests should be restructured so that there are more test files that each test a specific thing. 

3) I will support efforts to standardize the syntax of extensions and/or output formatting, *where it makes sense*.  I fully admit that "where it makes sense" is a totally subjective statement, and completely at my whim.  And this is where a clear set of guiding principles would make it more likely that MultiMarkdown would merge towards the consensus opinion, rather than staying put.  If the consensus among others was that they wanted the most flexible, powerful features, at the expense of a high markup to content ratio, then I would politely decline to implement those features as it clashes with my vision for MultiMarkdown.  I agree with others who have pointed out that agreeing on extensions is a separate, and likely more contentious, problem than fixing the known lingering issues with Markdown itself, and should probably be pursued as a separate, but possibly parallel, project.

4) I am busy enough with my own projects that I am not willing to take this on as a lead (not that anyone was asking me too...)  I am happy to help if there is a project started with a purpose I can agree with.  I would be interested in assuring that MultiMarkdown is compliant with the agreed upon standard.  But I, like others on this list, don't have the time to manage this as new project.

I'm interested in further thoughts, feedback, discussion...


F-

--  
Fletcher T. Penney
fletcher at fletcherpenney.net