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

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

> Well yes, I know, I expected that behavior after reading
> the docstring.  You obviously don't.
> 
> Nowhere is said that FUN should be a function _name_ or a symbol.

If it's not evaluated, and we say that it's added to a
hook, then it must be a sexp that represents a function
in some way, no?  What kinds of sexps represent/name
functions?  Lambda forms and defined-function names
(symbols).  (And maybe someone could think the symbol
name does also.)

> Unless stated otherwise, what you specify as an argument
> is an expression.

But given that assumption, what expressions are expected
for argument FUN?

The doc says that FUN is added to the hook.  Only functions
are added to a hook.  So FUN, the sexp, must be a function?
A sexp isn't a function, and a function isn't a sexp.

So one guesses that maybe it means a sexp that _represents_
a function.  OK. What kinds of specs represent functions?

You see where this leads, I hope.  Is that sexp evaluated?
Do I quote a function name or just pass the function name
(which certainly represents/names a function)?  That info
is missing.  It's not enough to know that macro args are
sexps.

And then we get to the part about the other, more particular
form of spec you can use for FUN - the other sexp that
represents a function, (:append FUN1).

Here we're told not that the whole thing (which is FUN from
the signature and the first line) is added to the hook, but
that FUN1 is added to the hook.

So already there's a contradiction from the the first line.
Even so, now we have that the FUN1 sexp part of the sexp
(:append FUN1) is actually what gets added.  OK.

And we're back to the same question as for FUN: a sexp that
represents a function.  Is it eval'd?  Quoted or unquoted
function representation?   Doesn't matter for a lambda, but
does matter for a function name.

Note that the doc string even goes to the trouble of adding
the detail that "This macro actually adds an auxiliary
function that calls FUN, rather than FUN itself, to
'minibuffer-setup-hook'."  Is that so important for users?

And yet we don't want to make clear whether the sexps (FUN
and FUN1) that represent functions that get added (oops - in
an auxiliary function) get evaluated, i.e., whether you pass
foobar or #'foobar?  Why isn't that important to communicate?

The doc isn't clear, IMO, and it doesn't help to say that if
a reader just understands that macros don't eval their args
then it should be clear.

> Here only with the exception that two syntaxes are
> possible, the alternative one is a list, like we e.g. 
> know from cl arglists.

I see a vague here with CL keyword args, if that's what
you're suggesting.  But CL doc would never show the lambda
list in a way that doesn't make a keyword arg clear, and it
would specifically call out the use of the supported keyword
arg.  (And of course, Elisp doesn't have or allow keyword
args in a lambda list.)

> My patch tried to make that part clearer: the argument is of the form
> FUN or (:append FUN) (an macro _argument_ described as of a certain form
> always speaks about the unevaluated s-exp), and FUN is an expression
> evaluating to the function that will be added to the hook.

Yes, your text was a big improvement, and yes, you tried to
address the problems I raised.  My only comment was a minor
one: to avoid talking about an "unquoted list".

And I pointed to another problem: is it true, as it is for
`add-hook', that the function "is not added if already
present"?  If so, the doc should say that.  A reader can't
assume that that's what happens - there's no mention that
`add-hook' is involved, for instance.  Neither of you have
spoken to this question.

I think the doc should make clear (explicit) that there're
two _alternative_ FUNC arg forms, that both are sexps, and
that in one form the entire sexp is eval'd to produce the
function that's added, and in the (:append F) form the F
part is eval'd to give the function that's added.

Also, I don't think that the non-(:append F) form is any
more of a "default" than the (:append F) form.  There are
two acceptable forms for that sexp arg; neither is default.