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

[Drew Adams <drew.adams@oracle.com>]

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

Precisely.  That was all that you suggested: add
the word "funtion" - no?  Instead of focusing on
the proble/bug report, your "just add" suggestion
is essentially tangent.

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

`expand-file-name' is a function, not a macro.
_Of course_ it evaluates its args.  And saying
that NAME is a file name, and that it's a string,
is 100% correct and adequate.

`minibuffer-with-setup-hook' is a macro.  And
it's not the case that all its args are eval'd
or not eval'd.  More importantly, it's not even
the case that its first arg is simply eval'd or
simply not eval'd.  The first arg is treated
quite unusually - if it's one kind of sexp then
part of it is eval'd; if it's not that kind of
sexp then the whole arg is eval'd.  There's no
way to guess this behavior.  The doc needs to
help, here.

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

See above.  It's not just about the form of the
sexp.  It's about the fact that it's a sexp,
and how it's handled being different in the two
cases.  It's not even obvious that the arg isn't
simply evaluated always, although one might
guess something more is going on if one notices
that it's a macro.

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

Please point to some other macros that treat
the same argument differently wrt evaluation.

No doubt there are a few.  But I expect that
those generally have multiple forms of the
sexp arg, and the doc catalogs the behavior
of each form, clearly.

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

(Here you go again, with the ad hominem.  You
never fail to make it about me, do you?  Think
about it, please.)

We always accept the fact that your judgment
is final.  That doesn't mean your judgment is
always sound or best, of course - we're all
only human.  But yes, you're the decider (and
I, for one, am glad of that - as I've said
many times).

_Did_ you make a final judgment here?  I
thought suggestions for the doc were still
being made.  I thought efforts were being made
to find a doc string that makes clear what the
second arg needs to be and how it's handled.

Maybe consider making your decisions more
obviously decisions, instead of speaking of
your contributions as "suggestions I proposed".
Otherwise, it's too easy to take you at your
word as a participating peer with some helpful
suggestions.

Close the bug, if you must.  I take no pleasure
in having to repeatedly explain what the problem
is.  You don't see the problem - fine; so be it.