[Haskell-cafe] Markdown extension for Haddock as a GSoC project

[Richard A. O'Keefe]

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?