mirrors/emacs
1
Fork 0
mirror of git://git.sv.gnu.org/emacs.git synced 2025-12-21 13:10:37 -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}. to put a new function on such a hook is to call @code{add-hook}.
@xref{Hooks}, for more information about using hooks. @xref{Hooks}, for more information about using hooks.
The variables whose names end in @samp{-functions} are usually @dfn{abnormal The variables whose names end in @samp{-functions} are usually
hooks} (some old code may also use the deprecated @samp{-hooks} suffix); their @dfn{abnormal hooks} (some old code may also use the deprecated
values are lists of functions, but these functions are called in a special way @samp{-hooks} suffix). Their values are lists of functions, but these
(they are passed arguments, or their return values are used). The variables functions are called in a special way: they are either passed
whose names end in @samp{-function} have single functions as their values. 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. This is not an exhaustive list, it only covers the more general hooks.
For example, every major mode defines a hook named 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 @cindex abnormal hook
If the hook variable's name does not end with @samp{-hook}, that 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 indicates it is probably an @dfn{abnormal hook}. That means one of
functions are called with arguments, or their return values are used two things: either that the hook functions are called with arguments,
in some way. The hook's documentation says how the functions are or that their return values are used in some way. The hook's
called. Any functions added to an abnormal hook must follow the documentation says how the functions are called. Any functions added
hook's calling convention. By convention, abnormal hook names end in to an abnormal hook must follow the hook's calling convention. By
@samp{-functions}. convention, abnormal hook names end in @samp{-functions}.
@cindex single-function hook @cindex single-function hook
If the name of the variable ends in @samp{-predicate} or If the name of the variable ends in @samp{-predicate} or