evolving the spec (was: forking Markdown.pl?)

Yuri Takhteyev qaramazov at gmail.com
Sat Mar 1 14:42:50 EST 2008

I think many of Michel's points are quite reasonable. Given that we
agree on many parts, how about we start off with those things we agree
on and deal with other issues later. Specifically, I suggest that we
start with hammering out the "macro" part of "Level 1" of the spec.
I.e., let's not worry about all the inline markup for now (unless it
turns out to be relevant to macro parsing), and let's put aside all
additional features. Let's first unambiguously specify how markdown
text ought to be parsed into paragraphs, quotes, lists, etc.

Michel, do you want to do a first draft and circulate it?

> My solution to this problem was to call it the Markdown Extra spec.

> What do you think?

Sure, assuming that JG will give us blessing for calling this
"Markdown." Though, this also creates a bit of confusion between the
orginal "Markdown Extra" as implemented in PHP Markdown and the new
Markdown Extra defined by the spec.

> I don't think that's a good process. My idea for writing a Markdown

> Extra spec was to write something as a draft, call for comments,

> improve things, call for new comments, and so on until we have

> something stable enough (a few months later).

Ok, but we should start with core markdown, I think, to have a stable

> I think the HTML spec is going on well, thanks to an editor who can

> make decisions. Voting on an issue-to-issue basis isn't something I'd

> like to try. The problem being that once something has been elected in

> or out of the spec, it's problematic and conter-productive to ask

> everyone to vote again on that decision some time later because

I didn't suggest voting. I said let's try to do it by consensus, and
if this doesn't work out then we'll figure out what to do, maybe some
kind of voting.

> Beside, it's a better idea in my opinion to make a decision

> considering the technical merit of an argument rather than a

> popularity contest.

Well sure, but at the end someone will have to make that decision.
Hopefully after discussing the technical merits we'll reach general
agreement. But if we don't, someone will have to make a call, in
which case we'll have to decide how to do that. But as I said, let's
not worry about this for now.

> I disagree with this statement: having a spec with no separation

> between the two is better than no spec at all since one could take the

> given spec, remove some features, and get a good specification for how

> to parse plain Markdown. Most of the work would already have been done.

Well, it's either all required, some required and some optional or all
optional. I think making all features "required" will be asking too
much of the implementors. Making all of them be "optional" might
undermine compatibility even further. Which is why I think there
should be a "required" part and an "optional" part.

> I wonder where you would put PHP Markdown's no-markup mode (ignoring

> HTML) into this. Is this a level 2 feature?

I would treat it as "Level 2". It's a great feature, but it's a new
feature. I would rather leave Level 1 as a clarified and fixed spec
for the original markdown.

> That's a good idea in general, but I'm not sure it should be

> explicitly forbidden in the spec. If the spec defines something and

> you decide to do it differently, then you're obviously not following

> the spec, and probably for a reason.

Not forbidden, just frowned upon.

> But anyway, I'd rather begin by defining something that works, and

> leave conformance requirements for later.


> Again, I'm not keen to enter conformance requirement before having a

> working spec. But while I agree with you sentiment that implementors

> should make an effort in that direction (as I'm doing by maintaining

> PHP Markdown and PHP Markdown Extra side by side), I don't think it's

> fair for implementors to require them to implement that kind of

> customizability. Keep in mind that having various modes makes a

> program harder to test, more bug-prone, and may prevent some

> optimizations.

Let's make it "recommended". We "recommend" that implementations that
add Level 2 features give the user a simple way to turn them off.

> > Although I would like to add one thing, not only should the various

> > implementations be able to turn Level2 on or off, is should be

> > preferred (or maybe required?? thought anyone?) that each Level2

> > feature can be turned on or off individually. For example, assuming

> > wikilinks become a Level2 feature, I dislike them (yes I know, I wrote

> > the wikilink extension for python-markdown), so I don't want them at

> > all even if I need footnotes.

I think that's too much to ask. It should be good enough to recommend
a single switching that activates or desactivates L2 features. Any
further customizability should be up to the implementation.

> Two separate groups working on block-level and inline-level syntaxes

> in parallel would be like having two people each engraving a different

> side of a coin at the same time: there are too much interactions

> between the two for them to be defined separately, and I don't think

> the spec is going to be big enough to justify this anyway.

I don't agree, but let's not fight over this and do them sequentially instead.

> > Works for me. But why not just call them "block-level" and "inline"

> > rather than "macro" and "micro"?


- yuri


More information about the Markdown-Discuss mailing list