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.
> >
> > And this is the case whether or not the "single function hook"
> > is intended to always be single-function (which intention
> > AFAIK, is not enforced anywhere) or it is intended to have
> > any number (including zero and one) of functions.
> 
> So something like this?
> 
>  If the variable's name ends in @samp{-function}, then its value is
> +just a single function, not a list of functions.  @code{add-hook}
> +should not be used to modify such a @emph{single function hook}
   ^^^^^^^^^^
> +because it would turn the value into a list.  Use @code{add-function}
   ^^^^^^^
> +instead (@pxref{Advising Functions}).

Not in my opinion.  The fact that it automatically turns the
value into a list is a _feature_, not something to avoid.

IMHO, the fact that a single function is allowed, and you
are not _required_ to instead use a list (e.g. a singleton
list, which might or might not be added to or subtracted
from) is not to be confused with an admonition that there
is something wrong with using a list.  Such an admonition
would be inappropriate/misguided, IMHO.

Yes, it is true that there are "single-function" hooks
(hooks that happen to have only one function at the
moment) and "single-function" hooks (hooks that are
designed/expected to only ever have a single function,
never zero or more than one).  And yes, the current
wording is a bit ambiguous in this regard.

It is entirely possible for a given hook variable to be
_intended_ to have only one function in its list value
(equivalently, as its atomic value).

But that intended restriction or special case is _not_
something that is declarable/definable using the hook
mechanism.  If that is the intention or a requirement
of the code that uses that hook, then it is up to that
code to enforce it.

And such code should also _document_ this (exceptional)
need for its hook to have only a single function.

The "normal", general, and usual case is for a hook value
to be a list of functions, with any number of elements,
including the case of zero elements.

It would be good to hear from other users about this,
especially (I think) other old-time users or Emacs
developers.  RMS, for example.  But the above is my
understanding, at least, and I think it gibes with the
doc and longstanding code.

The recommended function for setting/modifying a hook
value is `add-hook'.  And all of the doc string for
`add-hook' is couched in terms of the use of a list
value.  It is only at the very end that a statement
is added that if the value is a function then it is
(automatically) changed to a list of functions.  It
is a list of functions that is generally expected as
the value.

The doc string has not changed since at least Emacs 20:

----

Add to the value of HOOK the function FUNCTION.
^^^
FUNCTION is not added if already present.
                ^^^^^            ^^^^^^^
FUNCTION is added (if necessary) at the beginning of the hook list
            ^^^^^
unless the optional argument APPEND is non-nil, in which case
FUNCTION is added at the end.
            ^^^^^

The optional fourth argument, LOCAL, if non-nil, says to modify
the hook's buffer-local value rather than its default value.
This makes no difference if the hook is not buffer-local.
To make a hook variable buffer-local, always use
`make-local-hook', not `make-local-variable'.

HOOK should be a symbol, and FUNCTION may be any valid function.  If
HOOK is void, it is first set to nil.  If HOOK's value is a single
        ^^^^              ^^^^^^^^^^
function, it is changed to a list of functions.
^^^^^^^^        ^^^^^^^^^^^^^^^^^

----

Similarly, the text of (elisp) Hooks dates to Emacs 20, with
almost no changes.  And it clearly says that a hook (normal
or abnormal) is a _list_ of functions.

It adds that besides "normal" and "abnormal" hooks, whose
values are lists, you can have a hook whose name ends in
`-function', and in that case its "value is just a single
function, not a list of functions".  That special case
comes after the more lengthy presentation of normal and
abnormal hooks, and the general description of hooks, which
speak of a list value.

It is only recently that the problematic text was appended
for a hook whose name is ends in `-function':

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

Other than that text, the node is the same as in Emacs 20.

That added text is all wrong.  First, "single-function hook"
is ambiguous (see above).  But even if you suppose that what
is really meant here is a hook whose name ends in `-function'
(since the added text is in the same paragraph), it is _not_
true (AFAIK) that `add-hook' "cannot be used" for such a hook.

Someone (TM) might be _wanting_ to say that Emacs now
recommends that you use `add-function' instead of
`add-hook' for a hook whose name ends in `-function'.
But has that actually been decided?

If it has, then that is what should be said, and clearly so.
And in that case please help users by telling them why (e.g.
advantages of advising with `add-function' versus setting
the value using `add-hook').

Your proposed text suggests that even you are not clear
about the reason for this proposed change (recommendation),
since you suppose that it is "because it would turn the
value into a list".  I'm pretty sure that that is not the
reason (even apart from the fact that that is a feature),
and the reason is that `add-function', i.e., advising the
function is deemed to have significant advantages.

There is only a cross reference to node `Advising Functions',
and users who follow it and read about advising will have
to _guess_ how it pertains to the recommendation to use
`add-function' for a hook whose name ends in `-function'.

If this is now the recommendation, please make it clear
to users why - why it is a better idea in this particular
case to use `add-function' than it is to use `add-hook'.