Subject: bug#34842: 26.1; Alist documentation: let-alist

From: "Basil L. Contovounesios" <[email-masked]>
Date: Sun, 13 Oct 2019 13:38:09 +0100

Eli Zaretskii <[email-masked]> writes:

>> From: Lars Ingebrigtsen <[email-masked]>
>> Date: Sun, 13 Oct 2019 04:48:11 +0200
>> Cc: [email-masked], Sebastián Monía
>>  <[email-masked]>
>> 
>> "Basil L. Contovounesios" <[email-masked]> writes:
>> 
>> > Thanks.  The following constitute what I think are some opportunities
>> > for clarifying the current doc.  WDYT?
>> 
>> Looks good to me, but:
>
> I have one more nit: why was @dots{} added after @var{body} in the
> @defmac line?  There's only one body here, isn't it?

There's only one body indeed, but it comprises multiple forms.
The Elisp manual currently contains over 50 occurrences of body...,
including the following:

 -- Macro: dolist (var list [result]) body...
 -- Special Form: catch tag body...
 -- Macro: ignore-errors body...
 -- Macro: defun name args [doc] [declare] [interactive] body...
 -- Macro: lambda args [doc] [interactive] body...
 -- Macro: defsubst name args [doc] [declare] [interactive] body...     
 -- Macro: defmacro name args [doc] [declare] body...
 -- Macro: with-eval-after-load library body...
 -- Special Form: eval-when-compile body...

Whereas it only contains 7 occurrences of '&rest body':

 -- Macro: pcase-defmacro name args [doc] &rest body
 -- Macro: with-connection-local-variables &rest body
 -- Macro: gv-define-setter name arglist &rest body
 -- Macro: gv-letplace (getter setter) place &rest body
 -- Macro: minibuffer-with-setup-hook function &rest body
 -- Macro: with-coding-priority coding-systems &rest body...
 -- Macro: with-temp-message message &rest body

[Note that with-coding-priority uses both &rest and body...]

And let-alist is the only occurrence of a body without either &rest or
an ellipsis:

 -- Macro: let-alist alist body

Of course there is also the forms... style, of which there are under 20
occurrences, including:

 -- Special Form: progn forms...
 -- Special Form: if condition then-form else-forms...
 -- Macro: when condition then-forms...
 -- Macro: unless condition forms...
 -- Special Form: while condition forms...
 -- Special Form: let (bindings...) forms...

I don't mind which style is preferred, but let-alist should probably
pick one of the existing ones, right?  Any preference?

Thanks,

-- 
Basil