bug#25581: 25.1; Incorrect statement in (elisp) `Hooks'

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

> > The changes needed, I think, are (1) clarify that the requirement
> > of the value being a function applies only to `*-function' vars
> > and (2) be clear that there are multiple ways to change the value,
> > including plain old `setq' (as Mark O pointed out).
> 
> Hmm, do we really need to explain that variables can be changed with
> setq (seems redundant)?

I think we do here.  Especially since we tell users that you "have
to use" `add-function' to modify "such a single function hook".

A hook is (still) a variable.  It's not super clear from the
doc that this is the case, IMO.

Because we want to be clear that you should not try to modify
the value using, e.g., `add-to-list' - so we recommend
`add-hook' or `add-function', we kind of fall into the trap
of not being clear that you can bind or set the value in the
usual ways.  I do think it's worth pointing out that you can
do this.

> Though it might be useful to compare and contrast setq vs
> add-function (and maybe setq vs add-hook too?)

OK.  But there's not a lot of compare-and-contrast to do, IMO.

All we need to say, I think, is that to change (replace) the
whole value you can use `setq' (or `set' or `setq-local...),
but to _modify_ the current value you should use `add-hook' or
`add-function' (and similar), depending on whether the var name
is `*-functions' or `*-hook', on the one hand (for `add-hook'),
or `*-function', on the other (for `add-function' etc).

> Also wondering if add-function needs a bit of "rebranding",
> since I see it keeps getting referred to as "advice" (i.e.,
> something to be avoided).

Good question!  On the one hand, it does provide a replacement
for the old advice system.  On the other hand, it is something
different and is quite general.

I don't have a good suggestion about the best branding for it,
but Stefan might have something to offer in this regard.
Whatever branding is chosen, it might entail rewriting some of
the manual.

Part of the question you pose is whether and how much it is
something to be avoided.  Instead of just saying that or not
saying anything at all, it would be helpful if we let users
know about some of the consequences of using it, including
possible pitfalls or other things to be aware of.  Again,
Stefan is likely the expert in this regard.