Getting some funny brackets in Haddock docs
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? Thanks, David
On 01/09/2018 05:55 PM, David Feuer wrote:
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.
If you think that's confusing, just wait til you try to explain that unicode snowman means circumfix fromList. How about,
let map_with_no_1 = fromList [(5,'a'), (3,'b')] let default_value = 'x' findWithDefault default_value 1 map_with_no_1 == default_value True
An extremely common complaint about Haskell coming from other languages is
the proliferation of un-Googleable operators and symbols. I would be
unhappy to see these changes made, especially as the fancy brackets aren't
valid code (and thus can't be Hoogled or copy/pasted). I suspect that every
non-maintainer of the containers documentation would need to look these
symbols up every time they consulted the documentation, as the
documentation would likely be the only place they're used.
The `fromList` calls are perhaps a little noisy -- having literal syntax
like Python's for maps and sets would be nice, but that's probably not
going to fly given that `containers` isn't part of `base` or the Report.
Matt Parsons
On Tue, Jan 9, 2018 at 9:08 PM, Michael Orlitzky
On 01/09/2018 05:55 PM, David Feuer wrote:
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.
If you think that's confusing, just wait til you try to explain that unicode snowman means circumfix fromList.
How about,
let map_with_no_1 = fromList [(5,'a'), (3,'b')] let default_value = 'x' findWithDefault default_value 1 map_with_no_1 == default_value True
Haskell-Cafe mailing list To (un)subscribe, modify options or view archives go to: http://mail.haskell.org/cgi-bin/mailman/listinfo/haskell-cafe Only members subscribed via the mailman list are allowed to post.
Hi, Am Dienstag, den 09.01.2018, 17:55 -0500 schrieb David Feuer:
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.
they are maybe somewhat verbose and distracting, but they are also explicit (compared to OverloadedLists) and do not introduce new stuff (compared to funny brackets). I would leave it as it is. Joachim -- Joachim Breitner mail@joachim-breitner.de http://www.joachim-breitner.de/
participants (4)
-
David Feuer -
Joachim Breitner -
Matt -
Michael Orlitzky