Re: [Haskell-cafe] Haddock changes pushed upstream

On 27/01/14 04:59, Evan Laforge wrote:

On Sun, Jan 12, 2014 at 5:37 PM, Mateusz Kowalczyk wrote:

...

* Bold markup added. The syntax is two underscores around what you want bold. Note, we still do not support multi-line markup. It's possible but it's a design choice not to support it.

This is all great, but I have a concern about this one. Do we really need more than one kind of emphasis?

Actually, mostly what I don't like is the / markup, because slashes are common, e.g. URLs and paths, and it's a pain to escape them all the time. Messed up formatting due to forgetting a backslash is very common in my docs, and I've even seen it in GHC docs as well.

This is an existing markup and we won't change it because every piece of documentation using it will break. I have seen plenty of documentation with ugly markup because someone forgot to escape something but it is unavoidable. I agree that ‘/’ might not be the best character but it's as good as any other for this purpose. If it was something else, people would complain about that instead.

I would prefer to swap /s for *s because *s seem less common, but of course that would break stuff. And I'm sure there are people out there who like using /s for emphasis, so we don't need to repaint that bikeshed. But at least we can avoid adding even more special characters you need to remember to escape.

If it was ‘*’ then we'd have to remember that instead (and ‘*’ is also a very common character). The reason I picked two underscores for bold is precisely because it's not that common.

And bold emphasis seems like it's redundant with italics emphasis.

You're free to not use it. A lot of people wanted bold (including myself). It looks different, it's a different kind of emphasis, why not include it? I don't understand your point of view on this. Are you not against different kinds of lists? I mean, all of them enumerate things so why bother with 3 different kinds, right? It is also now a bit late for this post, documentation and tests have been written and it's all done and dusted, just waiting for the imminent 7.8 release. There was plenty of time for input. If you have a pressing reason why bold shouldn't be included, file a Haddock ticket. -- Mateusz K.