[Haskell-cafe] Haskell-Cafe Digest, Vol 217, Issue 17
Michael Turner
michael.eugene.turner at gmail.com
Fri Sep 17 03:53:13 UTC 2021
Wow, someone on this thread said of me, from what I wrote on the
beginner's list, "He's trying to translate Haskell to C/C++."
No. I started here:
https://www.stwing.upenn.edu/~wlovas/hudak/aug.pdf
I'd like to use this parsing technique for natural language. I had no
intention of translating Haskell to C/C++ unless it turned out to
matter for performance. What I didn't realize starting out in trying
to understand that code is that it's horribly written code, and
underdocumented. 'g' as a function name, a name not clearly related to
any meaning? Oh, and how about this type signature:
app :: (TTree -> TTree -> Tree) -> TTree -> TTree -> [TTree]
I actually reached a point where I thought, "I'm never gonna
understand this code," because of that line. Somehow, after weeks of
scrolling past it, grimacing, then looking at it again, I figure out a
clarification.
-- Order (Before/After)
type Order = Typed_Tree -> Typed_Tree -> Tree
and then I get
app ::
Order
-> Typed_Tree -- the TT to be applied
-> Typed_Tree -- TT applied to
-> [Typed_Tree] -- result list
Is that "translating it to C++"? Or is it "translating it to something
you can at least mentally translate into plain English"? (Current
frustration: can't seem to find a clean way to extract "Before" and
"After" type constructors from Order, as strings to print in trace
messages. Several "solutions" found, all either not working in my
version of GHC, or not even compilable.)
I finally realized: that paper where I started learning Haskell may be
a gem as a paper in English, but the code is basically dashed off, by
people so steeped in Haskell that it was all obvious to them. And it
uses a representation of a left upper-triangular array (in a
list-of-lists approach that probably sprays garbage left and right in
the course of Haskell evaluations of "transpose", "reverse", etc.)
which only makes the code harder to understand.
And I haven't convinced myself that it wouldn't just spray smaller
numbers of larger pieces of garbage anyway, if I rewrote it to clean
out all the list-hacking cruft. Maybe it's OK. Maybe the GHC optimizer
really is that good. But before I refactor it to Vector, first I have
to make sure I really understand what this code is doing, so that the
unit tests I'm adding don't just fail mysteriously. And I'm not there
yet.
When you read a "diagnosis" of me as someone whose mind is resistant
to the Haskell execution model, please ignore it. I'm not resisting
it. I'm trying to internalize it. Unfortunately, I haven't found a
treatment that ties the execution model to where the rubber hits the
road: real computers, like you buy at a store, which are derided by
this commenter as "Turing machines." Sorry, guy, but you wrote your
reply on a Turing machine. Turing machines got it to my inbox. As
Simon Peyton-Jones said, in a talk about how to handle effects, you
can't really verify that your program is executing correctly by
noticing that the box it's running on gets warmer.
I'm quite fine with purity, at least where it can reduce debugging
time. I've learned a couple of other functional languages, if you'll
condescendingly permit that, say, Lisp and Erlang are "functional." In
college, I got fascinated by the idea of a Lisp interpreter with lazy
evaluation, and read some papers on the subject, and I even believe
laziness could prove useful for the project I'm on. I'm all for static
typing. I'm all for how lazy evaluation and purity and functional
programming in general can facilitate exploitation of multi-core
parallelism. What I want is a clear, concise description of the
execution model, to tie it all finally back down to those horrible
grubby Turing machines that people buy in stores. Like the one on my
desk, right now.
Regards,
Michael Turner
Executive Director
Project Persephone
1-25-33 Takadanobaba
Shinjuku-ku Tokyo 169-0075
Mobile: +81 (90) 5203-8682
turner at projectpersephone.org
Understand - http://www.projectpersephone.org/
Join - http://www.facebook.com/groups/ProjectPersephone/
Donate - http://www.patreon.com/ProjectPersephone
Volunteer - https://github.com/ProjectPersephone
"Love does not consist in gazing at each other, but in looking outward
together in the same direction." -- Antoine de Saint-Exupéry
On Fri, Sep 17, 2021 at 11:18 AM <haskell-cafe-request at haskell.org> wrote:
>
> Send Haskell-Cafe mailing list submissions to
> haskell-cafe at haskell.org
>
> To subscribe or unsubscribe via the World Wide Web, visit
> http://mail.haskell.org/cgi-bin/mailman/listinfo/haskell-cafe
> or, via email, send a message with subject or body 'help' to
> haskell-cafe-request at haskell.org
>
> You can reach the person managing the list at
> haskell-cafe-owner at haskell.org
>
> When replying, please edit your Subject line so it is more specific
> than "Re: Contents of Haskell-Cafe digest..."
>
>
> Today's Topics:
>
> 1. Re: Haskell's "historical futurism" needs better writing, not
> better tools (Viktor Dukhovni)
> 2. Re: Haskell's "historical futurism" needs better writing, not
> better tools (David Feuer)
> 3. Re: Haskell's "historical futurism" needs better writing, not
> better tools (Viktor Dukhovni)
> 4. Re: Haskell's "historical futurism" needs better writing, not
> better tools (David Feuer)
> 5. Re: Haskell's "historical futurism" needs better writing, not
> better tools (Anthony Clayden)
> 6. Haskell reference documentation, laws first or laws last?
> (Viktor Dukhovni)
> 7. Re: Haskell reference documentation, laws first or laws last?
> (Anthony Clayden)
> 8. Re: Haskell reference documentation, laws first or laws last?
> (Chris Smith)
> 9. Re: Haskell reference documentation, laws first or laws last?
> (David Feuer)
> 10. Re: Haskell reference documentation, laws first or laws last?
> (Viktor Dukhovni)
> 11. Re: Haskell reference documentation, laws first or laws last?
> (Anthony Clayden)
> 12. Re: Haskell reference documentation, laws first or laws last?
> (Chris Smith)
> 13. Re: Haskell reference documentation, laws first or laws last?
> (David Feuer)
> 14. Re: Haskell reference documentation, laws first or laws last?
> (Viktor Dukhovni)
> 15. Re: Haskell reference documentation, laws first or laws last?
> (Sebastiaan Joosten)
>
>
> ----------------------------------------------------------------------
>
> Message: 1
> Date: Thu, 16 Sep 2021 16:52:22 -0400
> From: Viktor Dukhovni <ietf-dane at dukhovni.org>
> To: haskell-cafe at haskell.org
> Cc: Michael Turner <michael.eugene.turner at gmail.com>
> Subject: Re: [Haskell-cafe] Haskell's "historical futurism" needs
> better writing, not better tools
> Message-ID: <YUOuhjb3t0bYRkI0 at straasha.imrryr.org>
> Content-Type: text/plain; charset=us-ascii
>
> On Wed, Sep 15, 2021 at 04:07:38PM +0900, Michael Turner wrote:
>
> > The real problem is that the writing sucks. Not all of it -- and some
> > contributors to the community are stellar writers, even if, in the
> > snarkish commentary they write about Haskell and the community, I
> > don't quite get all the jokes. But speaking as a contributor to the
> > Haskell.org wiki -- to which I contribute at times out of hope that
> > clarifying points I understand will also lead to more clarity for
> > myself -- I have to say it: the writing sucks.
>
> Can you be a bit more specific about which sort of writing you find
> sufficiently unsatisfactory to say "the writing sucks"?
>
> * Books about Haskell
> - Introductory (e.g. http://learnyouahaskell.com/)
> - Comprehensive (e.g. the classic Real World Haskell)
> - Topic focused (e.g. the IMHO rather excellent Parallel and
> Concurrent Haskell)
> - Theory focused (e.g.
> https://bartoszmilewski.com/category/category-theory/)
> - ...
> * The library reference documentation?
> * The GHC User's Guide?
> * The Haskell report?
> * Blog posts?
> * The Haskell Wiki?
> * r/haskell?
> * Haskell mailing lists?
> ...
> * All of the above???
>
> I am also curious whether I'm part of the solution or part of the
> precipitate. I've recently contributed new documentation for
> Data.Foldable and Data.Traversable:
>
> https://dnssec-stats.ant.isi.edu/~viktor/haskell/docs/libraries/base/Data-Foldable.html#g:7
> https://dnssec-stats.ant.isi.edu/~viktor/haskell/docs/libraries/base/Data-Traversable.html#g:4
>
> are these a step in the right direction, or examples of more writing
> that sucks? These are reference documentation, not beginner tutorials,
> so a more detailed write up of the concepts, pitfalls, ... things to
> keep in mind when using library, ...
>
> More of that sort of thing would help me to more quickly learn to use
> some of the libraries that lack this sort of overview prose, but perhaps
> what you're looking for is something else?
>
> --
> Viktor.
>
>
> ------------------------------
>
> Message: 2
> Date: Thu, 16 Sep 2021 16:57:28 -0400
> From: David Feuer <david.feuer at gmail.com>
> To: "haskell-cafe at haskell.org" <haskell-cafe at haskell.org>
> Cc: Michael Turner <michael.eugene.turner at gmail.com>
> Subject: Re: [Haskell-cafe] Haskell's "historical futurism" needs
> better writing, not better tools
> Message-ID:
> <CAMgWh9tRX=r8MMSvzTGMr2iQMcgzKwdRc7SF=zx2wgPXPojN+A at mail.gmail.com>
> Content-Type: text/plain; charset="utf-8"
>
> I am not a fan of how the new Traversable documentation buries the actual
> laws.
>
> On Thu, Sep 16, 2021, 4:55 PM Viktor Dukhovni <ietf-dane at dukhovni.org>
> wrote:
>
> > On Wed, Sep 15, 2021 at 04:07:38PM +0900, Michael Turner wrote:
> >
> > > The real problem is that the writing sucks. Not all of it -- and some
> > > contributors to the community are stellar writers, even if, in the
> > > snarkish commentary they write about Haskell and the community, I
> > > don't quite get all the jokes. But speaking as a contributor to the
> > > Haskell.org wiki -- to which I contribute at times out of hope that
> > > clarifying points I understand will also lead to more clarity for
> > > myself -- I have to say it: the writing sucks.
> >
> > Can you be a bit more specific about which sort of writing you find
> > sufficiently unsatisfactory to say "the writing sucks"?
> >
> > * Books about Haskell
> > - Introductory (e.g. http://learnyouahaskell.com/)
> > - Comprehensive (e.g. the classic Real World Haskell)
> > - Topic focused (e.g. the IMHO rather excellent Parallel and
> > Concurrent Haskell)
> > - Theory focused (e.g.
> > https://bartoszmilewski.com/category/category-theory/)
> > - ...
> > * The library reference documentation?
> > * The GHC User's Guide?
> > * The Haskell report?
> > * Blog posts?
> > * The Haskell Wiki?
> > * r/haskell?
> > * Haskell mailing lists?
> > ...
> > * All of the above???
> >
> > I am also curious whether I'm part of the solution or part of the
> > precipitate. I've recently contributed new documentation for
> > Data.Foldable and Data.Traversable:
> >
> >
> > https://dnssec-stats.ant.isi.edu/~viktor/haskell/docs/libraries/base/Data-Foldable.html#g:7
> >
> > https://dnssec-stats.ant.isi.edu/~viktor/haskell/docs/libraries/base/Data-Traversable.html#g:4
> >
> > are these a step in the right direction, or examples of more writing
> > that sucks? These are reference documentation, not beginner tutorials,
> > so a more detailed write up of the concepts, pitfalls, ... things to
> > keep in mind when using library, ...
> >
> > More of that sort of thing would help me to more quickly learn to use
> > some of the libraries that lack this sort of overview prose, but perhaps
> > what you're looking for is something else?
> >
> > --
> > Viktor.
> > _______________________________________________
> > 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.
> -------------- next part --------------
> An HTML attachment was scrubbed...
> URL: <http://mail.haskell.org/pipermail/haskell-cafe/attachments/20210916/169d5cc4/attachment-0001.html>
>
> ------------------------------
>
> Message: 3
> Date: Thu, 16 Sep 2021 18:43:31 -0400
> From: Viktor Dukhovni <ietf-dane at dukhovni.org>
> To: haskell-cafe at haskell.org
> Subject: Re: [Haskell-cafe] Haskell's "historical futurism" needs
> better writing, not better tools
> Message-ID: <YUPIk35GfjpHNvxP at straasha.imrryr.org>
> Content-Type: text/plain; charset=us-ascii
>
> On Thu, Sep 16, 2021 at 04:57:28PM -0400, David Feuer wrote:
>
> > I am not a fan of how the new Traversable documentation buries the
> > actual laws.
>
> The laws are one click away from the table of contents, and IMHO not
> particularly illuminating other than for advanced readers.
>
> For example, in Data.Foldable they are:
>
> foldr f z t = appEndo (foldMap (Endo . f) t ) z
> foldl f z t = appEndo (getDual (foldMap (Dual . Endo . flip f) t)) z
> fold = foldMap id
> length = getSum . foldMap (Sum . const 1)
>
> is someone new to Data.Foldable really going to learn something from
> these before they've deeply understood the background concepts?
>
> My take is that the laws should almost always be "buried" (one click
> away) at the end of the module documentation. Those who care and need
> them can find them, but I think they just intimidate the less
> experienced readers. Putting the laws first likely only discourages
> beginners.
>
> --
> Viktor.
>
>
> ------------------------------
>
> Message: 4
> Date: Thu, 16 Sep 2021 18:51:42 -0400
> From: David Feuer <david.feuer at gmail.com>
> To: "haskell-cafe at haskell.org" <haskell-cafe at haskell.org>
> Subject: Re: [Haskell-cafe] Haskell's "historical futurism" needs
> better writing, not better tools
> Message-ID:
> <CAMgWh9u4qX+LYQb2nA2hayDeouQkOLQ6x2AWLAb186S8AijOAg at mail.gmail.com>
> Content-Type: text/plain; charset="utf-8"
>
> The last time I went to look at the laws it took me a couple minutes to
> find them. I use them to write instances. Pretty important, IMO.
>
> On Thu, Sep 16, 2021, 6:46 PM Viktor Dukhovni <ietf-dane at dukhovni.org>
> wrote:
>
> > On Thu, Sep 16, 2021 at 04:57:28PM -0400, David Feuer wrote:
> >
> > > I am not a fan of how the new Traversable documentation buries the
> > > actual laws.
> >
> > The laws are one click away from the table of contents, and IMHO not
> > particularly illuminating other than for advanced readers.
> >
> > For example, in Data.Foldable they are:
> >
> > foldr f z t = appEndo (foldMap (Endo . f) t ) z
> > foldl f z t = appEndo (getDual (foldMap (Dual . Endo . flip f) t)) z
> > fold = foldMap id
> > length = getSum . foldMap (Sum . const 1)
> >
> > is someone new to Data.Foldable really going to learn something from
> > these before they've deeply understood the background concepts?
> >
> > My take is that the laws should almost always be "buried" (one click
> > away) at the end of the module documentation. Those who care and need
> > them can find them, but I think they just intimidate the less
> > experienced readers. Putting the laws first likely only discourages
> > beginners.
> >
> > --
> > Viktor.
> > _______________________________________________
> > 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.
> -------------- next part --------------
> An HTML attachment was scrubbed...
> URL: <http://mail.haskell.org/pipermail/haskell-cafe/attachments/20210916/3ce60cae/attachment-0001.html>
>
> ------------------------------
>
> Message: 5
> Date: Fri, 17 Sep 2021 11:32:04 +1200
> From: Anthony Clayden <anthony.d.clayden at gmail.com>
> To: Haskell Cafe <haskell-cafe at haskell.org>
> Subject: Re: [Haskell-cafe] Haskell's "historical futurism" needs
> better writing, not better tools
> Message-ID:
> <CABU_mxgAdZdQG0Q+A2CSMpB8z=es0S+rb6PKmHu3Yaf7LRqkig at mail.gmail.com>
> Content-Type: text/plain; charset="utf-8"
>
> Thank you Richard, I'm quite comfortable with discussing in public whether
> my response was appropriate.
>
> Michael might as well observe early that there's a broad range of views as
> to how best to learn Haskell. (And every reason that what works for some
> doesn't work for others.) I was sharing my experience. I was also drawing
> on observations of q's on StackOverflow, for which there's an
> alarming number who think Haskell is just C/C++ spelled funny. (Take the
> very first [Haskell] q right now.)
>
> Learning by 'mentally executing' programs is a workable approach -- but not
> if your mental model of execution is a Turing machine.
>
> And I was observing Michael's actual q on the Beginners list. It's clear to
> me:
>
> * He's trying to translate Haskell to C/C++.
> * He thinks Lambda calculus is 'advanced'/complicated/beyond a beginner.
> * He hasn't tried Lambda calculus/he didn't say it "wasn't helpful for him".
> * He thinks that already knowing a swag of procedural/OOP languages will
> help with learning Haskell.
>
> I'd say all of those are unhelpful blocks to learning.
>
> Perhaps in my personal 'learning journey' it helped that I was profoundly
> dissatisfied with procedural languages (of which I'd worked in over a
> dozen); and that I fell across Backus' 'Can Programming be liberated ...?',
> then Lambda calculus, before I landed on an actual implementation of those
> ideas in Haskell.
>
> And for sure, my learning approach left me with some misconceptions, that
> Richard and others have patiently untangled.
>
> AntC
>
> On Fri, 17 Sept 2021 at 02:05, Richard Eisenberg <lists at richarde.dev> wrote:
>
> > I just want to pipe up and say I'm not comfortable with this response.
> > When I feel this way about writing on a forum, I normally contact the
> > author in private, but I think posting publicly here has its merits. I'm
> > hoping that the long correspondence AntC and I have had -- often with
> > opposing viewpoints but with mutual respect -- with withstand this email.
> >
> > Michael posted here expressing frustration with his experience learning
> > and using Haskell. In my opinion, he has spent too much time reading older
> > papers, written by experts for experts -- which Michael is not. I do not
> > fault Michael for this: these resources are sometimes what appear when
> > searching, and we as a community have done a poor job marshaling our
> > educational resources. (Michael, I just thought of a resource you might
> > find useful: http://dev.stephendiehl.com/hask/ is an oft-linked resource
> > attempting to do that marshaling. I am not vouching for it here, per se,
> > but I know others have found it useful.)
> >
> > However, Michael very specifically said that "just learn lambda-calculus"
> > was not helpful for him, and so I think it's unhelpful for someone to
> > respond with "just learn lambda-calculus". There are a number of other
> > statements in the email below which could be seen as belittling -- also not
> > helpful.
> >
> > ...
> >
> > In the meantime, I implore us to take all expressed experiences as exactly
> > that: the experience of the person writing. And if they say they don't want
> > X, please let's not feed them X. :)
> >
> > Richard
> >
> > On Sep 16, 2021, at 12:53 AM, Anthony Clayden <anthony.d.clayden at gmail.com>
> > wrote:
> >
> > Hi Michael, oh dear, oh dear, oh dear.
> >
> > The seeds of your confusion are very evident from your message. How to
> > back you out of whatever deep rabbit-hole you've managed to get your head
> > into?
> >
> > > ... Your average reader (already a programmer) would be better served
> > by a comparative approach: Here's how to say something in a couple of
> > other programming languages, here's how to say something roughly
> > equivalent in Haskell -- BUT, here's how it's subtly different in Haskell.
> >
> > No. Just no. Haskell is not "subtly different" to (say) Java in the way
> > that C++ or C# are different. (I'll leave others to judge how subtly
> > different they are.)
> >
> > Haskell is dramatically and fundamentally different. You can't just
> > 'translate' an algorithm from OOP to Haskell. Many newbies try, and there's
> > many tales of woe on StackOverflow. Just No.
> >
> > I really don't know how you could have got any experience with Haskell and
> > say "subtly".
> >
> > I suggest you unlearn everything you think you know about Haskell, and
> > strike out in an entirely different direction. The best approach would be
> > to spend a few days playing with lambda calculus. (That's what I did before
> > tackling Haskell.)
> > ...
> >
> >
> -------------- next part --------------
> An HTML attachment was scrubbed...
> URL: <http://mail.haskell.org/pipermail/haskell-cafe/attachments/20210917/e9c827d5/attachment-0001.html>
>
> ------------------------------
>
> Message: 6
> Date: Thu, 16 Sep 2021 19:43:07 -0400
> From: Viktor Dukhovni <ietf-dane at dukhovni.org>
> To: haskell-cafe at haskell.org
> Subject: [Haskell-cafe] Haskell reference documentation, laws first or
> laws last?
> Message-ID: <YUPWi+hKBaZzyEGC at straasha.imrryr.org>
> Content-Type: text/plain; charset=us-ascii
>
> On Thu, Sep 16, 2021 at 06:51:42PM -0400, David Feuer wrote:
>
> > The last time I went to look at the laws it took me a couple minutes to
> > find them. I use them to write instances. Pretty important, IMO.
>
> I agree the laws are important to document, I just don't think they
> belong at the top of the module. The beginner to intermediate users
> will be using the library and existing instances for some time before
> they start to write their own instances.
>
> If more modules adopt something like the style of the new Data.Foldable,
> experienced users will know to look for the laws at the end, if not
> still present at the top of the module.
>
> Of course perhaps the community would prefer the original Laws first
> format, I'm fine with that emerging as the consensus. Perhaps worthy
> of a separate thread (made it so).
>
> Of course the conjectured users who might most benefit from not being
> intimidated by being exposed to laws before they're ready to understand
> them might not be present on this forum...
>
> --
> Viktor.
>
>
> ------------------------------
>
> Message: 7
> Date: Fri, 17 Sep 2021 12:37:17 +1200
> From: Anthony Clayden <anthony.d.clayden at gmail.com>
> To: haskell-cafe at haskell.org
> Subject: Re: [Haskell-cafe] Haskell reference documentation, laws
> first or laws last?
> Message-ID:
> <CABU_mxgk9qKTNeZXqSpViRAXxNUHv2UzQKhuz_wWHYEs-7GGKw at mail.gmail.com>
> Content-Type: text/plain; charset="utf-8"
>
> Hi Viktor, really this is a quite different q than the thread talking
> about a learner's experience.
>
> You're writing deeply-technical detail not at all aimed at beginners.
> There's a very broad range of reasons and prior knowledge for readers
> of Library docos.
>
> But I disagree with this:
>
> > The beginner to intermediate users will be using the library and existing instances for some time before they start to write their own instances.
>
> I'll want to write an instance of Foldable as soon as I've declared my
> datatype, won't I? Or do you expect me to be folding only over Lists?
>
> Speaking for myself, if I want to understand a function, I look first
> at its type then its source definition.
>
> The Laws for the particular Foldable example I don't understand at
> all. I'd say: hide those Laws as far away as possible.
>
> In fact, since the blasted FTP re-organisation of that library, I've
> more or less given up. Too hard/too abstract/too much Category Theory.
> What's an `Endo`?
>
> Thank you for your efforts to document. I expect there's someone
> you're helping. Not me. I don't think it's that the style "sucks".
>
> This style and content is enough for me:
> https://www.haskell.org/hugs/pages/libraries/base/Data-Foldable.html
>
>
> > Of course the conjectured users who might most benefit from not being intimidated by being exposed to laws before they're ready to understand them might not be present on this forum...
>
>
> I've gone well beyond the point of being intimidated by Category
> Theorists. I find they're doing a splendid job of putting people off
> getting to love Haskell as I used to. If you want to tell me off for
> speaking out of turn, go ahead. (But this forum is the cafe, perhaps
> this particular discussion should be on glasgow-haskell-users?)
>
>
> AntC
>
>
> On Thu, Sep 16, 2021 at 06:51:42PM -0400, David Feuer wrote:
> >* The last time I went to look at the laws it took me a couple minutes to
> *>* find them. I use them to write instances. Pretty important, IMO.
> *
> I agree the laws are important to document, I just don't think they
> belong at the top of the module. The beginner to intermediate users
> will be using the library and existing instances for some time before
> they start to write their own instances.
>
> If more modules adopt something like the style of the new Data.Foldable,
> experienced users will know to look for the laws at the end, if not
> still present at the top of the module.
>
> Of course perhaps the community would prefer the original Laws first
> format, I'm fine with that emerging as the consensus. Perhaps worthy
> of a separate thread (made it so).
>
> Of course the conjectured users who might most benefit from not being
> intimidated by being exposed to laws before they're ready to understand
> them might not be present on this forum...
>
> --
> -------------- next part --------------
> An HTML attachment was scrubbed...
> URL: <http://mail.haskell.org/pipermail/haskell-cafe/attachments/20210917/a272c422/attachment-0001.html>
>
> ------------------------------
>
> Message: 8
> Date: Thu, 16 Sep 2021 21:10:58 -0400
> From: Chris Smith <cdsmith at gmail.com>
> To: haskell-cafe <haskell-cafe at haskell.org>
> Subject: Re: [Haskell-cafe] Haskell reference documentation, laws
> first or laws last?
> Message-ID:
> <CAPq5PvJ6B9ycvcXOtYzryjRMC8zC1i1k9RwkxPbCZ8tbt=hADg at mail.gmail.com>
> Content-Type: text/plain; charset="utf-8"
>
> For what it's worth, I agree with you both that it's important to document
> the laws, and that it's not the most friendly way to begin the
> documentation for a reader who is unfamiliar with the concept. It's not
> clear to me whether the documentation ought to be optimized for readers who
> are or aren't familiar with the concept, but I lean to the latter, which
> means putting the type class laws at the end (but still easily accessible)
> makes sense to me.
>
> On Thu, Sep 16, 2021 at 7:47 PM Viktor Dukhovni <ietf-dane at dukhovni.org>
> wrote:
>
> > On Thu, Sep 16, 2021 at 06:51:42PM -0400, David Feuer wrote:
> >
> > > The last time I went to look at the laws it took me a couple minutes to
> > > find them. I use them to write instances. Pretty important, IMO.
> >
> > I agree the laws are important to document, I just don't think they
> > belong at the top of the module. The beginner to intermediate users
> > will be using the library and existing instances for some time before
> > they start to write their own instances.
> >
> > If more modules adopt something like the style of the new Data.Foldable,
> > experienced users will know to look for the laws at the end, if not
> > still present at the top of the module.
> >
> > Of course perhaps the community would prefer the original Laws first
> > format, I'm fine with that emerging as the consensus. Perhaps worthy
> > of a separate thread (made it so).
> >
> > Of course the conjectured users who might most benefit from not being
> > intimidated by being exposed to laws before they're ready to understand
> > them might not be present on this forum...
> >
> > --
> > Viktor.
> > _______________________________________________
> > 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.
> -------------- next part --------------
> An HTML attachment was scrubbed...
> URL: <http://mail.haskell.org/pipermail/haskell-cafe/attachments/20210916/018a9ae9/attachment-0001.html>
>
> ------------------------------
>
> Message: 9
> Date: Thu, 16 Sep 2021 21:14:19 -0400
> From: David Feuer <david.feuer at gmail.com>
> To: "haskell-cafe at haskell.org" <haskell-cafe at haskell.org>
> Subject: Re: [Haskell-cafe] Haskell reference documentation, laws
> first or laws last?
> Message-ID:
> <CAMgWh9u=OvrO+xh=Q=U6nUrApMc5QPsF4+bdGJLO40uY9PmdPQ at mail.gmail.com>
> Content-Type: text/plain; charset="utf-8"
>
> I'm not talking about whether they're first or last. They're currently not
> part of the class documentation *at all*. They're only in the
> Data.Traversable documentation.
>
> On Thu, Sep 16, 2021, 7:45 PM Viktor Dukhovni <ietf-dane at dukhovni.org>
> wrote:
>
> > On Thu, Sep 16, 2021 at 06:51:42PM -0400, David Feuer wrote:
> >
> > > The last time I went to look at the laws it took me a couple minutes to
> > > find them. I use them to write instances. Pretty important, IMO.
> >
> > I agree the laws are important to document, I just don't think they
> > belong at the top of the module. The beginner to intermediate users
> > will be using the library and existing instances for some time before
> > they start to write their own instances.
> >
> > If more modules adopt something like the style of the new Data.Foldable,
> > experienced users will know to look for the laws at the end, if not
> > still present at the top of the module.
> >
> > Of course perhaps the community would prefer the original Laws first
> > format, I'm fine with that emerging as the consensus. Perhaps worthy
> > of a separate thread (made it so).
> >
> > Of course the conjectured users who might most benefit from not being
> > intimidated by being exposed to laws before they're ready to understand
> > them might not be present on this forum...
> >
> > --
> > Viktor.
> > _______________________________________________
> > 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.
> -------------- next part --------------
> An HTML attachment was scrubbed...
> URL: <http://mail.haskell.org/pipermail/haskell-cafe/attachments/20210916/e22dcea6/attachment-0001.html>
>
> ------------------------------
>
> Message: 10
> Date: Thu, 16 Sep 2021 21:25:17 -0400
> From: Viktor Dukhovni <ietf-dane at dukhovni.org>
> To: haskell-cafe at haskell.org
> Subject: Re: [Haskell-cafe] Haskell reference documentation, laws
> first or laws last?
> Message-ID: <YUPufa7qQyZ3Q/p4 at straasha.imrryr.org>
> Content-Type: text/plain; charset=us-ascii
>
> On Thu, Sep 16, 2021 at 09:14:19PM -0400, David Feuer wrote:
>
> > I'm not talking about whether they're first or last. They're currently not
> > part of the class documentation *at all*. They're only in the
> > Data.Traversable documentation.
>
> I see, I think you're noting that when re-exported from Prelude, the
> class definitions of Foldable and Traversable that appear in the
> Prelude module:
>
> https://hackage.haskell.org/package/base-4.15.0.0/docs/Prelude.html#g:11
>
> no longer include the laws, you have to look at the underlying module
> to find them. If that's the issue, I should note that the re-exported
> class definitions do have overview hyperlinks:
>
> A more detailed description can be found in the overview section of
> [Data.Foldable](https://hackage.haskell.org/package/base-4.15.0.0/docs/Data-Foldable.html#overview)
>
> A more detailed description can be found in the overview section of
> [Data.Traversable](https://hackage.haskell.org/package/base-4.15.0.0/docs/Data-Traversable.html#overview)
>
> Would your issue be addressed if links to the laws were similarly linked
> from the class definitions?
>
> --
> Viktor.
>
>
> ------------------------------
>
> Message: 11
> Date: Fri, 17 Sep 2021 13:26:48 +1200
> From: Anthony Clayden <anthony.d.clayden at gmail.com>
> To: haskell-cafe at haskell.org
> Subject: Re: [Haskell-cafe] Haskell reference documentation, laws
> first or laws last?
> Message-ID:
> <CABU_mxgfJZMO80MV3ic-kOcy51qKZ1Hn2buxBZuoNT2N2xMyWA at mail.gmail.com>
> Content-Type: text/plain; charset="utf-8"
>
> Hi David,
>
> The Foldable Laws are here
> https://dnssec-stats.ant.isi.edu/~viktor/haskell/docs/libraries/base/Data-Foldable.html#g:21
>
> In the Data-Foldable doco. (There's a menu entry on the sidebar, or
> text search.)
>
> The Data-Traversable doco has only the Traversable Laws.
>
> > I'm not talking about whether they're first or last. They're currently not part of the class documentation *at all*. They're only in the Data.Traversable documentation.
> -------------- next part --------------
> An HTML attachment was scrubbed...
> URL: <http://mail.haskell.org/pipermail/haskell-cafe/attachments/20210917/d1fa931a/attachment-0001.html>
>
> ------------------------------
>
> Message: 12
> Date: Thu, 16 Sep 2021 21:32:29 -0400
> From: Chris Smith <cdsmith at gmail.com>
> To: David Feuer <david.feuer at gmail.com>
> Cc: "haskell-cafe at haskell.org" <haskell-cafe at haskell.org>
> Subject: Re: [Haskell-cafe] Haskell reference documentation, laws
> first or laws last?
> Message-ID:
> <CAPq5PvL9YwVduwsJE8HqH7ARSUmG2XazXZEZrROjP5SFheERbA at mail.gmail.com>
> Content-Type: text/plain; charset="utf-8"
>
> Ah, I misunderstood you as well. I agree that the laws should be included
> in the type class documentation. In fact, most of the documentation from
> the link should probably be moved into the documentation for the class,
> rather than a stand-alone section.
>
> On Thu, Sep 16, 2021 at 9:15 PM David Feuer <david.feuer at gmail.com> wrote:
>
> > I'm not talking about whether they're first or last. They're currently not
> > part of the class documentation *at all*. They're only in the
> > Data.Traversable documentation.
> >
> > On Thu, Sep 16, 2021, 7:45 PM Viktor Dukhovni <ietf-dane at dukhovni.org>
> > wrote:
> >
> >> On Thu, Sep 16, 2021 at 06:51:42PM -0400, David Feuer wrote:
> >>
> >> > The last time I went to look at the laws it took me a couple minutes to
> >> > find them. I use them to write instances. Pretty important, IMO.
> >>
> >> I agree the laws are important to document, I just don't think they
> >> belong at the top of the module. The beginner to intermediate users
> >> will be using the library and existing instances for some time before
> >> they start to write their own instances.
> >>
> >> If more modules adopt something like the style of the new Data.Foldable,
> >> experienced users will know to look for the laws at the end, if not
> >> still present at the top of the module.
> >>
> >> Of course perhaps the community would prefer the original Laws first
> >> format, I'm fine with that emerging as the consensus. Perhaps worthy
> >> of a separate thread (made it so).
> >>
> >> Of course the conjectured users who might most benefit from not being
> >> intimidated by being exposed to laws before they're ready to understand
> >> them might not be present on this forum...
> >>
> >> --
> >> Viktor.
> >> _______________________________________________
> >> 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.
> -------------- next part --------------
> An HTML attachment was scrubbed...
> URL: <http://mail.haskell.org/pipermail/haskell-cafe/attachments/20210916/7fb33ad0/attachment-0001.html>
>
> ------------------------------
>
> Message: 13
> Date: Thu, 16 Sep 2021 21:33:02 -0400
> From: David Feuer <david.feuer at gmail.com>
> To: "haskell-cafe at haskell.org" <haskell-cafe at haskell.org>
> Subject: Re: [Haskell-cafe] Haskell reference documentation, laws
> first or laws last?
> Message-ID:
> <CAMgWh9vv2QQYusOs5HotmjHb+PGZZtsd_mvGx-e-h=HYU0WCZQ at mail.gmail.com>
> Content-Type: text/plain; charset="utf-8"
>
> The laws of any sensible class are an essential and integral part of it.
> Without them, you just have ad hoc overloading. They shouldn't be relegated
> to the canonical exporting module.
>
> On Thu, Sep 16, 2021, 9:27 PM Viktor Dukhovni <ietf-dane at dukhovni.org>
> wrote:
>
> > On Thu, Sep 16, 2021 at 09:14:19PM -0400, David Feuer wrote:
> >
> > > I'm not talking about whether they're first or last. They're currently
> > not
> > > part of the class documentation *at all*. They're only in the
> > > Data.Traversable documentation.
> >
> > I see, I think you're noting that when re-exported from Prelude, the
> > class definitions of Foldable and Traversable that appear in the
> > Prelude module:
> >
> >
> > https://hackage.haskell.org/package/base-4.15.0.0/docs/Prelude.html#g:11
> >
> > no longer include the laws, you have to look at the underlying module
> > to find them. If that's the issue, I should note that the re-exported
> > class definitions do have overview hyperlinks:
> >
> > A more detailed description can be found in the overview section of
> > [Data.Foldable](
> > https://hackage.haskell.org/package/base-4.15.0.0/docs/Data-Foldable.html#overview
> > )
> >
> > A more detailed description can be found in the overview section of
> > [Data.Traversable](
> > https://hackage.haskell.org/package/base-4.15.0.0/docs/Data-Traversable.html#overview
> > )
> >
> > Would your issue be addressed if links to the laws were similarly linked
> > from the class definitions?
> >
> > --
> > Viktor.
> > _______________________________________________
> > 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.
> -------------- next part --------------
> An HTML attachment was scrubbed...
> URL: <http://mail.haskell.org/pipermail/haskell-cafe/attachments/20210916/8b4e884e/attachment-0001.html>
>
> ------------------------------
>
> Message: 14
> Date: Thu, 16 Sep 2021 21:56:37 -0400
> From: Viktor Dukhovni <ietf-dane at dukhovni.org>
> To: "haskell-cafe at haskell.org" <haskell-cafe at haskell.org>
> Subject: Re: [Haskell-cafe] Haskell reference documentation, laws
> first or laws last?
> Message-ID: <A1755A1A-2B38-4A24-B52F-55D1E6809C3F at dukhovni.org>
> Content-Type: text/plain; charset=us-ascii
>
> > On 16 Sep 2021, at 9:33 pm, David Feuer <david.feuer at gmail.com> wrote:
> >
> > The laws of any sensible class are an essential and integral part of it. Without them, you just have ad hoc overloading. They shouldn't be relegated to the canonical exporting module.
>
> Surely a one click link from the Prelude re-export is no worse than a 1-click link
> in the module table of contents?
>
> I am rather reluctant beat new readers over the head with laws that often are much
> too abstract to add clarity.
>
> --
> Viktor.
>
>
>
> ------------------------------
>
> Message: 15
> Date: Thu, 16 Sep 2021 22:13:27 -0400
> From: Sebastiaan Joosten <sjcjoosten+haskell at gmail.com>
> To: "haskell-cafe at haskell.org" <haskell-cafe at haskell.org>
> Subject: Re: [Haskell-cafe] Haskell reference documentation, laws
> first or laws last?
> Message-ID:
> <CABhTcUsUOZ9tqeoHRTUnz6ggC1N45yJF1WWP5X+xXtwxMOKFvA at mail.gmail.com>
> Content-Type: text/plain; charset="utf-8"
>
> I personally like it if the documentation of re-exported classes just
> contain a summary, much like Data.Foldable does. The prelude documentation
> is quite long already. I would not object to making the links stand out a
> bit more though: a title 'More detailed descriptions' with a bulleted
> summary to 'laws' might do that.
> On where the laws need to be: I think for foldable the right decision is
> made, there may be exceptions but I typically like to hear about the ideas
> behind things before I dive into the algebraic characterization.
>
> Also, many thanks to the write-up of Foldable.
>
> Best,
> Sebastiaan
>
> On Thu, Sep 16, 2021 at 9:36 PM Chris Smith <cdsmith at gmail.com> wrote:
>
> > Ah, I misunderstood you as well. I agree that the laws should be included
> > in the type class documentation. In fact, most of the documentation from
> > the link should probably be moved into the documentation for the class,
> > rather than a stand-alone section.
> >
> > On Thu, Sep 16, 2021 at 9:15 PM David Feuer <david.feuer at gmail.com> wrote:
> >
> >> I'm not talking about whether they're first or last. They're currently
> >> not part of the class documentation *at all*. They're only in the
> >> Data.Traversable documentation.
> >>
> >> On Thu, Sep 16, 2021, 7:45 PM Viktor Dukhovni <ietf-dane at dukhovni.org>
> >> wrote:
> >>
> >>> On Thu, Sep 16, 2021 at 06:51:42PM -0400, David Feuer wrote:
> >>>
> >>> > The last time I went to look at the laws it took me a couple minutes to
> >>> > find them. I use them to write instances. Pretty important, IMO.
> >>>
> >>> I agree the laws are important to document, I just don't think they
> >>> belong at the top of the module. The beginner to intermediate users
> >>> will be using the library and existing instances for some time before
> >>> they start to write their own instances.
> >>>
> >>> If more modules adopt something like the style of the new Data.Foldable,
> >>> experienced users will know to look for the laws at the end, if not
> >>> still present at the top of the module.
> >>>
> >>> Of course perhaps the community would prefer the original Laws first
> >>> format, I'm fine with that emerging as the consensus. Perhaps worthy
> >>> of a separate thread (made it so).
> >>>
> >>> Of course the conjectured users who might most benefit from not being
> >>> intimidated by being exposed to laws before they're ready to understand
> >>> them might not be present on this forum...
> >>>
> >>> --
> >>> Viktor.
> >>> _______________________________________________
> >>> 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.
> >
> > _______________________________________________
> > 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.
> -------------- next part --------------
> An HTML attachment was scrubbed...
> URL: <http://mail.haskell.org/pipermail/haskell-cafe/attachments/20210916/528c7734/attachment.html>
>
> ------------------------------
>
> Subject: Digest Footer
>
> _______________________________________________
> Haskell-Cafe mailing list
> Haskell-Cafe at haskell.org
> http://mail.haskell.org/cgi-bin/mailman/listinfo/haskell-cafe
>
>
> ------------------------------
>
> End of Haskell-Cafe Digest, Vol 217, Issue 17
> *********************************************
More information about the Haskell-Cafe
mailing list