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

[npostavs]

Drew Adams <drew.adams@oracle.com> writes:

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

Yeah, it's a bit hard to pick out the real changes from the whitespace
changes.  Basically, my idea is to mvoe the separate explanations about
using add-hook/function for hooks, abnormal hooks, and
-function/-predicate variables and merge them into a single paragraph at
the bottom.

>> +functions (@pxref{What Is a Function}) to be called on a particular
>
> OK.  I think the only real change there is to xref {What Is a
> Function}.  (Right?)

Yes, moved here from below.

>> -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?

Should be covered below, but I guess I didn't actually abnormal hooks
sepcifically there.

>> +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'.

Not sure, I was under the impression that -predicate is the same idea as
-function, with the added implication about the return value's meaning.
No idea if this is "new" or not.

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

Yes.

> Can or should users expect that such variables will by convention have
> such a conventional suffix?

I guess?

>
>> +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.

Makes sense.

>> +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.

Oops, that was a thinko, I meant "you can add functions".

>
>> +buffer-locally with @code{add-hook}.
>
> I would split the paragraph here, before talking about
> hooks whose values can only be a single-function.

Yes, it is a bit long.

[...]
> 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').

Hmm, I'm not sure if making this division is helpful.  I do think we
need some kind of name for these kind of "hooks".  Just not sure what it
should be...