Markdown Discuss - Feb 2008 - evolving the spec (was: forking Markdown.pl?)

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

Le 2008-02-29 ? 3:49, Yuri Takhteyev a ?crit :
>> 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 also think the Markdown Extra spec should be usable as a spec for  
how to parse plain Markdown. But I'm not conviced calling it "Markdown
2.0" will make the spec much more valuable. Can we even do that  
without John Gruber's blessing?
> 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.
I think the syntax needs to be defined unambiguously, not necessarily  
as a formal grammar, but certainly not with code either. My idea,  
currently, is to write a parsing procedure which is easy to read and  
implement in various ways, using a formal grammar to define various  
constructs of the syntax and plain english to link things together. I  
also intend to keep the spec implementable as an incremental parser,  
but that will require backtracking.


Michel Fortin
michel.fortin at michelf.com
http://michelf.com/

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

In article <928946aa0803011134y6054af3dq64a00834bfced75a at
mail.gmail.com>,
Joseph Lorenzo Hall <markdown-discuss at six.pairlist.net>
wrote:
>Is there any use case other than the copy and pasting example that
>gets you whitespace before a list item marker? Do people do this on
>purpose?
   I do it all the time.

   I indent text by 4 spaces, and do

     * text

   or

    1. text


   Worse yet, I do

    1. text
    2. text
    .
    .
    .
   10. text
   11. text

  A revised markdown syntax that forbade this would be slightly
  catastrophic for me.

  -david parsons

Aristotle Pagaltzis <pagaltzis at gmx.de> wrote:
>  > What about setting "value" on each "li" instead?
>
>  Equally deprecated.
The HTML spec authors have admitted that they believe this particular
change was a mistake on their behalf.

All browsers support the value attribute on <ol> <li>s, and there
are
numerous real world use-cases for allowing continuations of ordered
lists.

I for one, would like to see markdown support...

1. ordered
2. lists

that interrupt and then continue

3. like
4. this


Basic support for implied <ol type=""> attributes would also be
nice...

A. like
B. this
C. where the third item refers to list-item "A" above
   (which becomes non-sensial if the browser renders
   the list as 1. 2. 3...)

or

i. like
ii. this
iii. as well


...although I realise that over-zealous auto-detection algorithms
would cause problems with sencences/lines starting with an abbrivated
proper name like this:

A. Lincoln was an US president, and Lyndon
B. Johnson was another.


-- 
M?r