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

[Waylan Limberg]

Well, if its going to happen, this will probably make it happen.
Further thoughts below:

On Fri, Feb 29, 2008 at 6:04 PM, Yuri Takhteyev <qaramazov at gmail.com> wrote:

> Since Joe called for procedural suggestion, here is what I think we should do:

>

>  1. First, I think there were valid concerns about whether it would be

>  ok for us to come up with a spec and call it "Markdown 2.0".  I

>  suggest we put the question of naming aside.  Once we agree on a spec,

>  we'll ask for John's permission to call it "Markdown 2.0" or

>  Markdown-Something-Else, and in the worst case we'll call it something

>  different, like "M-Spec" or "FooBar7.0"  For now, let me refer to it

>  as the M-Spec.

>

>  2. As Thomas suggested, we should first reach some agreement as to

>  what if anything needs to change from the original Markdown or how the

>  "holes" are to be filled.  _Then_ try writing a grammar.  I suggest

>  that we do this first part in plain English (and perhaps some

>  pseudo-code), using the wiki to record the decisions and the

>  highlights of the dissenting views, and using the mailing list for the

>  actual discussion.  Let's _try_ to do it by consesus.  It might just

>  work.  If we can't agree and have to resort to voting, we can then

>  figure out how to handle that.  (We've got a voting expert among us:

>  Joe.)


Something tells me this is going to be the ugly part. As long as it
doesn't turn into something like writing html specs has become. Uhg.

>

>  3. I suggest that be start by breaking "M-Spec" into two levels.

>  Level 1 will aim to clarify the original Markdown syntax and "fix" it

>  in cases where we agree it is broken.  This may involve incorporating

>  some ideas from Markdown Extra (like emphasis_in_the_middle fix).  It

>  will try to stay true to the "spirit" of Markdown and to not add any

>  new "features."  Level 2 will add certain features, such as footnotes,

>  tables, definition lists, unindented code blocks, etc.


Excellent. Without this separation between Level1 and 2, I'd say the
spec is a really bad idea.

>

>  4. We'll agree that Level 1 is required for all "M-Spec"

>  implementation, while Level 2 is optional.  We can either ask that all

>  M-Spec implementations return literally the same HTML for Level-1 text

>  or say that the output should match apart from "irrelevant"

>  whitespace.  M-Spec implementations can choose whether to implement

>  some (or all) Level 2 features, but they should avoid implementing

>  similar-but-not quite features.  E.g., you don't have to implement

>  footnotes, but if you do, please do it as specified in Level 2 spec.

>  All implementations should also be clear as to which Level 2 features

>  are supported and which are not.  It could be as simple as giving the

>  user a check list.  All implementations that support Level 2 features

>  should have an option of turning them of.


I really like every detail of this. If any part of this gets left out
in the end, I, for one, would be disappointed.

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.

>

>  5. I suggest that for everyone's sanity we divide both levels of the

>  specs into a "macro" and "micro" part.  The first ("macro") part will

>  tell us how the text is to be chunked into headers, paragraphs, lists,

>  quotations, etc.  I think this part would be best described as an

>  algorithm for turning markdown text into a tree of "block-level"

>  nodes, where each node has certain "type" ("paragraph", "list item",

>  "quotation", "code")  The second ("micro") part will tell us what to

>  do with the text inside those nodes.  I think that this would be best

>  described as a list of substitution rules that would be run in a

>  particular order (to clarify precedence).  This also would allow us to

>  divide the work: we could have a "macro" working group and a "micro"

>  working group.


Works for me. But why not just call them "block-level" and "inline"
rather than "macro" and "micro"?

>

>  6. Once we have a reasonable draft and have worked out the main

>  disagreements, we can do another pass over the spec looking for

>  ambiguities, and once we are satisfied try to write a formal grammar.

>  If we manage, great.  If not, I think that's ok too.  A detailed and

>  agreed upon spec "in English" will already be a big step forward.

>

>

>   - 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