RE: 1) (elisp) `Advising Named Functions', 2) search filtering example

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

> > I think that is wrong also.  `add-hook' _can_ be used to modify a
> > _single function hook_.  And the doc of `add-hook' tells you so,
> > in its last line - `C-h f add-hook':
> >
> >   ...
> >   If HOOK's value is a single function, it is changed to a list of
> >   functions.
> 
> If you do this, then you will break the callers, which expect the
> value of this variable to be a single function.

Tell that to the doc string for `add-hook', which has said what it
says in this regard for a very long time.

What has changed (what is new) is that this was added to node `Hooks':

  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::).

And that is clearly false ("cannot be used" - it _can_ be so used).

This is what that doc used to say (e.g. Emacs 23.4):

   By convention, abnormal hook names end in `-functions' or
   `-hooks'.  If the variable's name ends in `-function', then
   its value is just a single function, not a list of functions.

There has thus also (apparently) been a change in policy here.
Whereas, before, this doc just let you know about the _naming
convention_ for a hook whose value is a single function, the
changed doc says (incorrectly) that you cannot use `add-hook'
with it.

I think that callers of such a hook should _use it as a hook_,
and not necessarily expect that the value is a single function.

Callers of a hook can, and should, I think, use one of the
`run-hook*' functions.  And there too you will note that the
doc _explicitly_ talks about the non-list, single function case.

`C-h f run-hooks':

  If a hook symbol has a non-nil value, that value may be a
  function or a list of functions to be called to run the hook.
  If the value is a function, it is called with no arguments.
  If it is a list, the elements are called, in order, with no arguments.

`C-h f run-hook-with-args':

  The value of HOOK may be nil, a function, or a list of functions.
  Call each function in order with arguments ARGS.

(It used to say this:

  If HOOK has a non-nil value, that value may be a function
  or a list of functions to be called to run the hook.  If the
  value is a function, it is called with the given arguments
  and its return value is returned.  If it is a list of functions,
  those functions are called, in order, with the given arguments ARGS.)

`C-h f run-hook-with-args-until-failure':

  The value of HOOK may be nil, a function, or a list of functions.
  Call each function in order with arguments ARGS, stopping at the
  first one that returns nil, and return nil.

`C-h f run-hook-with-args-until-success': similar.

So do we have changes in policy wrt using hooks, or not?
(If yes, why?)  Which doc needs to be fixed?