Hello, I disagree. While none of your detail points are wrong, they mainly focus on the fact that there is no 1-to-1 mapping between the existing haddock markup and Markdown. I don't think there needs to be. If Markdown can do something new, that something can be added; if something doesn't make sense in Haddock (like horizontal rules), we ignore them. I don't think original and markdown syntax should be mixed in the same file. That would make everything impossible to parse and difficult to write. As for which markdown implementation to use: I think it really doesn't matter that much in practice. Github and pandoc can both render documentation to my pleasing; I have yet to find a difference between them that would be a practical problem for my documentation efforts. Regarding module and type links: They are links, so probably just representing them as Markdown links would be cleanest. [SomeThing]() with an empty reference could make haddock automatically figure out what is wanted or default to a type, and you could be explicit with [SomeThing](module), [SomeThing](type) and [SomeThing](class). For headings, why is CPP a problem? CPP ignores haddock comments, haddock should ignore CPP. There is no reason to put CPP macros into comments. Regarding emphasis, **foo** would simply not be a heading in an export list. Using markdown haddock, we will have markdown headings for that. Markdown being claimed to be "for editing documents for the Web" doesn't make our efforts impossible. Pandoc can easily create latex output from it, and Github can use it as a documentation language for programming perfectly fine. So can we. Did I address all your points? Niklas On Fri 30 Aug 2013 10:30:51 JST, Mateusz Kowalczyk wrote:
Greetings café,
Perhaps some saddening news for Markdown fans out there. As you might remember, there was a fair amount of push for having Markdown as an alternate syntax for Haddock.
Unfortunately, this is probably not going to happen for reasons listed on the post I just published at [1].
This thread is meant to be for discussion about the post as many people, myself included, felt that Markdown would be a nice thing to have.
I feel like I covered the topic fairly well on the post but feel free to give suggestions or ask questions.
I would also like to remind you that if there's something that you'd like to see in Haddock or something that you feel is broken, a good way express this is to make a ticket on the Haddock Trac[2].
I will close the relevant Markdown ticket on the Trac[3] in about 3 days, unless someone can come up with a reasonable solution that meets the initial intent of this part of the project: a widely known markup format that could be used as an alternate syntax for Haddock so that it's possible to write the documentation without learning the vanilla syntax itself.
[1]: http://fuuzetsu.co.uk/blog/posts/2013-08-30-why-Markdown-in-Haddock-can't-happen.html