[Haskell-cafe] Getting some funny brackets in Haddock docs

David Feuer david.feuer at gmail.com
Tue Jan 9 22:55:26 UTC 2018

The containers Haddock documentation currently represents sequences,
sets, and maps via the relevant `fromList` function. For example,
Data.Map gives the example

  findWithDefault 'x' 1 (fromList [(5,'a'), (3,'b')]) == 'x'

I find these `fromList` calls exceedingly distracting, and I think
they obscure the key ideas. Of course, I *could* just specify at the
top that the documentation assumes OverloadedLists, but I think that's
likely to be somewhat confusing, especially to beginners.

My preference would really be to represent these data structures using
funny brackets of some sort. Perhaps ⟦7,34,12⟧ for a sequence, ⦃40,3⦄
for a set, and ⟪(12,"alpha"), (14,"bravo")⟫ for a map. But there are
three problems:

1. How can I insert the brackets conveniently? I definitely don't want
to fill the module with Unicode. My preference would be to use \{ and
\} or \[ and \] and have them get replaced by the left and right
brackets appropriate to the module in question. But I don't actually
know how to do that.

2. Funny brackets could presumably cause trouble for people who don't
have appropriate fonts available. How could I mitigate this?

3. This whole idea could cause trouble for people who want to copy and
paste examples from the documentation. Are people likely to want to do
that? If so, how might I mitigate that problem? Are there tricks I can
play to make copy/paste turn a funny left bracket into `fromList [`
and a funny right bracket into `]`, and also not break things for
non-HTML backends?


More information about the Haskell-Cafe mailing list