mirrors/emacs
1
Fork 0
mirror of git://git.sv.gnu.org/emacs.git synced 2025-12-21 05:00:47 -08:00
Code Issues Projects Releases Wiki Activity

Clarify abnormal hook documentation

Browse source 
* doc/lispref/hooks.texi (Standard Hooks):
* doc/lispref/modes.texi (Hooks): Clarify wording of "abnormal
hook" documentation.  (Bug#34588)
This commit is contained in:
Stefan Kangas 2021-10-23 20:03:34 +02:00
parent 6fa5206770
commit 4fd5c8df67
2 changed files with 13 additions and 11 deletions
Download patch file Download diff file Expand all files Collapse all files

12
doc/lispref/hooks.texi
View file

@ -18,11 +18,13 @@ arguments and their values are completely ignored. The recommended way
to put a new function on such a hook is to call @code{add-hook}.
@xref{Hooks}, for more information about using hooks.
The variables whose names end in @samp{-functions} are usually @dfn{abnormal
hooks} (some old code may also use the deprecated @samp{-hooks} suffix); their
values are lists of functions, but these functions are called in a special way
(they are passed arguments, or their return values are used). The variables
whose names end in @samp{-function} have single functions as their values.
The variables whose names end in @samp{-functions} are usually
@dfn{abnormal hooks} (some old code may also use the deprecated
@samp{-hooks} suffix). Their values are lists of functions, but these
functions are called in a special way: they are either passed
arguments, or their return values are used in some way. The variables
whose names end in @samp{-function} have single functions as their
values.
This is not an exhaustive list, it only covers the more general hooks.
For example, every major mode defines a hook named

12
doc/lispref/modes.texi
View file

@ -59,12 +59,12 @@ runs just before Emacs suspends itself (@pxref{Suspending Emacs}).
@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. Any functions added to an abnormal hook must follow the
hook's calling convention. By convention, abnormal hook names end in
@samp{-functions}.
indicates it is probably an @dfn{abnormal hook}. That means one of
two things: either that the hook functions are called with arguments,
or that their return values are used in some way. The hook's
documentation says how the functions are 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 name of the variable ends in @samp{-predicate} or