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

[Niklas Hambüchen]

On 01/09/13 04:27, Mateusz Kowalczyk wrote:
> It doesn't have to be 1-to-1 but the features have to be expressible in
> both: it's useless if we have different features with one syntax but not
> the other.

I don't find that useless. Markdown does not have definition lists, but
we use a normal list to achieve the same documentation goals.

Already being able to simply write basic markdown would bring me big
practical benefits, and I would prefer minor theoretical misalignments
not to outweigh them.

>> 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.
> This is precisely what I have been doing and why my post went over every
> point from the original Markdown documentation, talking about why each
> of these does or doesn't make sense. In the end, Markdown offers us
> nothing new feature wise

If the features are the same, I would prefer to write them in markdown.

> and either forces us to make up new syntax for
> things it doesn't know about (definition lists) or makes us remove
> existing features all together.

As I said, I think it doesn't matter. The basic functionality that
people use is all there. I have not seen a haddock definition list in my
life, the first one is encountered is the single one in attoparsec
because I grepped for [@ after reading your post.

>> 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.
> Unfortunately it _does_ matter in practice because each flavour solves
> Markdown quirks differently. On top of this, we have to accomodate for
> Haddock specific features. We're effectively creating our own flavour of
> Markdown + extra syntax. This sounds like… Haddock markup!

Once we have picked one of the flavours, I do not care about the others.
These quirks have little practical relevance: I have put the markdown
from my main github projects into the tool you mentioned, and into
pandoc, and there were no bad surprises for me.

Given that, even if I were to step into a pathologic case, after I write
the documentation, a quick look at it immediately tells me whether
everything is to my liking or not.

>> 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.
> I have to admit that I did not explore this very carefully but you we
> can't simply guarantee that no one every will run CPP on their files by
> hand. Better safe than sorry.

This is unreasonable. You also can't guarantee that nobody will run the
Handlebars templating language either, or any other tool.

You cannot even tell what the user wants to achieve: Should

    -- | You can use `#if SHELL a #else b #endif`

go into the documentation unexpanded or template processed?

The only sane way is to make haddock agnostic of all those tools in the
world, save the Haskell compiler which it addresses by being inside
comments.

If somebody wanted to run their custom tool by hand before running
haddock by hand, sure they would write

    #if ...
    -- | Some haddock
    #else
    -- | Some other haddock
    # endif

if they wished to conditionally generate different haddock.

>> Regarding emphasis, **foo** would simply not be a heading in an export
>> list. Using markdown haddock, we will have markdown headings for that.
> But what if I want it to be a heading? Are we picking rules arbitrarily now?

I do not understand what you mean. If you want it to be a heading, you
write:

    # My heading

I don't find that worse than

    * My heading

>> 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.
> That's because you can use LaTeX to render everything that HTML can (but
> not the other way around!).

Yes, so what is the problem? You write markdown and it can be compiled
to your target languages. Why is it a problem that you cannot go the
other way around?

My point here was saying that markdown can be compiled to the three
targets you mentioned.

> GitHub can use it because they don't have the burden of having to
> accommodate for an existing feature set of a different markup language.
> Note how GitHub Markdown doesn't have all the features of Haddock,
> therefore it is _not_ compatible with it. We can't just use their
> Markdown because it doesn't cover our use cases.

We don't have that burden either, save the easily replaceable definition
list.

Coming back to those, their markdown equivalent could be a list with
links, or simply a ```definition fenced code block.

>> Did I address all your points?
> You addressed some of them, but I hope I reasoned for them well above.
> What you haven't provided is how such Markdown could possibly look,
> noting the original goal of this: be an alternate syntax that's familiar
> to people already.

It could look exactly like Github or pandoc markdown (fine with either,
they are equal enough for me), with the difference that

* they are enclosed in Haskell comments and start with `-- |`
* they resolve type/module links via standard markdown links (this does
not change the parsing)