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

[Seumas Mac Uilleachan]

I wholeheartedly agree. The main attractions of Markdown to me are:

1.  It is easy to read

    I use Markdown for personal info and stuff, then convert and read in 
a browser. But for me it is ALSO important to be able to easily read the 
original source. That is where Markdown excels over the other 
text-to-HTML conversion tools. I have tried other methods (generally 
wiki's) but find their markups generally nonintuitive or hard to read in 
source (especially the use of apostrophe '''''ugh''''')

2.  It is fault-tolerant

    The rules are loose enough that if I don't use the exact number of 
spaces I still get what I intended rather than what I actually entered. 
Or if I add a space or two in front of the bullets (often by cutting and 
pasting) it still works. Actually that is a good point too - cutting and 
pasting with Markdown requires less after-the-fact cleanup than the 
other systems I've tried.

We need to keep these point in mind when discussing the future of 
Markdown. I do use PHP Markdown Extra, but ONLY for the tables feature 
('cause HTML tables are tedious and I'm lazy). Other than that I stick 
pretty much to the original and just use HTML if something extra is needed.

Less is more when it comes to Markdown's syntax. Markdown is intended to 
make text writing easier and more legible than is currently possible 
with HTML. The least (and most flexible) syntax rules required for that 
should be the goal.

Waylan Limberg wrote:

> 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

>>

>>     

>

>

>

>