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

[Andy Moreton <andrewjmoreton@gmail.com>]

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