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
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
On 31/08/13 19:14, Niklas Hambüchen wrote: the other. 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.