Re: master 2e9111813b: Add two classic Common Lisp macro-writing macros

[Sean Whitton]

Hello,

Thank you for looking!

On Tue 12 Apr 2022 at 10:25pm +03, Eli Zaretskii wrote:

>> +This macro expands to code that executes @var{body} with each of the
>> +variables in @var{names} bound to a fresh uninterned symbol or
>> +``gensym''.
>
> Instead of "or" I suggest to say "a.k.a.@: @dfn{gensym}" (and add a
> @cindex entry for "gensym", as usual with any term in @dfn).

I've changed this to something else, but I'd prefer not to use an
abbreviation like "a.k.a.".  Thanks for pointing out @dfn.

>> +@defmac cl-once-only ((name form)@dots{}) body@dots{}
>> +This macro is primarily to help the macro programmer ensure that forms
>> +supplied by the user of the macro are evaluated just once by its
>> +expansion even though the result of evaluating the form is to occur
>> +more than once.  Less often, this macro is used to ensure that forms
>> +supplied by the macro programmer are evaluated just once.
>> +
>> +Each @var{name} is a variable which can be used to refer to the result
>> +of evaluating @var{form} in @var{body}.  @code{cl-once-only} binds
>> +each @var{name} to a fresh uninterned symbol during the evaluation of
>> +@var{body}.
>
> My recommendation is always to try to name parameters after their
> roles.  In this case, I'd use VAR or VARIABLE instead of the less
> specific NAME.  Then you could make the text shorter and thus clearer:
>
>   Each @var{variable} can be used to refer to the result of evaluating
>   @var{form} in @var{body}.  @code{cl-once-only} binds each
>   @var{variable} to a fresh uninterned symbol...

Yes, that's better.

> (And why not use "gensym" instead of the wordier "uninterned symbol"?
> that's why you introduced that terminology, right?)

I wanted to use "gensym" in the description of cl-with-gensyms because
of the name of that macro.  But otherwise, I was thinking that it's a
less familiar term in Elisp than it is in CL, and that "uninterned
symbol" was the most familiar Elisp term.  I don't mind changing it if
you think that's not so much of a concern.

>>            Then, @code{cl-once-only} wraps the final expansion in
>> +code to evaluate each @var{form} and bind it to the corresponding
>> +uninterned symbol.
>
> How can a form be bound to a symbol?

In this case it should say that the result of evaluation is bound to the
corresponding uninterned symbol, thanks.

In general, I would describe (let ((x '(+ 1 2))) ...) as a case where a
form is bound to a symbol -- would you describe that differently?

Revised patch attached.

-- 
Sean Whitton

0001-Document-additions-of-cl-with-gensyms-and-cl-once-on.patch
Description: Text Data