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

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

> > The second sentence here is incorrect:
> >
> >  If the variable’s name ends in ‘-function’, then its value is just a
> >  single function, not a list of functions.  ‘add-hook’ cannot be used to
> >  modify such a _single function hook_, and you have to use ‘add-function’
> >  instead (*note Advising Functions::).
> >
> > You CAN use `add-hook' to modify such a single-function hook.
> > Nothing prevents you from doing so.  And nothing even suggests
> > that you should not.  And you have always been able to do so.
> 
> Well, the name -function suggests that you shouldn't.

No, I don't think so.  Nothing suggests you shouldn't.
Because it's not true that you shouldn't.  It all
depends on whether the variable is a hook.  If it is,
then it's fine to use `add-hook' on it - in fact, it's
advisable.

> I think the confusing thing here is that foo-function isn't a hook at
> all -- variables ending with -function are normally not executed with
> run-hooks at all, so using add-hook on such a variable will normally
> break.

This isn't true.  `add-hook' works fine with a variable
named `*-function'.  What it does is treat the variable
as a hook (since you called `add-hook' on it).  It turns
the value into a singleton list with the given function
as element.

`add-hook' does what it's supposed to with any variable.
What's wrong is to use `add-hook' on a variable (whatever
the name) that's not intended to be used as a hook.
Using `add-hook' on a variable treats it like a hook:
it adds the argument function as an element in the
variable's list value.

If you use `add-hook' on a var that's NOT intended as a
hook, in particular, a variable whose value should NOT
be a list of functions, then that's on you.

Some variables named `*-function' are not intended as
hooks.  For those, it makes no sense to use `add-hook'
(and `run-hooks').  Others _are_ intended as hooks.

The latter case is legacy, AFAIK.  Such vars would be
better named `*-hook' or `*-functions', depending on
whether they are normal or abnormal hooks. 

> So I'm not sure what that section is doing in the Hooks node at all.  It
> origin starts here, where unfortunately vc-region-history gives up.

I don't understand that last sentence, and I'm not
sure what you mean by "that section".  The text of
node `Hooks' is longstanding, and though not perfect,
it is generally accurate.

The problem is the change that someone made by adding
this paragraph, fairly recently (presumably  when
`add-function' came into being):

  "‘add-hook’ cannot be used to modify such a single
   function hook, and you have to use ‘add-function’
   instead (*note Advising Functions::)."

That's what this bug is about - that text.

> My preference here would be just to remove the paragraph,
> which is pretty confusing.

If you mean the paragraph I mentioned just above then
yes, that was the suggestion.

There's a lot of careful consideration in this thread,
and there's a lot of info in node `Hooks'.  Let's not
throw out the baby with the bathwater.  A variable
named `*-function' can be a hook, but it need not be.
Such a name doesn't tell us whether the variable is a
hook, unfortunately.

Yes, that's a point of confusion.  The right change,
if one is needed in this regard, is to rename any
such hooks.

Note that Emacs has, in some cases, tried to make
clear when a `*-function' variable is not a hook.
For example, `C-h v auto-fill-function' says, among
other things:

  NOTE: This variable is not a hook;
  its value may not be a list of functions.

That makes the purpose and allowable value of that
variable pretty clear.

More recently, there's been addition of more non-hook
variables with names `*-function', and _without_ such
caveats in their doc strings.  It's maybe time to
rename the hook variables with names `*-function'.
But as long as such exist the doc should cover them.