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

[Eli Zaretskii <eliz@gnu.org>]

> From: Drew Adams <drew.adams@oracle.com>
> CC: "59559@debbugs.gnu.org" <59559@debbugs.gnu.org>
> Date: Sat, 21 Jan 2023 18:51:25 +0000
> 
> > How about just adding the obvious to the first sentence:
> > 
> >   Temporarily add function FUN to `minibuffer-setup-hook' while executing
> >   BODY.
> 
> To me, that doesn't help at all.  And as you would
> (usually) say, "function FUN" can just be replaced
> by "FUNCTION" there.

That's a tangent.  Let's keep our focus where it belongs.

> Just saying that the first arg is a function doesn't
> solve the problem.  What is the first arg, exactly?
> Is it evaluated?

How is this different from the below:

  expand-file-name is a built-in function in ‘C source code’.

  (expand-file-name NAME &optional DEFAULT-DIRECTORY)

  Convert filename NAME to absolute, and canonicalize it.
  [...]
  NAME should be a string [...]

Since when do we ask about function's arguments whether they are
evaluated or not? and why for that particular function and not for
others?

> It's a sexp.  Either that sexp is a list `(:append F)',
> in which case only F is evaluated, to provide the
> function to add (append), or the entire FUN sexp is
> evaluated to provide the function to add (prepend).

You are splitting hair.  Once again, saying that an argument can (or
should) be of some form is a paradigm we use a lot in our doc strings,
and this case is not different.

> It's this unusual behavior that needs to be understood,
> and thus described - in particular pointing out that
> the arg isn't just evaluated to begin with.

No, it isn't unusual.

> > All the rest sounds clear to me, and I find the original text less
> > confusing than your proposed change ("expression that should evaluate
> > to a function"?).
> 
> Please see the text suggestions I proposed.  Somehow
> we need to get across the unusual treatment of the
> first arg.

It isn't unusual.  I see nothing here that needs some special wording.

And let's not make this another endless discussion where you refuse to
accept the judgment of others.