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

[Gemini Lasswell <gazally@runbox.com>]

[-- Attachment #1: Type: text/plain, Size: 386 bytes --]

I just got acquainted with inline-letevals and found its description
in the Elisp manual confusing because the purpose of the macro is not
stated, and it is described as similar to 'let' without mention of an
important difference in what happens to the elements of the bindings
list which are symbols.

Here's a patch to functions.texi where I've attempted to clarify the
description.


[-- Attachment #2: 0001-Improve-documentation-of-inline-letevals.patch --]
[-- Type: text/plain, Size: 2206 bytes --]

From c1214913731b37c0444f8953a9b2a7619f22b2a9 Mon Sep 17 00:00:00 2001
From: Gemini Lasswell <gazally@runbox.com>
Date: Tue, 3 Apr 2018 13:12:15 -0700
Subject: [PATCH] Improve documentation of inline-letevals

* doc/lispref/functions.texi (Defining Functions): Clarify what
'inline-letevals' is used for and how it differs from 'let'.
---
 doc/lispref/functions.texi | 22 +++++++++++++---------
 1 file changed, 13 insertions(+), 9 deletions(-)

diff --git a/doc/lispref/functions.texi b/doc/lispref/functions.texi
index 78372a8a10..a6187eb628 100644
--- a/doc/lispref/functions.texi
+++ b/doc/lispref/functions.texi
@@ -714,15 +714,19 @@ Defining Functions
 @end defmac
 
 @defmac inline-letevals (bindings@dots{}) body@dots{}
-This is similar to @code{let} (@pxref{Local Variables}): it sets up
-local variables as specified by @var{bindings}, and then evaluates
-@var{body} with those bindings in effect.  Each element of
-@var{bindings} should be either a symbol or a list of the form
-@w{@code{(@var{var} @var{expr})}}; the result is to evaluate
-@var{expr} and bind @var{var} to the result.  The tail of
-@var{bindings} can be either @code{nil} or a symbol which should hold
-a list of arguments, in which case each argument is evaluated, and the
-symbol is bound to the resulting list.
+Execute @var{body} in the context of @var{bindings}.  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.  Each
+element of @var{bindings} should be either a symbol or a list of the
+form @w{@code{(@var{var} @var{expr})}}.  Elements of the form
+@w{@code{(@var{var} @var{expr})}} work as in @code{let} (@pxref{Local
+Variables}) to set up local variables by binding each symbol @var{var}
+to the result of evaluating @var{expr}.  When an element of
+@var{bindings} is just a symbol @var{var}, the result of evaluating
+@var{var} is re-bound to @var{var}.  The tail of @var{bindings} can be
+either @code{nil} or a symbol which should hold a list of arguments,
+in which case each argument is evaluated, and the symbol is bound to
+the resulting list.
 @end defmac
 
 @defmac inline-const-p expression
-- 
2.15.0