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

[John MacFarlane]

+++ Mateusz Kowalczyk [Sep 02 13 21:34 ]:
> On 02/09/13 19:43, John MacFarlane wrote:
> > 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.  
> Paragraph level elements are indeed not allowed in lists. The list
> contents are currently (that is, on my working branch) allowed to be:
> monospace (delimited by @), anchors, identifiers, module names,
> pictures, URLs, bold, emphasis, HTML escape codes, regular strings. Note
> that if a monospaced string is the only element of the list content, it
> gets turned into a code block.
> 
> I'm not sure what you mean by block elements.

I mean things like paragraphs, blockquotes, code blocks, other lists.

In markdown you can have a list item that contains these things:

1.  This is my first list item.

    Second paragraph of first list item. Some code:

        foo = bar <$> baz <*> 2.0

2.  This is my second list item.

    * Sublist item one
    * Sublist item two

3.  This is my third list item.  Someone said:

    > We want markdown support in haddock!

In Haddock, last I looked, you couldn't do any of this...

In your original message, you emphasized features of Haddock that
don't exist in standard markdown and would require extensions
(definition lists, automatic links to Haskell identifiers, etc.).

But in many other ways, markdown is much more expressive than
Haddock markup, as the example above illustrates.  The changes that
would be needed to Haddock to allow it to express what can be expressed
in markdown are much bigger, I think, than the changes that would be
needed to markdown to allow it to express what can be expressed in
Haddock.