Markdown Discuss - Mar 2008 - on the philosophical aspects of a specification

a specification will _eventually_ be used, by someone,
to tell the user they are doing things "wrong", won't 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.

i would prefer that implementers get more sophisticated
about teasing out the user's intent in "ambiguous" cases.

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

just a remark, intended to stir thought, _not_ a debate...
(please do reply if you must; i'll refrain from responding.)

-bowerbird



**************
Ideas to please picky eaters. Watch video on AOL Living.
      
(http://living.aol.com/video/how-to-please-your-picky-eater/rachel-campos-duffy/
2050827?NCID=aolcmp00300000002598)
-------------- next part --------------
An HTML attachment was scrubbed...
URL:
<http://six.pairlist.net/pipermail/markdown-discuss/attachments/20080303/5b0f41fd/attachment.html>

* Bowerbird at aol.com <Bowerbird at aol.com> [2008-03-03
07:00]:
> i would prefer that implementers get more sophisticated
> about teasing out the user's intent in "ambiguous" cases.
If every implementor teases a different intent out the same
document, the user loses.

Is it possible for everyone to agree in all cases about how the
user?s intent should be teased out? Clearly it is conceivable
that enough effort could be made to write all agreements down.

And if you write down what intent should be teased out of
particular inputs, what have you created but a spec? And if the
effort has been made to agree on all possible cases, would this
spec not be unambiguous? And is it not yet obviously the case
that such a spec would not need to be inflexible about the syntax
it admits?

Why then does the fallacious argument that a spec would represent
a loss for the user continue?

Regards,
-- 
Aristotle Pagaltzis // <http://plasmasturm.org/>

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/

well, i had said i wouldn't reply on this, but i think that
this post will still manage to be productive.   i hope so...

***

aristotle said:
>    If every implementor teases a different intent 
>    out the same document, the user loses.
well, yes.   but that's pretty obvious, isn't it?

there needs to be agreement among implementers.
i would think that goes without saying.

however, implementers can reach agreement easily,
by leaving users out in the cold, brushing them off
with a "you will need to follow the spec" which seems
-- if i understand markdown's cornerstone correctly --
to be outside gruber's comfort range for his creation...

nobody benefits from _true_ ambiguity.   kill that off...

but if you cannot be clever enough to allow "corner" cases
to be resolved _however_different_users_intended_them_
-- especially if those different intentions could be _easily_
understood by a naive person viewing them in plain text --
you need to go back to the drafting table and do more work.

in other words, the same input must create the same output.

but if people express different output using _similar_ input,
then you need to work to find a way to differentiate the input,
and not simply think that you can tell one of them to change...

so before considering two things as "the same", work _hard_
to see if there's some way -- any way -- to differentiate 'em...

i mean, that's _my_ opinion, but my opinion counts much less
than those of the implementers, and far less than gruber's...

the thing is, i like the _idea_ of markdown, which should not
be surprising, since i'd been working on my own non-markup
form of markup (for project gutenberg's e-texts in particular)
before markdown was invented.   since i couldn't "write a spec"
-- as my target documents are already widely propagated --
i had to _get_clever_ to tease out the different interpretations.
not only did it lead to code that's stronger _and_ more flexible, 
but i found the challenge to be stimulating _and_ productive...

>    Why then does the fallacious argument that 
>    a spec would represent a loss for the user continue?
aren't you loading the dice by labeling it as "fallacious"?

i'm not necessarily arguing that _any_ spec would do that.
but some might...   most especially by some implementers...
and according to markdown, users can't be wrong, can they?

so far, i've agreed with every aspect of michel's take on this...

-bowerbird



**************
It's Tax Time! Get tips, forms, and advice on AOL Money & 
Finance.
      (http://money.aol.com/tax?NCID=aolprf00030000000001)
-------------- next part --------------
An HTML attachment was scrubbed...
URL:
<http://six.pairlist.net/pipermail/markdown-discuss/attachments/20080303/ca70ff92/attachment.htm>

aristotle said:
>    The reasoning I outlined in questions 
>    [I've taken the liberty to re-insert the quotation you elided] 
>    shows that the premises do not support the argument. 
your questions created a straw-man.

i agreed that the exact same input should create the same output.
it'd be ludicrous to say anything else.   that's why it's a
straw-man...

then i went on to the _real_ question, which is whether or not
_similar_ input interpretable by human beings in different ways
should be "regularized" by a spec for implementer convenience,
which i opined would seem contrary to markdown's philosophy...

>    That means, like it or not, that the argument is fallacious.
your straw-man was fallacious.   straw-men always are.

>   Users can very well be wrong according to Markdown. 
>    As John has said, if a human would have trouble figuring out 
>    what structure some piece of text is supposed to signify, 
>    the computer can be forgiven for likewise failing to infer 
>    a useful meaning.
and here we have another straw-man.   get over it.   please.

a situation where "a human would have trouble figuring out"
the interpretation is _not_ the situation that's troubling to me.
it's patently obvious that doesn't meet the spirit of markdown.

the situation that's troubling is where one set of input is clear,
while another set of similar-but-not-identical input leads to
an interpretation that is _different_ yet still _equally-clear_,
but you can't easily write routines to differentiate the two, so
you have the spec disallow one of 'em because that's an easy
"solution", even though it disenfranchises one of the users...

the question is "who is the boss?" -- the spec, or the users?

-bowerbird



**************
It's Tax Time! Get tips, forms, and advice on AOL Money & 
Finance.
      (http://money.aol.com/tax?NCID=aolprf00030000000001)
-------------- next part --------------
An HTML attachment was scrubbed...
URL:
<http://six.pairlist.net/pipermail/markdown-discuss/attachments/20080306/3fa7c4a4/attachment.htm>

joseph said:
>    On a constructive tip:? What we're trying to do is 
>    design a perspective, by specifying what markdown does now, 
>    from which implementations of markdown can 
>    consistently interpret the same input.
and, if you will allow me to offer a constructive tip to _you_,
i'd suggest that instead you look closely at the cases where
_implementations_differ_, work to divine the logic of each,
and find a way that allows users to continue to have it all...

here's a rule of thumb for you:
if you break existing documents, you're doing it wrong.

and here's the rule of thumb on allowable exceptions:
if users thank you for the spec, in spite of the fact that
it breaks some of their existing documents, because
they think the new clarity is worth it, you did well enough.

***

aristotle said:
>   Wasn't the original point that Markdown 
>    should have no concept of an invalid document? 
>    I know Michel said that was his goal for Markdown Extra, 
>    and it's pretty much the argument which which
>    Bowerbird started this thread.
well, to get the argument straight, it's _not_ that
"there is no such thing as an invalid document"...
(garbage happens, and garbage-in-garbage-out.)

it's more along the lines of "if a human can see
the structure which was intended by the author,
markdown should display the structure correctly,
and _not_ tell users they didn't follow the spec."

-bowerbird

p.s.   and now, folks, i really will bow out of this thread...
if you haven't gotten what i'm saying by now, you won't.



**************
It's Tax Time! Get tips, forms, and advice on AOL Money & 
Finance.
      (http://money.aol.com/tax?NCID=aolprf00030000000001)
-------------- next part --------------
An HTML attachment was scrubbed...
URL:
<http://six.pairlist.net/pipermail/markdown-discuss/attachments/20080307/7d26a2f0/attachment.htm>