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

[Eli Zaretskii <eliz@gnu.org>]

> Cc: "59559@debbugs.gnu.org" <59559@debbugs.gnu.org>
> From: Drew Adams <drew.adams@oracle.com>
> Date: Sat, 21 Jan 2023 18:41:15 +0000
> 
> 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.

All of your suggestions just muddy the water, making a clear doc
string confusing and risking the user's interpreting that like some
kind of black magic is going on here.

The current doc string is clear and easy to understand and use.