on the philosophical aspects of a specification

[Michel Fortin]

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


> 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
http://michelf.com/