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

[Drew Adams]

> > > I think clarifying that a bit would make sense.
> > Yes.
> I tried to do that:
<proposed>
  In the default case, FUN is an expression that should
  evaluate to a function, and the result will be prepended to
  `minibuffer-setup-hook'.  If FUN is an unquoted list of the
  form `(:append FUN1)', the result of evaluating FUN1 will be
  appended to `minibuffer-setup-hook' instead of prepending it.

Thx.

I'd say (but Eli will likely disagree), that we need
not and should not use future tense ("will be"),
and we should avoid "should".  But that's just a
doc-style question.

More importantly, I'd avoid talking about an unquoted
list.  It's not really about quotation, is it?  It's
about evaluation.  It's about the first arg being a
sexp that doesn't simply get evaluated.

The important thing, I think, is to get across the
(quite unusual) treatment of arg FUN: It's not just
evaluated, and it's not just NOT evaluated.  (IMO,
this is a poor interface, but we are where we are.)

I suggest something like this - somehow get across
the fact that FUN _might_ be simply evaluated, and
the result prepended, or it might be a sexp that's
_not_ evaluated, but _part_ of it is, and in that
case the result of that evaluation is appended.

E.g.:

  Argument FUN is a sexp; it is not simply evaluated.
  Two cases:
  * If FUN has form (:append FUNCTION), evaluate
    FUNCTION and append the result to the hook.
  * Otherwise, evaluate FUN and prepend the result
    to the hook.

Another possibility:

  If FUN is (without evaluating) a sexp (:append FUNCTION)
  then FUNCTION is evaluated and appended to the hook.
  Otherwise, FUN is evaluated and prepended to the hook.

(Could say "list" instead of "sexp", but the latter
stresses the connotation that it's not evaluated.)

We might also change the name FUN.  Maybe use FUN-SPEC
or something - something that doesn't suggest that it
_is_ a function but that it specifies a function that
gets added to the hook.

A question is whether what is said in the doc of
`add-hook' is also true here: the function "is not
added if already present."

If so, I think the doc should say that.  (It's kind
of a shame that we can't just point to `add-hook'.)