[Haskell-cafe] Hackage package "synopsis" sections

[Mateusz Kowalczyk]

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.
>
> [1]: http://commonmark.org
> 
> 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.