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

david parsons orc at pell.portland.or.us
Sat Mar 1 17:36:36 EST 2008

In article <EB61C125-47FB-4DC7-ABE2-BBD576D95F8A at attacklab.net>,
John Fraser <markdown-discuss at six.pairlist.net> wrote:

>On Mar 1, 2008, at 1:19 PM, david parsons wrote:

>>> I agree that Markdown needs to be defined unambiguously, but I don't

>>> think that's feasible with plain English in the loop. For something

>>> as complex and flighty as Markdown, we need working code.


>> I'm not so sure about this. I managed to write a markdown

>> implementation without using anything other than the daring

>> fireball

>> syntax document and MarkdownTest_1.0. And I am by no means a

>> Perl programmer.



>Okay, but I'd argue that your success had a lot more to do with the

>test suite than the syntax document.

I'm not sure. The test suite kicked out about 7 failures where
I spazzed out and misread the syntax document, but there was
only one place where I actually had to hack the compiler to
generate test-matching code (the first line of a code block
needs to have trailing whitespace trimmed.)

If I didn't have a test suite, it would have taken a lot longer to
dust out the corners, but if I was confronted with nothing but a
mass of Perl code and a test suite, I don't think I would have
even bothered.

>I'll admit it: I'm probably more suspicious of paper specs than I

>should be. But I can't help thinking that (1) any natural-language

>Markdown spec will have holes; (2) any test suite will have littler

>holes; and (3) the most popular implementation will always be the de

>facto standard.

Which means that you end up having to code-peek to determine
how the language works. And this restricts the audience to
people who are proficient in that language (or, worse yet, to
people who are proficient to the particular dialect that the
developers used when they wrote the code.)

(And it still needs documentation so people can actually use
the code; if Markdown.pl didn't have the syntax document
or the dingus, I suspect that the userbase would be the two
people who developed the language in the first place. So
if you're going to have a document describing how the language
works, why not say that document is the definition of the
language and have it fully describe the process that is
already being done?)

-david parsons

More information about the Markdown-Discuss mailing list