Getting some funny brackets in Haddock docs

Previous Topic Next Topic
 
classic Classic list List threaded Threaded
9 messages Options
Reply | Threaded
Open this post in threaded view
|

Getting some funny brackets in Haddock docs

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. 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
_______________________________________________
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.
Reply | Threaded
Open this post in threaded view
|

Re: Getting some funny brackets in Haddock docs

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.
Reply | Threaded
Open this post in threaded view
|

Re: Getting some funny brackets in Haddock docs

Matt
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 <[hidden email]> wrote:
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.


_______________________________________________
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.
Reply | Threaded
Open this post in threaded view
|

Re: Getting some funny brackets in Haddock docs

Johannes Waldmann-2
In reply to this post by David Feuer
OverloadedLists solves this, in a way?

Prelude> :set -XOverloadedLists
Prelude> import qualified Data.Map.Strict as M
Prelude M> M.size [(2,3)]
1

because of the IsList instance
https://hackage.haskell.org/package/containers-0.5.10.2/docs/src/Data.Map.Internal.html#line-3233

Do we want to use this in code examples in the docs?
Equivalently, is it recommended to use this notation in actual code?
The problem I see is that this (and similar) extensions
will be active for all literals in a module -
while we only want it for literals of some specific type.
I know this is handled in the parser, and we don't know the types
at this point.

- J
_______________________________________________
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.
Reply | Threaded
Open this post in threaded view
|

Re: Getting some funny brackets in Haddock docs

Steven Shaw
Johanne
​s, can you explain again what's wrong with the code example you gave. It looks like you're saying that `M.size [(2,3)]` should not be 1 (but I'm not sure).


David, perhaps you could add your own neat GHC language extension for UnicodeOverloadedLists which lets you use those unicode characters to delimit lists in addition to the usual []. When, I'd think it best to assume `UnicodeOverloadedLists` is enabled by making a comment at the top of the documentation.
 The just put those unicode character into the documentation. Damn people those that stare at the square boxes ;). I have no idea how unicode characters work with fonts 😅 ...

There are so many approaches though. You could teach Haddock how to syntax highlight Haskell code​
​ (ghc-exactprint?). Then use a pretty-printer that uses your favourite sequence delimiters — perhaps ⟦⟧.​ Then ensure that you display the Haskell code blocks using your new pretty-printer. Also, you'll need a regular Haskell pretty-printer for use with a "copy" icon to allow folks to copy "regular" Haskell to try in their REPLs (so you probably need to "inject" a tiny bit of JS into the docs).

That sounds like a lot of work so you could hack something together with JS (or GHCJS), munging the normal Haddock output to your tastes.​ If you use GHCJS, you could perhaps even still use ghc-exactprint to help munge the <pre> sections.

_______________________________________________
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.
Reply | Threaded
Open this post in threaded view
|

Re: Getting some funny brackets in Haddock docs

Joachim Breitner-2
In reply to this post by David Feuer
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
  [hidden email]
  http://www.joachim-breitner.de/

_______________________________________________
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.

signature.asc (849 bytes) Download Attachment
Reply | Threaded
Open this post in threaded view
|

Re: Getting some funny brackets in Haddock docs

Johannes Waldmann-2
In reply to this post by Steven Shaw
Hi,

> It looks like you're saying that `M.size [(2,3)]` should not be 1 (but
> I'm not sure).

Sorry for being terse.
No, that was just a comment about syntax, not semantics.

I was just stating that because of the IsList instance,
we can write  [(2,3)]  instead of  M.fromList [(2,3)]

This would give shorter text in the examples in the API doc -
and has the immense benefit that it already works as-is,
does not need any haddock changes, unicodes, JS, etc.

But it would hide the type distinction (Map vs. List)
so it might turn out to be unhelpful.

- J
_______________________________________________
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.
Reply | Threaded
Open this post in threaded view
|

Re: Getting some funny brackets in Haddock docs

Steven Leiva
I consider myself a Haskell beginner, and I think that the current situation (with the use of fromList) will be less confusing than the funny brackets.

Even if you could make it so that copy/past would turn funny brackets into fromList, it would still be surprising behavior. When the code does something unexpected, we are going to try to put in the funny brackets in the repl. (Maybe that's more for programming beginners versus Haskell beginners, but let's not discount them either).

I haven't read the docs, and I understand that your primary concern is the noise from fromList, but I think leaving things as is and adding some wording that says "Hey, if you want to avoid having fromList everywhere in your own code, you can add OverloadedList  extension" would be the most approachable. (Shouldn't be too much to ask a beginner to at least read the preamble of a module's docs).

Just my 2 cents.

On Wed, Jan 10, 2018 at 5:50 AM, Johannes Waldmann <[hidden email]> wrote:
Hi,

> It looks like you're saying that `M.size [(2,3)]` should not be 1 (but
> I'm not sure).

Sorry for being terse.
No, that was just a comment about syntax, not semantics.

I was just stating that because of the IsList instance,
we can write  [(2,3)]  instead of  M.fromList [(2,3)]

This would give shorter text in the examples in the API doc -
and has the immense benefit that it already works as-is,
does not need any haddock changes, unicodes, JS, etc.

But it would hide the type distinction (Map vs. List)
so it might turn out to be unhelpful.

- J
_______________________________________________
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.



--

_______________________________________________
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.
Reply | Threaded
Open this post in threaded view
|

Re: Getting some funny brackets in Haddock docs

m-renaud
Thanks for the input Steven! We did what you mentioned (adding a tip about Overloaded lists near the top) in the containers introduction and walkthrough at https://haskell-containers.readthedocs.io/en/latest/set.html#short-example. It sounds like we should do the same thing in the Haddocks.

I'm also in agreeance that the examples should be copy-pasteable into Haskell source files or the repl. I think what Michael suggested (moving the set/map/sequence construction to a line above and assigning it to a variable) is a good compromise; there's no special syntax added and the actual use of the function becomes less "noisy".

On Wed, Jan 10, 2018, 7:24 AM Steven Leiva <[hidden email]> wrote:
I consider myself a Haskell beginner, and I think that the current situation (with the use of fromList) will be less confusing than the funny brackets.

Even if you could make it so that copy/past would turn funny brackets into fromList, it would still be surprising behavior. When the code does something unexpected, we are going to try to put in the funny brackets in the repl. (Maybe that's more for programming beginners versus Haskell beginners, but let's not discount them either).

I haven't read the docs, and I understand that your primary concern is the noise from fromList, but I think leaving things as is and adding some wording that says "Hey, if you want to avoid having fromList everywhere in your own code, you can add OverloadedList  extension" would be the most approachable. (Shouldn't be too much to ask a beginner to at least read the preamble of a module's docs).

Just my 2 cents.

On Wed, Jan 10, 2018 at 5:50 AM, Johannes Waldmann <[hidden email]> wrote:
Hi,

> It looks like you're saying that `M.size [(2,3)]` should not be 1 (but
> I'm not sure).

Sorry for being terse.
No, that was just a comment about syntax, not semantics.

I was just stating that because of the IsList instance,
we can write  [(2,3)]  instead of  M.fromList [(2,3)]

This would give shorter text in the examples in the API doc -
and has the immense benefit that it already works as-is,
does not need any haddock changes, unicodes, JS, etc.

But it would hide the type distinction (Map vs. List)
so it might turn out to be unhelpful.

- J
_______________________________________________
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.



--
Steven Leiva
<a href="tel:(305)%20528-6038" value="+13055286038" target="_blank">305.528.6038
[hidden email]
http://www.linkedin.com/in/stevenleiva
_______________________________________________
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.

_______________________________________________
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.