[Haskell-cafe] On Markdown in Haddock and why it's not going to happen

[Niklas Hambüchen]

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
>
> [2]: http://trac.haskell.org/haddock
>
> [3]: http://trac.haskell.org/haddock/ticket/244