Re: [Haskell-cafe] Getting some funny brackets in Haddock docs
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.In... 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
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.
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
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 < johannes.waldmann@htwk-leipzig.de> 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 305.528.6038 leiva.steven@gmail.com http://www.linkedin.com/in/stevenleiva
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
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 < johannes.waldmann@htwk-leipzig.de> 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 305.528.6038 <(305)%20528-6038> leiva.steven@gmail.com 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.
participants (4)
-
Johannes Waldmann -
Matt Renaud -
Steven Leiva -
Steven Shaw