[Haskell-cafe] Haddock changes pushed upstream

[Mateusz Kowalczyk]

On 27/01/14 04:59, Evan Laforge wrote:
> On Sun, Jan 12, 2014 at 5:37 PM, Mateusz Kowalczyk
> <fuuzetsu at fuuzetsu.co.uk> 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.