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

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

It's hard for me to read this style of `diff' output, so I may
have missed some of the real changes.  I think I'm generally OK
with your proposed changes, but I made a few comments below.

> -  A @dfn{hook} is a variable where you can store a function or functions
> -to be called on a particular occasion by an existing program.  Emacs
> -provides hooks for the sake of customization.  Most often, hooks are set
> -up in the init file (@pxref{Init File}), but Lisp programs can set them
> also.
> +  A @dfn{hook} is a variable where you can store a function or
> +functions (@pxref{What Is a Function}) to be called on a particular
> +occasion by an existing program.  Emacs provides hooks for the sake of
> +customization.  Most often, hooks are set up in the init file
> +(@pxref{Init File}), but Lisp programs can set them also.
>  @xref{Standard Hooks}, for a list of some standard hook variables.

OK.  I think the only real change there is to xref {What Is a
Function}.  (Right?)

> -You can use @code{add-hook} to add a function to an abnormal
> -hook, but you must write the function to follow the hook's
> -calling convention.

I think this statement was removed.  Don't you think that we
should say that you can use `add-hook' with an abnormal (or
a normal) hook?  Why would we want to remove this?  A reader
could think that `add-hook' is only for normal hooks, and so
might resort to, say, `add-to-list' for an abnormal hook.

> +If the name of the variable ends in @samp{-predicate} or
> +@samp{-function} (singular) then its value must be a function, not a

Is this the (new) policy, adding the suffix `-predicate'?
In my previous comments I was sticking to the old policy, and
pointing out that `isearch-filter-predicate', now that it is
being advised here and there with `add-function', is being used
as a hook, and so it should be named accordingly, as `*-function'.

I'm not sure it is a good idea to add more possible suffixes
for hooks.  But someone who decides things should decide this.
If it is decided to add suffix `-predicate' for hooks, then OK.

There's something else that is a bit disconcerting - not with
what you wrote, but what you wrote brings up another issue:

This text talks about a naming convention, saying that IF a
variable's name matches one of these patterns THEN it is a
hook (or it is likely to be a hook).

But the addition of nadvice.el and subsequent encouragement
of advising functions with it applies to all functions.  It in
effect makes every function-valued variable into a hook.  Can
or should users expect that such variables will by convention
have such a conventional suffix?  Dunno.

> +  Since hooks (both multi and single function) are variables, their

(Should be "both multi- and single-function" or "both
multi-function and single-function".)

> +values can be modified with @code{setq} or temporarily with
> +@code{let}.

Yes, but I'd say something like this (using "set" and "bind"
instead of "modified"):

 Since a hook is a variable you can set or bind it to a different
 value (using `setq' or `let', for example).  This applies to any
 hook, regardless of its value.

If you want to point out that this is true for both multi-function
and single-function hooks, OK, but it's not strictly necessary.
The point is about variables, not their values, and I think the
last sentence I added is enough to cover this.

(I said earlier that it's good to point out that you can use
`setq' and `let' to set or bind a hook whose name ends in
`-function'.  It's the wording "multi-function" and
"single-function" that I think is not good to use - see below.)

> +However, it is often useful to add or remove a particular
> +function from a hook while preserving any other functions it might
> +have.  For multi function hooks, the recommended way of doing this is
> +with @code{add-hook} and @code{remove-hook} (@pxref{Setting Hooks}).

> +Most normal hook variables are initially void; @code{add-hook} knows
> +how to deal with this.  You can add hooks either globally or

"You can add hooks" is wrong.  Something like `add-hook' adds
a function to a hook (a variable).  It does not add a hook to
anything.

> +buffer-locally with @code{add-hook}.

I would split the paragraph here, before talking about
hooks whose values can only be a single-function.

> +For hooks which hold only a single function,

This is clearer:

 "For a hook whose value must be a single function..."

As I said in an earlier mail, just calling such hooks
"single-function" can be misleading.  They are hooks whose
value MUST (always) be a single function.  The label
"single-function hook" can be misunderstood as a list-valued
hook whose value is currently a singleton list (holds a
single function).

Unless we give such hooks a special name (I don't think
"single-function" is clear), this is another argument for
sticking with the old naming convention (not adding suffix
`-predicate').  In that case they can be referred to as hooks
whose name ends in `-function'.  If we add `-predicate' then
the clearest way to refer to them (unless we give them a new
name) is "a hook whose name ends in `-function' or `-predicate',
which is a mouthful, especially if repeated.

I think it might be clear enough to say what I said above:
"a hook whose value must be a single function".  It is that
the variable value MUST BE a function, not that the hook
HOLDS a single function (e.g. currently).

> +@code{add-hook} is not appropriate, but you can use
> +@code{add-function} (@pxref{Advising Functions}) to combine new
> +functions with the hook.

I would say "but you can advise the function that is the
hook value using functions such as `add-function'
(@pxref{Advising Functions})."

The hook is a variable.  It is its value that is advised.
The hook (a variable) is not combined with functions.  And
`add-function' is only one way to advise the hook value.

> Note that some single function hooks may be
> +@code{nil} which @code{add-function} cannot deal with, so you must
> +check for that before calling @code{add-function}.

This disagrees with my understanding.  (But again,
"single-function hook" is misleading.)  We are talking here
about a hook whose value MUST ALWAYS BE a function (advised
or not).  Its value cannot be `nil'.

IOW, I don't think we should talk about "single-function
hooks", and explain that such a hook's single value might
be `nil' or a function...  I think we should talk about
hooks whose value MUST BE a function.  And for those
critters, you can always use `add-function' etc.

Now, since you can apply `add-function' to any function, it
can happen that someone defines a variable - of whatever
name - whose value can be a (single) function or nil (or
a number or a symbol or a character or...).  In a general
sense, since the value CAN be a function, someone could
call such a variable a "hook", if s?he wants.

But that is, I think, NOT what we are talking about in
this doc.  We are talking here about naming conventions
for variables whose values are either (1) a function
whose name ends in `-function' (or `-predicate'?) and
whose value MUST BE a function or (2) a list of functions
(normal & abnormal hooks, for which you can use `add-hook').

A variable whose value can be something other than a list
of functions or a single function, and whose name does not
follow the documented convention, can have its value modified
in any number of ways, including (depending on the current
value) with `add-hook' or `add-function', but it is not a
hook in the sense specified in this node.