unofficial mirror of bug-gnu-emacs@gnu.org 
 help / color / mirror / code / Atom feed
* bug#31052: 26.0.91; Improve documentation of inline-letevals
@ 2018-04-04  0:33 Gemini Lasswell
  2018-04-04  6:45 ` Eli Zaretskii
  0 siblings, 1 reply; 9+ messages in thread
From: Gemini Lasswell @ 2018-04-04  0:33 UTC (permalink / raw)
  To: 31052

[-- 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


^ permalink raw reply related	[flat|nested] 9+ messages in thread

end of thread, other threads:[~2020-08-22 15:59 UTC | newest]

Thread overview: 9+ messages (download: mbox.gz follow: Atom feed
-- links below jump to the message on this page --
2018-04-04  0:33 bug#31052: 26.0.91; Improve documentation of inline-letevals Gemini Lasswell
2018-04-04  6:45 ` Eli Zaretskii
2018-04-04 13:18   ` Andy Moreton
2018-04-04 14:06     ` Eli Zaretskii
2018-04-05  1:12       ` Stefan Monnier
2018-04-04 17:10   ` Gemini Lasswell
2018-04-05  9:54     ` Eli Zaretskii
2018-04-06 20:29       ` Gemini Lasswell
2020-08-22 15:59       ` Lars Ingebrigtsen

Code repositories for project(s) associated with this public inbox

	https://git.savannah.gnu.org/cgit/emacs.git

This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).