on the philosophical aspects of a specification

Michel Fortin michel.fortin at michelf.com
Mon Mar 3 07:08:38 EST 2008

Le 2008-03-03 à 0:55, Bowerbird at aol.com a écrit :

> a specification will _eventually_ be used, by someone,

> to tell the user they are doing things "wrong", won't it?

Well, that's not the specification I intend to do. All inputs are
right in Markdown; there is no such thing as "invalid" or "non-
conformant" Markdown, and that's how I intend to specify it.

> and doesn't that turn markdown's genesis upside-down?

> heck, next thing you know we'll be telling them to r.t.f.m.

The point of Markdown is that you can learn a good part of it just be
looking at example and extrapolating from that. Reading a manual isn't
a requirement, and it should stay that way. That doesn't mean there
shouldn't be a manual nonetheless; when it doesn't do what you expect,
you should have a reference to dig into, and some people like to read

> i would prefer that implementers get more sophisticated

> about teasing out the user's intent in "ambiguous" cases.

The problem is that in many cases, the author's intent is ambiguous
even for a human. Then there are cases which can only the only way to
understand what the author's intent is to actually read the text and
use the formatting in a way that makes sense.

Markdown can't do anything about these two cases, except for one
thing: be predictable by having syntax rules simple enough so that
authors understand what happens and providing an obvious way out so
that authors aren't stuck with nothing to do.

> of course, i've always been suspicious of "specifications",

> since many technoids think the job is finished once the

> spec is "all done", before one line has been programmed;

> give me _working_code_ any day of the week, thank you...

I intend to keep the specification evolving, and it obviously
shouldn't be called stable until we have actual implementations of it
proving that it works good enough. In fact, I plan to start with a
specification very close, if not identical, to what PHP Markdown Extra
does, except for the few things I'm considering bugs.

> just a remark, intended to stir thought, _not_ a debate...

> (please do reply if you must; i'll refrain from responding.)

Your concerns are valid ones, which seems to be shared by some other
people too. I wanted to debunk them. Please don't refrain from writing
the list if you have others.

Michel Fortin
michel.fortin at michelf.com

More information about the Markdown-Discuss mailing list