bug#59559: 28.1; `minibuffer-with-setup-hook' with :append

[Drew Adams]

> Drew, thanks for your elaborations.

You're welcome.  Thanks for working on this.

> I don't have a strong opinion.  I can follow your thoughts, but I'm also
> not really convinced that writing that all out in the docstring is
> necessary.
> 
> So I would like to leave it up to you two to find a final agreement.

Eli has now decided - apparently it's "won't fix".

FWIW, I think this kind of interface is inherently
problematic (for the reasons I gave).  It's not
similar to, say, `add-hook', where APPEND can be
an optional arg.  (Nor is it like CL keyword args.)

No one has any trouble understanding that a macro
like `with-current-buffer' evals its first arg,
so no special need for the doc to point that out.
If this case were like that (and others, similar)
I wouldn't have filed the bug report.

It's the use by `minibuffer-with-setup-hook' of
the same arg with two forms, and with evaluation
not always of that arg but sometimes of just part
of it -- that's what makes it problematic for the
doc to just talk about FUN being a function.  IMO
the doc does _need_ to talk about how the arg is
handled (evaluated).

FWIW, I would have just had two macros, instead
of fiddling with a special kind of arg:

1. `with-mbuf-setup-hook-add'  (or
   `with-mbuf-setup-hook-prepend')

2. `with-mbuf-setup-hook-append'


That also uses fewer chars:

(with-mbuf-setup-hook-append #'toto ...)

(minibuffer-with-setup-hook (:append #'toto) ...)


Even if "minibuffer" is spelled out it's shorter:

(with-minibuffer-setup-hook-append #'toto ...)

And starting with "with-" fits what we do with
other, similar macros.