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

[Mateusz Kowalczyk]

On 31/08/13 19:14, Niklas Hambüchen wrote:
> Hello,
> 
> I disagree.
That's fine, that's why the thread is here.
> 
> While none of your detail points are wrong, they mainly focus on the
> fact that there is no 1-to-1 mapping between the existing haddock markup
> and Markdown. I don't think there needs to be.
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.

> 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 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. Once any not-HTML-specific (tags, rules)
features that might be missing are implemented, we're left with
something that looks very much like Markdown already. Alternate syntax
would also look very much like Markdown but in a different, less known
way. Not very nice. Basically, Markdown brings nothing new to the table
that we can actually use and we're in fact making it less familiar by
having to strip and add syntax.
> 
> I don't think original and markdown syntax should be mixed in the same
> file. That would make everything impossible to parse and difficult to write.
Agreed. See point above why this isn't practical anyway. We'd be piling
features on top of Markdown, defeating the point of having
familiar-to-others syntax.
> 
> 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!
> 
> 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. I actually implemented headings for
function docs using the ‘==== Heading 4’ syntax, avoiding this problem
all together.
> 
> 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?
> 
> 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!).

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.
> 
> 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. If you can come up with such thing without losing any
features and being distinct enough from Haddock markup to warrant it, I
would love to hear it.
> 
> Niklas
> 



-- 
Mateusz K.