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

* bug#31052: 26.0.91; Improve documentation of inline-letevals
  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 17:10   ` Gemini Lasswell
  0 siblings, 2 replies; 9+ messages in thread
From: Eli Zaretskii @ 2018-04-04  6:45 UTC (permalink / raw)
  To: Gemini Lasswell; +Cc: 31052

> From: Gemini Lasswell <gazally@runbox.com>
> Date: Tue, 03 Apr 2018 17:33:31 -0700
> 
> 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.

Thanks, but your text left me confused, perhaps because it mixes the
details of the syntax and semantics with the explanation of why and
how to use them, and what is the result of such usage.  These should
be generally kept separate for clarity.

How about if you first tell informally what information is missing
from the original text, and then we see how to augment that by adding
the missing bits?





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

* bug#31052: 26.0.91; Improve documentation of inline-letevals
  2018-04-04  6:45 ` Eli Zaretskii
@ 2018-04-04 13:18   ` Andy Moreton
  2018-04-04 14:06     ` Eli Zaretskii
  2018-04-04 17:10   ` Gemini Lasswell
  1 sibling, 1 reply; 9+ messages in thread
From: Andy Moreton @ 2018-04-04 13:18 UTC (permalink / raw)
  To: 31052

On Wed 04 Apr 2018, Eli Zaretskii wrote:

>> From: Gemini Lasswell <gazally@runbox.com>
>> Date: Tue, 03 Apr 2018 17:33:31 -0700
>> 
>> 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.
>
> Thanks, but your text left me confused, perhaps because it mixes the
> details of the syntax and semantics with the explanation of why and
> how to use them, and what is the result of such usage.  These should
> be generally kept separate for clarity.
>
> How about if you first tell informally what information is missing
> from the original text, and then we see how to augment that by adding
> the missing bits?

The same node in the elisp manual has this:

   Functions defined via ‘define-inline’ have several advantages with
respect to macros defined by ‘defsubst’ or ‘defmacro’:

and this:

   − They behave in a more predictable way than ‘cl-defsubst’ (*note
     (cl)Argument Lists::).

It would be more consistent to use defsubst or cl-defsubst in both
places.

Also, while looking at inline-letevals in inline.el, I noticed that the
preceeding macros inline--leteval and inline--letlisteval mention the
wrong symbol name in their error messages:

(defmacro inline--leteval (_var-exp &rest _body)
  (declare (indent 1) (debug (sexp &rest body)))
  (error "inline-letevals can only be used within define-inline"))

(defmacro inline--letlisteval (_list &rest _body)
  (declare (indent 1) (debug (sexp &rest body)))
  (error "inline-letevals can only be used within define-inline"))

Perhaps these typos can be fixed before the release.

    AndyM






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

* bug#31052: 26.0.91; Improve documentation of inline-letevals
  2018-04-04 13:18   ` Andy Moreton
@ 2018-04-04 14:06     ` Eli Zaretskii
  2018-04-05  1:12       ` Stefan Monnier
  0 siblings, 1 reply; 9+ messages in thread
From: Eli Zaretskii @ 2018-04-04 14:06 UTC (permalink / raw)
  To: Andy Moreton, Stefan Monnier; +Cc: 31052

> From: Andy Moreton <andrewjmoreton@gmail.com>
> Date: Wed, 04 Apr 2018 14:18:32 +0100
> 
> Also, while looking at inline-letevals in inline.el, I noticed that the
> preceeding macros inline--leteval and inline--letlisteval mention the
> wrong symbol name in their error messages:
> 
> (defmacro inline--leteval (_var-exp &rest _body)
>   (declare (indent 1) (debug (sexp &rest body)))
>   (error "inline-letevals can only be used within define-inline"))
> 
> (defmacro inline--letlisteval (_list &rest _body)
>   (declare (indent 1) (debug (sexp &rest body)))
>   (error "inline-letevals can only be used within define-inline"))
> 
> Perhaps these typos can be fixed before the release.

It's not too late for that, but I'm not sure this is a typo.  It could
be deliberate.

Stefan, can you comment on this, please?






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

* bug#31052: 26.0.91; Improve documentation of inline-letevals
  2018-04-04  6:45 ` Eli Zaretskii
  2018-04-04 13:18   ` Andy Moreton
@ 2018-04-04 17:10   ` Gemini Lasswell
  2018-04-05  9:54     ` Eli Zaretskii
  1 sibling, 1 reply; 9+ messages in thread
From: Gemini Lasswell @ 2018-04-04 17:10 UTC (permalink / raw)
  To: Eli Zaretskii; +Cc: 31052


Eli Zaretskii writes:

> How about if you first tell informally what information is missing
> from the original text, and then we see how to augment that by adding
> the missing bits?

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'.
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.





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

* bug#31052: 26.0.91; Improve documentation of inline-letevals
  2018-04-04 14:06     ` Eli Zaretskii
@ 2018-04-05  1:12       ` Stefan Monnier
  0 siblings, 0 replies; 9+ messages in thread
From: Stefan Monnier @ 2018-04-05  1:12 UTC (permalink / raw)
  To: Eli Zaretskii; +Cc: 31052, Andy Moreton

>> Also, while looking at inline-letevals in inline.el, I noticed that the
>> preceeding macros inline--leteval and inline--letlisteval mention the
>> wrong symbol name in their error messages:
>> 
>> (defmacro inline--leteval (_var-exp &rest _body)
>>   (declare (indent 1) (debug (sexp &rest body)))
>>   (error "inline-letevals can only be used within define-inline"))
>> 
>> (defmacro inline--letlisteval (_list &rest _body)
>>   (declare (indent 1) (debug (sexp &rest body)))
>>   (error "inline-letevals can only be used within define-inline"))
>> 
>> Perhaps these typos can be fixed before the release.
>
> It's not too late for that, but I'm not sure this is a typo.  It could
> be deliberate.
>
> Stefan, can you comment on this, please?

Good catch: these aren't typos!

The inline-letevals macro expands to calls to inline--leteval and
inline--letlisteval and it's easier to have those signal the error than
to make inline-letevals check whether we're within a define-inline.

The user is not supposed to use  inline--leteval or inline--letlisteval
manually anywhere at all (as indicated by the "--" in their name), so if
those occur it's (presumably) because of an incorrect use of
inline-letevals.

I'll add a comment about it, to stop other people from trying to "fix" it.


        Stefan





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

* bug#31052: 26.0.91; Improve documentation of inline-letevals
  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
  0 siblings, 2 replies; 9+ messages in thread
From: Eli Zaretskii @ 2018-04-05  9:54 UTC (permalink / raw)
  To: Gemini Lasswell; +Cc: 31052

> From: Gemini Lasswell <gazally@runbox.com>
> Cc: 31052@debbugs.gnu.org
> Date: Wed, 04 Apr 2018 10:10:39 -0700
> 
> > How about if you first tell informally what information is missing
> > from the original text, and then we see how to augment that by adding
> > the missing bits?
> 
> 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}.

Is this what caused you to say it "does a completely different thing
to symbols in the binding list"?  Or did I misunderstand?

Thanks.





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

* bug#31052: 26.0.91; Improve documentation of inline-letevals
  2018-04-05  9:54     ` Eli Zaretskii
@ 2018-04-06 20:29       ` Gemini Lasswell
  2020-08-22 15:59       ` Lars Ingebrigtsen
  1 sibling, 0 replies; 9+ messages in thread
From: Gemini Lasswell @ 2018-04-06 20:29 UTC (permalink / raw)
  To: Eli Zaretskii; +Cc: 31052


Eli Zaretskii writes:

>   When an element of @var{bindings} is just a symbol @var{var}, the
>   result of evaluating @var{var} is re-bound to @var{var}.
>
> Is this what caused you to say it "does a completely different thing
> to symbols in the binding list"?  Or did I misunderstand?
>

What caused me to say it does a completely different thing is that,
for example, if VAR is bound to 3 in an outside scope, inside:

(let (var) ...)

it will be bound to nil.  But inside

(inline-letevals (var) ...)

it will be bound to 3.  And if VAR is unbound in the outside scope,
let will bind it to nil and inline-letevals will signal an error.

It's occurred to me while writing this that

(inline-letevals (var) ...)

behaves much like

(let ((var (eval var))) ...)

although I'm not sure how to turn that into a concise explanation for
the documentation.





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

* bug#31052: 26.0.91; Improve documentation of inline-letevals
  2018-04-05  9:54     ` Eli Zaretskii
  2018-04-06 20:29       ` Gemini Lasswell
@ 2020-08-22 15:59       ` Lars Ingebrigtsen
  1 sibling, 0 replies; 9+ messages in thread
From: Lars Ingebrigtsen @ 2020-08-22 15:59 UTC (permalink / raw)
  To: Eli Zaretskii; +Cc: Gemini Lasswell, 31052

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





^ permalink raw reply	[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).