On 29/04/2013, at 3:26 AM, Chris Smith wrote:
I think it's worth backing up here, and remembering the original point of the proposal, by thinking about what is and isn't a goal. I think I'd classify things like this:
Goals: - Use a lightweight, common, and familiar core syntax for simple formatting. - Still allow haddock-specific stuff like links to other symbols.
Non-Goals: - Compliance/compatibility with any specification or other system. - Have any kind of formal semantics.
Why I find the idea of rejecting semantics appalling: Last week I was working with a documentation tool for another language which claims to be "Markdown" and where *bold* only allows one or more alphabetic words **bold** allows any text _italic_ only allows one or more alphabetic words __italic__ allows any text Today I had to revise some documentation for yet a third language which also claims to be "Markdown" and where *word* and _word_ both gave italics **word* and __word__ both gave bold. Oh, and the markup wasn't documented, because it was just "Markdown", and everyone knows Markdown, right? The syntax I was using was legal syntax, but the semantics was not the semantics I expected and was not written down. I don't care how formal the syntax and semantics are, but I care very much how complete they are.
Formal semantics is a non-issue: the behavior will still be defined by the implementation, in that people will write their documentation, and if it looks wrong, they will fix it.
Sorry, but this is rubbish. If the semantics is not documented, then people will write their documentation, and it will look wrong, AND THEY WILL NEVER HAVE BEEN GIVEN A CLUE ABOUT WHAT TO WRITE INSTEAD.
We don't want to reason formally about the formatting of our comments, or prove that it's correct. Avoiding unpleasant surprises is good; but avoiding *all* possible ambiguous corner cases in parsing, even when they are less likely than typos, is not particularly important.
Hmm. Just today, again, looking at the revision list for a Markdown processor, I see comments like "This changes the syntax from all previous versions... Code blocks and spans ... will now generate different output..." (which reminds me that the author may not be able to fix the looks of their documentation because it may have been perfectly fine when they wrote it, and they may be unavailable when the semantics changes) "Tweaked the rules ... this may affect existing content" (see above) Sort-of fixed a bug ... Given Markdown's list creation rules, I'm not sure this *can* be fixed." (which is the kind of thing that happens when you decide a clear syntax and semantics are not necessary).
If some ambiguity becomes a big problem, it will get fixed later as a bug.
As the comment extracted above suggests, it may not be fixable. We may not care about compatibility with other dialects of Markdown, but we should care about compatibility between versions of Haddock. Damn! Why did Watts Humphrey have to die before he'd convinced the world that the cheapest way to fix bugs is to keep them out in the first place?