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

[Waylan Limberg]

With all this discussion about evolving the spec, I think we want to
remember the philosophy behind Markdown to begin with. Go re-read the
Overview[1] of the syntax rules.

[1]: http://daringfireball.net/projects/markdown/syntax#overview

As the very first line says:


> Markdown is intended to be as easy-to-read and easy-to-write as is feasible.


Personally, some of the "holes" in the current syntax rules are
actually the "features" that makes this statement true. As
implementors, we want a strict spec because it's easier to implement,
but that does not always result in easier to read and/or write.

Take the discussion a short time ago on this list regarding whitespace
allowed at the start of a list item. A quick read of the rules would
indicate the the `*` or number should be the first item on that line.
In practice, markdown.pl allows up to 3 spaces at the start of a list
item. While J.G. agreed (IIRC) that that probably is a bug that should
be fixed, we learned through the course of that conversation that a
number of people actually are relying on that "bug" as a "feature",
and in fact, if the "bug" was "fixed", their documents would break.
Admittedly, why those three spaces were allowed to begin with is
beyond me, but when we consider the philosophy behind Markdown, we
realize that it is *easy* for a writer to inadvertently add a space to
the beginning of a line of text, but *hard* for that same writer (or
future editor) to find that space to remove it later. Therefore, as
crazy as is sounds, this "bug" is a "feature" when the philosophy is
taken into consideration. My guess is that this is also why J.G.
"doesn't give a rip" about a spec. A spec doesn't fit his
understanding of the philosophy behind Markdown (which he wrote).

Now, before you all write me off as insane, this is actually why I
think Markdown 2.0 is a good idea. By moving to 2.0, we don't have to
worry about backward compatibility (Markdown 2.0 should not allow
those 3 spaces). There have been various situations (some edge cases,
some not) that are not addressed in the current rules, and AFAIK those
rules have never been updated to address them. A new set of rules
would open the doors for all kinds of possibilities. However, in
writing those rules, I think we need to keep that philosophy at the
**forefront**.

For example, many people will propose various additional syntax to
accomplish different things. In general I would be opposed to nearly
every one when considering this excerpt from the current rules:


> Markdown is not a replacement for HTML, or even close to it. Its syntax is

> very small, corresponding only to a very small subset of HTML tags. The

> idea is not to create a syntax that makes it easier to insert HTML tags.

> In my opinion, HTML tags are already easy to insert. The idea for

> Markdown is to make it easy to read, write, and edit prose.


That's not to say that there are no valid arguments to add additional
syntax, but the arguments for those new rules would need to be very
convincing. After all, that's what attracted me to Markdown in the
first place. I hate editing HTML. Don't get me wrong, I know my way
around an html document, but even standards compliant, well structured
html can start to look like tag-soup the more you stare at it. On the
other hand, I can send a Markdown document to someone that has never
seen html and they **should** be able to read and understand most, if
not all, of the "markup" immediately. Lets keep it that way!

If you notice, I never suggest that Markdown 2.0 should be a "spec",
but rather an updated set of syntax *rules*. I've already explained my
reasons above, but just wanted to make sure that's clear. I suspect
that is also what Micheal Fortin is trying to say in his response to
Yuri's suggestion of a Markdown 2.0 spec. Personally, I believe that
if a spec is created (with all the strictness that that entails), then
we will have moved to far from the philosophy behind Markdown and what
we have will no longer be Markdown but some derivative that subscribes
to a different philosophy. That's not something I'm interested in.

On Fri, Feb 29, 2008 at 3:49 AM, Yuri Takhteyev <qaramazov at gmail.com> wrote:

> >  Anyway, a spec for Markdown Extra would contain a spec for Markdown as

>  >  well, wouldn't it?

>

>  I think the whole enterprise would be a lot more valuable, if we

>  produce a combined spec, which would be self-contained, and call it

>  Markdown 2.0.

>

>  I don't think we necessarily need a formal grammar.  What we need is

>  to create a document, starting with "Markdown Syntax" perhaps, throw a

>  bunch of questions at it, settle on the answers, incorporate them into

>  a spec.  Perhaps we can use the wiki at http://markdown.infogami.com/

>  for this.

>

>  (BTW, I just cleaned up the wiki removing links to unrelated sites and

>  reorganizing the rest into what seemed like a more coherent set of

>  categories.)

>

>  - yuri

>

>  --

>  http://sputnik.freewisdom.org/

>  _______________________________________________

>  Markdown-Discuss mailing list

>  Markdown-Discuss at six.pairlist.net

>  http://six.pairlist.net/mailman/listinfo/markdown-discuss

>




-- 
----
Waylan Limberg
waylan at gmail.com