[Haskell-cafe] GSoC Project Proposal: Markdown support for Haddock

[Richard A. O'Keefe]

On 5/04/2013, at 2:00 PM, Johan Tibell wrote:

>> Would it be too much to ask that a notation be used which has
>> a formal syntax and a formal semantics?
> 
> We will document our superset, sure. That's what others did as well.
> The point is using Markdown as the shared base.

Nononono.
Sure, the others "documented" their supersets.
But they did *NOT* provide what I am asking for:
 - a FORMAL SYNTAX and
 - a FORMAL SEMANTICS.
I tried to use one of these systems, and found myself
unable to determine which combinations of features were
legal and what legal combinations of features *meant*.
I corresponded with some people who had built markdown
parsers, and the answer was the same each time: they had
reversed engineered some other parser (typically a Perl
one) and bashed on it until they were bug-compatible.

If I want to get a particular effect in LaTeX or even in
HTML+CSS, I can usually figure it out *without* having to
run any program.  If I want to get a particular effect in
Markdown, I flounder around and end up doing without.

I am sick of "documentation" that vaguely hints at things,
and I am especially sick of Markdown so-called documentation.

To say it one more time:  I was unable to use the official
Markdown documentation,
http://daringfireball.net/projects/markdown/syntax,
to guide the construction of a parser.

For example, <br> is a valid URL enclosed in <. . .>, so
is it a link, as the "Automatic Links" section would suggest,
or is it embedded HTML, as the "Inline HTML" section would
suggest?  Can you tell *from the documentation*?

For another example, is *foo**bar**ugh* supposed to map to
<em>foo<strong>bar</strong>ugh</em> or to
<em>foo</em><em>bar</em><em>ugh</em>?
Again, I'm not asking "what does this or that *program* do",
I'm asking "can you tell from the documentation what they
*ought* to do?"

If there is an unambiguous specification of Markdown somewhere
(specification; not program), I would be glad to see it.