On 09/15/2014 11:54 PM, Jonathan Paugh wrote:
Hi all,
Using Markdown would be a great idea. And, if Haddock were to support Markdown, and packages were migrated gradually to that, the inconsistency would disappear (eventually).
IIRC, adding Markdown to Hadock was suggested on this list before, and the major argument against it was that Markdown didn't have a standard. Now, it has one, called CommonMark[1]. Barring any (further) copyright issues with the name, that looks to be a great step forward for Markdown.
Regards, Jonathan Paugh
It was more than proposed, it was the original plan of my GSOC in 2013. In the end it went into a different direction because after actually hacking on Haddock I came to the conclusion that Markdown was actually not a good idea. You can find reasons in café archives I'm sure. Standardisation was only one of the problems. The biggest problem is is that Haddock and Markdown simply serve a different purpose and there is no clear 1:1 mapping between the two. There is also the question of who's going to maintain it. We are severely understaffed. Haddock has only two maintainers, Simon Hengel and myself and Simon tends to be quite busy so it's mostly myself, and I also have about a billion projects I want to spend time on. I don't want to maintain another parser, there are more important things to hack. Honestly, it's sad that such a core project is so understaffed. Alas, complaining is not my main aim here. I simply want to point out that after some work, the Haddock parser and the required types now don't depend on GHC or any other libs that don't ship (bar for internal attoparsec dependency) with the compiler. This means that recent Pandoc now has both reader and writer modules for Haddock which means you can go Haddock <=> Markdown if you wish and get some results. I have not tried it myself however. Incidentally, implementing such reader/writer Pandoc modules was my initial submission in 2013. In summary, if you really want to write Markdown instead of Haddock, use pandoc to convert between the two. I really wonder if the hassle is worth it though. -- Mateusz K.