From 4fd5c8df67e2eb41dd0ea6d95586bbd8d09cc482 Mon Sep 17 00:00:00 2001 From: Stefan Kangas Date: Sat, 23 Oct 2021 20:03:34 +0200 Subject: [PATCH] Clarify abnormal hook documentation * doc/lispref/hooks.texi (Standard Hooks): * doc/lispref/modes.texi (Hooks): Clarify wording of "abnormal hook" documentation. (Bug#34588) --- doc/lispref/hooks.texi | 12 +++++++----- doc/lispref/modes.texi | 12 ++++++------ 2 files changed, 13 insertions(+), 11 deletions(-) diff --git a/doc/lispref/hooks.texi b/doc/lispref/hooks.texi index feec8b24f46..e9d1e270d8e 100644 --- a/doc/lispref/hooks.texi +++ b/doc/lispref/hooks.texi @@ -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 diff --git a/doc/lispref/modes.texi b/doc/lispref/modes.texi index ee55f982d02..ed0c535867f 100644 --- a/doc/lispref/modes.texi +++ b/doc/lispref/modes.texi @@ -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 -- 2.39.5