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

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

[Drew Adams]

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.

See http://lists.gnu.org/archive/html/emacs-devel/2016-10/msg00448.html.
See the other msgs of that thread also.

At the very least, this text is misleading, in more than one way.

In GNU Emacs 25.1.1 (x86_64-w64-mingw32)
 of 2016-09-17 built on LAPHROAIG
Windowing system distributor 'Microsoft Corp.', version 6.1.7601
Configured using:
 'configure --without-dbus --without-compress-install CFLAGS=-static'

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

[npostavs]

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

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

--- i/doc/lispref/modes.texi
+++ w/doc/lispref/modes.texi
@@ -74,9 +74,10 @@ Hooks
 
 @cindex single-function hook
 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} cannot be
-used to modify such a @emph{single function hook}, and you have to use
-@code{add-function} instead (@pxref{Advising Functions}).
+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}).
 
 @menu
 * Running Hooks::    How to run a hook.

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

[Mark Oteiza]

npostavs@users.sourceforge.net writes:

> Drew Adams <drew.adams@oracle.com> writes:
>
>> 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?
>
> --- i/doc/lispref/modes.texi
> +++ w/doc/lispref/modes.texi
> @@ -74,9 +74,10 @@ Hooks
>  
>  @cindex single-function hook
>  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} cannot be
> -used to modify such a @emph{single function hook}, and you have to use
> -@code{add-function} instead (@pxref{Advising Functions}).
> +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}).

Better, but the typical practice of setq'ing to another named
function should be mentioned before advice.

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

[Drew Adams]

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

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

[Drew Adams]

> Better, but the typical practice of setq'ing to another named
> function should be mentioned before advice.

Before or after, I don't know.  But it should be clear to
a user at the end that s?he _can_ use _any_ of these (and
similar):

 setq (-local etc), set
 add-hook
 add-function

And if Emacs wants to make a point of _recommending_ one
of these (for a hook named `*-function') then it should,
I think, point out some of its _advantages_.

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

[npostavs]

Drew Adams <drew.adams@oracle.com> writes:
>> 
>>  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.

Perhaps an example would help clarify things:

emacs -Q
M-: (add-hook 'blink-paren-function #'ignore) RET
insert "()"
blink-paren-post-self-insert-function: Invalid function: (ignore blink-matching-open)

In my opinion, such errors (triggered by putting a list where a function
was wanted) are something to avoid.

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

IMO the current wording is pretty unambiguous that a variable ending in
"-function" should be a single function and not a list.  But if you feel
differently, please suggest an alternate wording.

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

From a quick look at M-x apropos-variable RET .*-function$ RET, every
such variable is described as "a function" or "function" which is
clearly not a list of functions.

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

[Drew Adams]

> IMO the current wording is pretty unambiguous that a variable ending in
> "-function" should be a single function and not a list.  But if you feel
> differently, please suggest an alternate wording.
> 
> > And such code should also _document_ this (exceptional)
> > need for its hook to have only a single function.
> 
> From a quick look at M-x apropos-variable RET .*-function$ RET, every
> such variable is described as "a function" or "function" which is
> clearly not a list of functions.

What can mislead is "such a single-function hook", even though it
is used just after introducing variables named `*-function'.  If
the text is changed to repeat that name criterion then I think it
is clearer.  Something like this:

 If the name of the variable ends in `-function' (singular) then its
 value must be a function, not a list of functions.  In this case,
 to modify the variable value just set it (using `setq' etc.) or
 advise it (using `add-function' etc.).

And yes, I was wrong to say that you could in fact use `add-hook'
in this case.  Sorry for that noise.

The changes needed, I think, are (1) clarify that the requirement
of the value being a function applies only to `*-function' vars
and (2) be clear that there are multiple ways to change the value,
including plain old `setq' (as Mark O pointed out).

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

[npostavs]

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

>
> The changes needed, I think, are (1) clarify that the requirement
> of the value being a function applies only to `*-function' vars
> and (2) be clear that there are multiple ways to change the value,
> including plain old `setq' (as Mark O pointed out).

Hmm, do we really need to explain that variables can be changed with
setq (seems redundant)?  Though it might be useful to compare and
contrast setq vs add-function (and maybe setq vs add-hook too?)

Also wondering if add-function needs a bit of "rebranding", since I see
it keeps getting referred to as "advice" (i.e., something to be
avoided).

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

[Drew Adams]

> > The changes needed, I think, are (1) clarify that the requirement
> > of the value being a function applies only to `*-function' vars
> > and (2) be clear that there are multiple ways to change the value,
> > including plain old `setq' (as Mark O pointed out).
> 
> Hmm, do we really need to explain that variables can be changed with
> setq (seems redundant)?

I think we do here.  Especially since we tell users that you "have
to use" `add-function' to modify "such a single function hook".

A hook is (still) a variable.  It's not super clear from the
doc that this is the case, IMO.

Because we want to be clear that you should not try to modify
the value using, e.g., `add-to-list' - so we recommend
`add-hook' or `add-function', we kind of fall into the trap
of not being clear that you can bind or set the value in the
usual ways.  I do think it's worth pointing out that you can
do this.

> Though it might be useful to compare and contrast setq vs
> add-function (and maybe setq vs add-hook too?)

OK.  But there's not a lot of compare-and-contrast to do, IMO.

All we need to say, I think, is that to change (replace) the
whole value you can use `setq' (or `set' or `setq-local...),
but to _modify_ the current value you should use `add-hook' or
`add-function' (and similar), depending on whether the var name
is `*-functions' or `*-hook', on the one hand (for `add-hook'),
or `*-function', on the other (for `add-function' etc).

> Also wondering if add-function needs a bit of "rebranding",
> since I see it keeps getting referred to as "advice" (i.e.,
> something to be avoided).

Good question!  On the one hand, it does provide a replacement
for the old advice system.  On the other hand, it is something
different and is quite general.

I don't have a good suggestion about the best branding for it,
but Stefan might have something to offer in this regard.
Whatever branding is chosen, it might entail rewriting some of
the manual.

Part of the question you pose is whether and how much it is
something to be avoided.  Instead of just saying that or not
saying anything at all, it would be helpful if we let users
know about some of the consequences of using it, including
possible pitfalls or other things to be aware of.  Again,
Stefan is likely the expert in this regard.

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

[npostavs]

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

>> > The changes needed, I think, are (1) clarify that the requirement
>> > of the value being a function applies only to `*-function' vars
>> > and (2) be clear that there are multiple ways to change the value,
>> > including plain old `setq' (as Mark O pointed out).
>> 
>> Hmm, do we really need to explain that variables can be changed with
>> setq (seems redundant)?
>
> I think we do here.  Especially since we tell users that you "have
> to use" `add-function' to modify "such a single function hook".
>
> A hook is (still) a variable.  It's not super clear from the
> doc that this is the case, IMO.

Hmm, maybe if we rearranged things a bit.

--- i/doc/lispref/modes.texi
+++ w/doc/lispref/modes.texi
@@ -35,10 +35,11 @@ Hooks
 @section Hooks
 @cindex hooks
 
-  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.
 
 @cindex normal hook
@@ -56,27 +57,36 @@ Hooks
 used in other contexts too.  For example, the hook @code{suspend-hook}
 runs just before Emacs suspends itself (@pxref{Suspending Emacs}).
 
-  The recommended way to add a hook function to a hook is by calling
-@code{add-hook} (@pxref{Setting Hooks}).  The hook functions may be any
-of the valid kinds of functions that @code{funcall} accepts (@pxref{What
-Is a Function}).  Most normal hook variables are initially void;
-@code{add-hook} knows how to deal with this.  You can add hooks either
-globally or buffer-locally with @code{add-hook}.
-
 @cindex abnormal hook
   If the hook variable's name does not end with @samp{-hook}, that
 indicates it is probably an @dfn{abnormal hook}.  That means the hook
 functions are called with arguments, or their return values are used
 in some way.  The hook's documentation says how the functions are
-called.  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.  By convention, abnormal hook names end in @samp{-functions}.
+called.  Any functions added to an abnormal hook must follow the
+hook's calling convention.  By convention, abnormal hook names end in
+@samp{-functions}.
 
 @cindex single-function hook
-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} cannot be
-used to modify such a @emph{single function hook}, and you have to use
-@code{add-function} instead (@pxref{Advising Functions}).
+If the name of the variable ends in @samp{-predicate} or
+@samp{-function} (singular) then its value must be a function, not a
+list of functions.  As with abnormal hooks, the expected arguments and
+meaning of the return value vary across such @emph{single function
+hooks}.  The details are explained in each variable's docstring.
+
+  Since hooks (both multi and single function) are variables, their
+values can be modified with @code{setq} or temporarily with
+@code{let}.  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
+buffer-locally with @code{add-hook}.  For hooks which hold only a
+single function, @code{add-hook} is not appropriate, but you can use
+@code{add-function} (@pxref{Advising Functions}) to combine new
+functions with the hook.  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}.
 
 @menu
 * Running Hooks::    How to run a hook.

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

[Drew Adams]

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.

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

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

[Drew Adams]

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

It's one thing to say that a Boolean function is, in effect, a
predicate.  It's another thing to extend the convention of names
that end in `-function' to apply to names that end in `-predicate'.

Such a convention has never been pronounced before, AFAIK.
I don't think we should make convention policy this way.

Instead, I suggested in my report that the example I know about,
`isearch-filter-predicate' is misnamed, precisely because it
acts like a hook but is not named following the convention.
It should be named `-function', IMO.

Whether or not it is easy to rename it now (I think it's possible
to deprecate the old name), the fact that it is misnamed should
not, by itself, start a spread of `-predicate' as yet another
possible hook-name suffix.  If someone mistakenly adds another
variable that is, in its behavior a hook, and it has suffix
`-fn' or `-pred' or `-test', should we then willy nilly update
the doc to extend the convention some more?

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

It's not my call, and as I said, I don't know what I think
about this.  I tend to lean at the moment toward saying
that if we are advising people to `advice-add' variables
whose value is expected to always be a function, and if
we are calling that a hook of sorts, then we should stick
with recommending a simple convention of suffix `-function'.

I also think that we should probably point out explicitly
somewhere why we have these naming conventions: to facilitate
(human) readability.  A variable whose name ends in
`-function' is conventionally such a hook.  That means that
just seeing such a name makes us likely to think it is
(whether or not it really is - it could be a variable whose
value is not necessarily a function).  It's an aid to reading,
with no guarantees about how reliable/accurate it is.

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

Please read my last paragraph that you just cited again.
That's my point.  Those are exactly the naming conventions
we've had, up till now. IMO they are the naming conventions
we should still have.

A variable whose value can be anything, including possibly a
function, is not a hook in the sense introduced by our naming
conventions.

Someone might want to call it a hook because _when its value
is a function_, if code invokes that function then yes, it
hooks into that function's code.

But that's a far cry from the conventions talked about here,
which are strict (clear) about what they apply to.  If a
variable can be anything then its name can be anything, and
whether or not it might sometimes have a function value and
be invoked is not a reason to dilute the helpful conventions.

The point of such a convention (see above) is to help you
read code, without analyzing it in detail to see what the
use of such a variable is.

If someone uses the a name `*-function' its a pretty safe
bet that its value _is_ a function and that the code invokes
it somewhere.

If we start applying such a name to anything and everything
that might sometimes have a function value then its power
to help reading is reduced.  Then, for EVERY variable named
`*-function' a reader will need to read all of the code
carefully, to see whether and where it might have a function
value.

It's better to have a good, quick first approximation based
on the name, so that even without scrutinizing the code you
can suppose that the value is a function.

Otherwise, there is little point in having such a convention.

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

[Lars Ingebrigtsen]

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

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

Well, the name -function suggests that you shouldn't.

I think the confusing thing here is that foo-function isn't a hook at
all -- variables ending with -function are normally not executed with
run-hooks at all, so using add-hook on such a variable will normally
break.

So I'm not sure what that section is doing in the Hooks node at all.  It
origin starts here, where unfortunately vc-region-history gives up.

My preference here would be just to remove the paragraph, which is
pretty confusing.

commit b8d4c8d0e9326f8ed2d1f6fc0a38fb89ec29ed27
Author:     Glenn Morris <rgm@gnu.org>
AuthorDate: Thu Sep 6 04:25:08 2007 +0000
Commit:     Glenn Morris <rgm@gnu.org>
CommitDate: Thu Sep 6 04:25:08 2007 +0000

    Move here from ../../lispref

diff --git a/doc/lispref/modes.texi b/doc/lispref/modes.texi
--- /dev/null
+++ b/doc/lispref/modes.texi
@@ -0,0 +76,3 @@
+  By convention, abnormal hook names end in @samp{-functions} or
+@samp{-hooks}.  If the variable's name ends in @samp{-function}, then
+its value is just a single function, not a list of functions.

-- 
(domestic pets only, the antidote for overdose, milk.)
   bloggy blog: http://lars.ingebrigtsen.no

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

[Stefan Kangas]

Lars Ingebrigtsen <larsi@gnus.org> writes:

> Drew Adams <drew.adams@oracle.com> writes:
>
>> 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.

I'm not sure the above makes sense.  Doesn't it usually work like:

(setq foo-function 'message)
(add-hook 'foo-function 'error) ; should work?
(funcall foo-function) ; => Lisp error: (invalid-function (error message))

> Well, the name -function suggests that you shouldn't.
>
> I think the confusing thing here is that foo-function isn't a hook at
> all -- variables ending with -function are normally not executed with
> run-hooks at all, so using add-hook on such a variable will normally
> break.
>
> So I'm not sure what that section is doing in the Hooks node at all.  It
> origin starts here, where unfortunately vc-region-history gives up.
>
> My preference here would be just to remove the paragraph, which is
> pretty confusing.

It sort of makes sense when read next to the paragraph before, doesn't
it?  There the concept "abnormal hook" is defined with an explanation of
variables ending in '-functions', and the paragraph about variables
ending in '-function' is written mostly in contrast to that.

I think the confusing thing here is that there are two ways to modify
these single function hooks: setq and add-function.

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

[Lars Ingebrigtsen]

Stefan Kangas <stefankangas@gmail.com> writes:

>>>  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.
>
> I'm not sure the above makes sense.  Doesn't it usually work like:
>
> (setq foo-function 'message)
> (add-hook 'foo-function 'error) ; should work?
> (funcall foo-function) ; => Lisp error: (invalid-function (error message))

run-hooks is very permissive -- you can set the value of a -hooks
variable to a single function, and it'll still work:

(setq my-hook (lambda () (message "foo")))
(run-hooks 'my-hook)

So I think Drew is assuming that this -function variable would be run by
run-hook, and then things would still indeed work.

> It sort of makes sense when read next to the paragraph before, doesn't
> it?  There the concept "abnormal hook" is defined with an explanation of
> variables ending in '-functions', and the paragraph about variables
> ending in '-function' is written mostly in contrast to that.
>
> I think the confusing thing here is that there are two ways to modify
> these single function hooks: setq and add-function.

But -functions variables are abnormal hooks.  -function variables aren't
hooks at all.

-- 
(domestic pets only, the antidote for overdose, milk.)
   bloggy blog: http://lars.ingebrigtsen.no

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

[Drew Adams]

> > 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.
> 
> Well, the name -function suggests that you shouldn't.

No, I don't think so.  Nothing suggests you shouldn't.
Because it's not true that you shouldn't.  It all
depends on whether the variable is a hook.  If it is,
then it's fine to use `add-hook' on it - in fact, it's
advisable.

> I think the confusing thing here is that foo-function isn't a hook at
> all -- variables ending with -function are normally not executed with
> run-hooks at all, so using add-hook on such a variable will normally
> break.

This isn't true.  `add-hook' works fine with a variable
named `*-function'.  What it does is treat the variable
as a hook (since you called `add-hook' on it).  It turns
the value into a singleton list with the given function
as element.

`add-hook' does what it's supposed to with any variable.
What's wrong is to use `add-hook' on a variable (whatever
the name) that's not intended to be used as a hook.
Using `add-hook' on a variable treats it like a hook:
it adds the argument function as an element in the
variable's list value.

If you use `add-hook' on a var that's NOT intended as a
hook, in particular, a variable whose value should NOT
be a list of functions, then that's on you.

Some variables named `*-function' are not intended as
hooks.  For those, it makes no sense to use `add-hook'
(and `run-hooks').  Others _are_ intended as hooks.

The latter case is legacy, AFAIK.  Such vars would be
better named `*-hook' or `*-functions', depending on
whether they are normal or abnormal hooks. 

> So I'm not sure what that section is doing in the Hooks node at all.  It
> origin starts here, where unfortunately vc-region-history gives up.

I don't understand that last sentence, and I'm not
sure what you mean by "that section".  The text of
node `Hooks' is longstanding, and though not perfect,
it is generally accurate.

The problem is the change that someone made by adding
this paragraph, fairly recently (presumably  when
`add-function' came into being):

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

That's what this bug is about - that text.

> My preference here would be just to remove the paragraph,
> which is pretty confusing.

If you mean the paragraph I mentioned just above then
yes, that was the suggestion.

There's a lot of careful consideration in this thread,
and there's a lot of info in node `Hooks'.  Let's not
throw out the baby with the bathwater.  A variable
named `*-function' can be a hook, but it need not be.
Such a name doesn't tell us whether the variable is a
hook, unfortunately.

Yes, that's a point of confusion.  The right change,
if one is needed in this regard, is to rename any
such hooks.

Note that Emacs has, in some cases, tried to make
clear when a `*-function' variable is not a hook.
For example, `C-h v auto-fill-function' says, among
other things:

  NOTE: This variable is not a hook;
  its value may not be a list of functions.

That makes the purpose and allowable value of that
variable pretty clear.

More recently, there's been addition of more non-hook
variables with names `*-function', and _without_ such
caveats in their doc strings.  It's maybe time to
rename the hook variables with names `*-function'.
But as long as such exist the doc should cover them.

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

[Drew Adams]

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.

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

[Drew Adams]

> I think the confusing thing here is that there are two ways to modify
> these single function hooks: setq and add-function.

`setq' can always be used to change a variable's value.
But that doesn't mean it's always the best thing to use.

See earlier posts in this thread, about variables whose
value is a "single function".  They can be hooks, but
need not be hooks (and this, regardless of their names).

Some vars are _intended_ to only ever have a single
function as their value.  Some vars are _intended_ to
have a value that can be a single function or a list of
functions.  Some of the latter kind of variables are
hooks.  (Maybe _all_ of the latter can be treated as
hooks; maybe not.)

`add-hook' is the best way to add a function to a hook.
This is so, regardless of its name.  That you can use
`setq' or something else instead doesn't make that TRT.

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

[Drew Adams]

> But -functions variables are abnormal hooks.

Yes.

> -function variables aren't hooks at all.

No, that's not correct.  Some are and some aren't.

You can't tell by a variable's name whether it's a
hook.  Convention can tell you, but unfortunately the
name `*-function' does _not_ tell you.  See my other
posts today about this.

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

[Richard Stallman]

[[[ To any NSA and FBI agents reading my email: please consider    ]]]
[[[ whether defending the US Constitution against all enemies,     ]]]
[[[ foreign or domestic, requires you to follow Snowden's example. ]]]

  >   Some vars are _intended_ to
  > have a value that can be a single function or a list of
  > functions.  Some of the latter kind of variables are
  > hooks.  (Maybe _all_ of the latter can be treated as
  > hooks; maybe not.)

We could conceivably start a long, slow process of giving them
new names, and converting them into enitrely regular normal hooks.

-- 
Dr Richard Stallman
Chief GNUisance of the GNU Project (https://gnu.org)
Founder, Free Software Foundation (https://fsf.org)
Internet Hall-of-Famer (https://internethalloffame.org)

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

[Drew Adams]

>   >   Some vars are _intended_ to
>   > have a value that can be a single function or a list of
>   > functions.  Some of the latter kind of variables are
>   > hooks.  (Maybe _all_ of the latter can be treated as
>   > hooks; maybe not.)
> 
> We could conceivably start a long, slow process of giving them
> new names, and converting them into enitrely regular normal hooks.

Yes.  And then (or even before then), we should
update the doc to say that in the past _______ was
allowed.  This, to point out that there can be code
out there in the wild that still expects that.

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

[Lars Ingebrigtsen]

npostavs@users.sourceforge.net writes:

> Hmm, maybe if we rearranged things a bit.
>
> --- i/doc/lispref/modes.texi
> +++ w/doc/lispref/modes.texi

I think Noam's patch helped with understanding how to set these
variables, so I've applied it to Emacs 28.

-- 
(domestic pets only, the antidote for overdose, milk.)
   bloggy blog: http://lars.ingebrigtsen.no

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

[Drew Adams]

> I think Noam's patch helped with understanding how to set these
> variables, so I've applied it to Emacs 28.

I explained clearly what is wrong with that.

So this is yet another "won't fix".  Too bad.