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

[Ivan Lazar Miljenovic]

On 5 April 2013 13:24, Richard A. O'Keefe <ok at cs.otago.ac.nz> wrote:
>
> 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.

I don't think so; this was one of the big issues recently when people
were trying to get Gruber to actually _do_ something with Markdown as
there were all these corner cases.

>
>
>
> _______________________________________________
> Haskell-Cafe mailing list
> Haskell-Cafe at haskell.org
> http://www.haskell.org/mailman/listinfo/haskell-cafe



-- 
Ivan Lazar Miljenovic
Ivan.Miljenovic at gmail.com
http://IvanMiljenovic.wordpress.com