bug#31052: 26.0.91; Improve documentation of inline-letevals

[Lars Ingebrigtsen]

Eli Zaretskii <eliz@gnu.org> writes:

>> The main question the existing documentation doesn't answer is what the
>> purpose of inline-letevals is and why it should be used instead of 'let'.
>
> OK, but in that case we need only add a single sentence:
>
>   This provides a convenient way to ensure that the arguments to an
>   inlined function are evaluated exactly once, as well as to create
>   local variables.
>
>> The misleading part of the existing documentation is that it describes
>> inline-letevals as similar to 'let' without mentioning that it does a
>> completely different thing to symbols in the binding list.
>
> The only part of your change that I perceive as related to this is the
> following sentence:
>
>   When an element of @var{bindings} is just a symbol @var{var}, the
>   result of evaluating @var{var} is re-bound to @var{var}.

I agree with Gemini that the description of inline-letevals was
confusing, and I also agree with Eli that the proposed patch was also
confusing.  :-)

So I've taken Eli's suggestion, and the sentence above and added them to
the manual, as well as adding a bit more text to explain what it's
doing, and where it differs from `let', and pushed to Emacs 28.

-- 
(domestic pets only, the antidote for overdose, milk.)
   bloggy blog: http://lars.ingebrigtsen.no