Heya,

On Sun Feb 12, 2023 at 6:05 PM GMT, Ludovic Courtès wrote:
> Like Chris, I’m wary of acronyms (they can easily make things
> impenetrable) so I’d write:
>
>   - the `with-store` macro and the `run-with-store` procedure
>   - the related monad interface

Wow, I really did use 'API' quite a lot... Oops :)

> I agree with Chris’s comment: a few sentences of a higher-level intro
> showing where this fits in the big picture would be great!

Okay, I'll try to figure something out for that.

> It would be nice to stress, also, that one doesn’t _need_ to know about
> monads to use the various programming interfaces of Guix; instead, it’s
> a thing for someone who’d like to get a deep dive into the internals of
> Guix.

Fair enough :)

> Maybe add something like “For example, one might write a function that
> divides two integers such that it returns special value `nothing` when
> the divisor is zero, and `maybe 5` when passed `15` and `3`.”  (I
> couldn’t think of a better example but you get the idea.  :-))

Okay.

> > +feature of strongly-typed functional languages, and you'll see it all over the
>
> s/strongly/statically/  :-)

Ahh, that's why everyone was pointing out the wording :)

> In Scheme we use #f, not '(), to denote “Nothing”.

Mhm, not sure why I added '() in retrospect.

> Maybe “First, let’s import that module:”?

Too much 'API'... :)

> “To define a monad in Guix, we use `define-monad`”
>
> (In general, I’d avoid “simply” because whether it’s “simple” depends on
> one’s background.)

Ah, of course.  I should've remembered this from last time :)

> s/these laws/the so-called _monad laws_/

Good idea.

> Should it be “⇒ #t” instead of “;; #t”, to follow the convention used in
> the manual and in other places?

That's much nicer, yeah.

> s/monad API/monad module/ (or “monad library”)

(insert thumbs up emoji here)

> > +   strong types or an interface-like system.
>
> “static types”?

Yep.

> s/This API/The `(guix monads)` module/

Okay.

> Maybe link to the “The Store Monad” section of the manual here or
> earlier?

Oh, did I not link to it before, in the "Lies, Damned Lies, and Abstractions"
section!?

* unmatched-paren checks

...oops.

> I feel we’re asking a lot of work from you, but hopefully the result
> will be even more pleasant.  I guess v4 will be ready to go!

Hopefully! :)

> Thanks for all the work,

And thanks for all your own work! :)

    -- (