On Thu, Nov 14 2024, Joost Kremers wrote:
> On Thu, Nov 14 2024, Eli Zaretskii wrote:
>>> From: Joost Kremers <joostkremers@fastmail.fm>
>>> I ended up putting it in the description of the first macro (`if-let*`) and
>>> referring to it in the others, because the relevant variable (here SPEC) is
>>> actually called VARLIST in `if-let*`, `when-let*` and `and-let*`, but SPEC
>>> in while-let. (The non-starred versions also have SPEC, but they're being
>>> deprecated. BTW, any reason why `while-let` isn't called `while-let*`?)
>>
>> The disadvantage of what you did is that you need to say repeatedly
>>
>>   @var{varlist} has the same form as in @code{if-let*}.
>>
>> and the reader has to go back, read the description of if-let* (which
>> she might not want to know anything about), and decide which parts of
>> that description are relevant to whatever macro she is interested in.
>
> Okay, so I'll put the explanation of VARLIST into the description of every
> macro.
>

Here's the new patch (finally...) `when-let*`, `and-let*` and `while-let`
now have an additional paragraph saying:

```
@var{varlist} has the same form as in @code{if-let*}: Each element of
@code{varlist} has the form @w{@code{(@var{symbol} @var{value-form})}}, in
which @var{value-form} is evaluated and @var{symbol} is locally bound to
the result. Bindings are sequential, as in @code{let*} (@pxref{Local
Variables}). As a special case, @var{symbol} can be omitted if only the
test result of @var{value-form} is of interest: @var{value-form} is
evaluated and checked for @code{nil}, but its value is not bound. ```

I agree this is better when you only want to read up on a single macro, but
it's arguably less pretty when you're reading through the entire section,
having to read the same thing four times... For that case, I pointed out
that VARLIST is the same as for `if-let*`, so a reader knows they can skip
that paragraph and won't have to wonder if there are subtle differences
between the macros.

-- 
Joost Kremers
Life has its moments