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

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

Please see my reply to Lars.  I hope I've made things
clear about this.  There are two uses of vars named
`*-function': (1) as a hook, (2) as a single function
to call.

The first use of such a name is, I think, legacy.
I think such vars should be renamed to either
`*-hook' or `*-functions', depending on whether they
are normal or abnormal.

But until they all are (and probably even then, since
they could exist in 3rd-party code), the doc should
cover them.

If I'm right that they are only legacy, and should
be renamed (to be confirmed by some old-timer such
as RMS), then the doc could make this clear.

`add-hook' and `run-hooks' work fine with such vars.
The doc about that is not wrong.  (Only the cited
paragraph is wrong.)

But if I'm right about the only-legacy thing, it
would probably help for the doc to point out that a
hook named `*-function' should probably be renamed
(to `*-hook' or `*-functions', depending on whether
it is normal or abnormal).  And Emacs itself should
in that case have its own such hooks renamed.  But
this understanding should be confirmed first.