Re: `thunk-let'?

[Eli Zaretskii <eliz@gnu.org>]

> From: Michael Heerdegen <michael_heerdegen@web.de>
> Cc: emacs-devel@gnu.org
> Date: Thu, 23 Nov 2017 05:15:44 +0100
> 
> Michael Heerdegen <michael_heerdegen@web.de> writes:
> 
> > This helped a lot.  My first version even compiled without error.  I'll
> > post the updated patch soon.
> 
> Ok, here is what I have, with everything discusses included (see also
> attached).  I will proofread it once more, maybe others will want to
> have a look in the meantime, too.

My comments below.

> +@defmac thunk-delay forms...

Please use "forms@dots{}" instead, it produces a prettier ellipsis.

> +Return a thunk for evaluating the @var{forms}.  A thunk is a closure
> +that evaluates the @var{forms} in the lexical environment present when
> +@code{thunk-delay} had been called.

This could be improved as follows:

  @cindex thunk
  Return a @dfn{thunk} for evaluating the @var{forms}.  A thunk is a
  closure (@pxref{Closures}) that evaluates the @var{forms} in the
  lexical environment present when @code{thunk-delay} had been called.

The improvements are:

  . you introduce a new term, so it should be in @dfn, and an index
    entry for it is in order
  . you mention "closures", so a cross-reference to where these are
    described is a Good Thing, because the reader might not know or
    remember what that is

> +@code{thunk-delay} had been called.

"had been called" or "will be called"?

> +@defun thunk-force thunk
> +Force @var{thunk} to perform the evaluation of the forms specified to the
> +@code{thunk-delay} that created the thunk.

"to the thunk-delay" or "in the thunk-delay" (or "for the thunk-delay")?

> +of the last form is returned.  The @var{thunk} also "remembers" that it has

Quoting in Texinfo is ``like this'' (I guess you didn't use the Emacs
Texinfo mode, or typed `C-q "' here.)  makeinfo will then convert
these to the actual quote characters.

> +been forced: Any further calls of @code{thunk-force} on the same @var{thunk}
                                                        ^^
"with"

> +@defmac lazy-let (bindings...) forms...

@dots{} again

> +This macro is analogous to @code{let} but creates "lazy" variable

``lazy''.

> +bindings.  Any binding has the form (@var{symbol} @var{value-form}).

The entire parenthesized expression should be in @code:

  @code{(@var{symbol} @var{value-form})}

I also recommend to wrap that in @w, so that it doesn't get split
between two lines, like this:

  @w{@code{(@var{symbol} @var{value-form})}}

> +@group
> +(f 12)
> +@print{} "Calculating 1 plus 2 times 12"
> +25

This 25 should have @result{} before it, right?

> +to set them (e.g.@ with @code{setq}).

You mean "e.g.@:", right?

> +@defmac lazy-let* (bindings...) forms...

@dots{}

> +binding expressions.  All references to the original variables in the
> +body @var{forms} are then replaced by an expression that calls
> +@code{thunk-force} on the according helper variable.  So, any code

"calls ... on" is slightly awkward English, I think.  How about "calls
thunk-force passing it the according helper variable as an argument",
or calls thunk-force with the according helper variable as the
argument" instead?

> +** Thunk
> +*** The new macros 'thunk-let' and 'thunk-let*' are analogue to `let'
> +and `let*' but create bindings that are evaluated lazily.

I think this should be a single-level entry:

  ** New macros 'thunk-let' and 'thunk-let*'.
  These macros are analogue to `let' and `let*', but create bindings
  that are evaluated lazily.

Thanks again for working on this.