Hello List In bug#70820 August 14, Stefan mentions that it is a common confusion to think of the functions in a hook as hooks. It got my attention because I belong to the confused ones every second year or so adding or removing functions from a hook.
I suggest the provided patch as a small improvement of the function documentation of add-hook and remove-hook. Maybe it doesn't mitigate the confusion mentioned that much, but it seem to align better with the manual as I read it. What do you think? In add-hook doc, lift up the paragraph about HOOK and FUNCTION and remove the mention about first setting the HOOK to nil. I think that is something internal to the add-hook function and not relevant to the programmer calling the add-hook function? And then say that the resulting hook will be a list both when the HOOK symbol is void or a single function. In remove-hook, stick to the notion that a hook contain functions to run, not hooks. This notion though is a bit confusing in relation to the names of those functions, but that's another story I guess. The following on top of emacs-30. diff --git a/lisp/subr.el b/lisp/subr.el index 28ba30f584e..e60c4119c60 100644 --- a/lisp/subr.el +++ b/lisp/subr.el @@ -2090,6 +2090,10 @@ add-hook "Add to the value of HOOK the function FUNCTION. FUNCTION is not added if already present. +HOOK should be a symbol. If HOOK is void, or if HOOK's value is a +single function, it is changed to a list of functions (containing only +FUNCTION in the void case). + The place where the function is added depends on the DEPTH parameter. DEPTH defaults to 0. By convention, it should be a number between -100 and 100 where 100 means that the function @@ -2108,10 +2112,6 @@ add-hook buffer-local value. That acts as a flag to run the hook functions of the global value as well as in the local value. -HOOK should be a symbol. 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. - FUNCTION may be any valid function, but it's recommended to use a function symbol and not a lambda form. Using a symbol will ensure that the function is not re-added if the function is @@ -2179,7 +2179,7 @@ remove-hook "Remove from the value of HOOK the function FUNCTION. HOOK should be a symbol, and FUNCTION may be any valid function. If FUNCTION isn't the value of HOOK, or, if FUNCTION doesn't appear in the -list of hooks to run in HOOK, then nothing is done. See `add-hook'. +list of functions to run in HOOK, then nothing is done. See `add-hook'. The optional third argument, LOCAL, if non-nil, says to modify the hook's buffer-local value rather than its default value.
