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

[Yuri Takhteyev]

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

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.

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.

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.

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/