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

[John MacFarlane]

When the proposal was first being discussed, I suggested that instead of
adding markdown support to haddock, one might enhance the existing
haddock markup, making it more expressive, so that it could encode the same
range of structural features as markdown.  If I'm not mistaken, currently
haddock doesn't allow list items with multiple paragraphs or other block
elements, or nested lists, or images, or blockquotes.  This makes it
impossible to create a pandoc writer for haddock markup (we already have a
haddock reader, soon to be released).

With a pandoc writer for haddock, one could write longer documentation sections
(e.g. tutorials) in markdown and convert them to haddock for inclusion in
source code.  This should help people who don't like haddock markup or don't
want to learn it.  With the reader, haddock comments can already be converted
into other formats.

I haven't been following your work, but do I understand correctly
that you've been making haddock markup more expressive and rational?
Has this gotten to the point where a pandoc writer would be feasible?

John

+++ Mateusz Kowalczyk [Aug 30 13 02:30 ]:
> 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
> -- 
> Mateusz K.
> 
> _______________________________________________
> Haskell-Cafe mailing list
> Haskell-Cafe at haskell.org
> http://www.haskell.org/mailman/listinfo/haskell-cafe