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

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

[Gemini Lasswell]

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

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

[Eli Zaretskii]

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

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

[Andy Moreton]

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

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

[Eli Zaretskii]

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

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

[Stefan Monnier]

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

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

[Gemini Lasswell]

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.

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

[Eli Zaretskii]

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

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

[Gemini Lasswell]

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.

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