Explain better about abnormal hooks.

2 files changed, 39 insertions, 29 deletions

diff --git a/lispref/hooks.texi b/lispref/hooks.texi
index 18f8bcfcad5..046ac7cc5d5 100644
--- a/lispref/hooks.texi
+++ b/lispref/hooks.texi
@@ -11,19 +11,22 @@ functions to be called from within Emacs on suitable occasions.
 
 Most of these variables have names ending with @samp{-hook}.  They are
 @dfn{normal hooks}, run by means of @code{run-hooks}.  The value of such
-a hook is a list of functions.  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.
+a hook is a list of functions; the functions are called with no
+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{-function} have single functions
-as their values.  Usually there is a specific reason why the variable is
-not a normal hook, such as the need to pass arguments to the function.
-(In older Emacs versions, some of these variables had names ending in
-@samp{-hook} even though they were not normal hooks.)
+The variables whose names end in @samp{-hooks} or @samp{-functions} are
+usually @dfn{abnormal hooks}; their values are lists of functions, but
+these functions are called in a special way (they are passed arguments,
+or their values are used).  A few of these variables are actually normal
+hooks which were named before we established the convention that normal
+hooks' names should end in @samp{-hook}.
 
-The variables whose names end in @samp{-hooks} or @samp{-functions} have
-lists of functions as their values, but these functions are called in a
-special way (they are passed arguments, or else their values are used).
+The variables whose names end in @samp{-function} have single functions
+as their values.  (In older Emacs versions, some of these variables had
+names ending in @samp{-hook} even though they were not normal hooks;
+however, we have renamed all of those.)
 
 @c !!! need  xref  to where each hook is documented or else document it
 @c by specifying what is expected, and when it is called relative to
diff --git a/lispref/modes.texi b/lispref/modes.texi
index e7b164f3b2c..10c71d00993 100644
--- a/lispref/modes.texi
+++ b/lispref/modes.texi
@@ -1262,10 +1262,17 @@ up in the @file{.emacs} file, but Lisp programs can set them also.
 @xref{Standard Hooks}, for a list of standard hook variables.
 
   Most of the hooks in Emacs are @dfn{normal hooks}.  These variables
-contain lists of functions to be called with no arguments.  The reason
-most hooks are normal hooks is so that you can use them in a uniform
-way.  You can always tell when a hook is a normal hook, because its 
-name ends in @samp{-hook}.
+contain lists of functions to be called with no arguments.  When the
+hook name ends in @samp{-hook}, that tells you it is normal.  We try to
+make all hooks normal, as much as possible, so that you can use them in
+a uniform way.
+
+  Every major mode function is supposed to run a normal hook called the
+@dfn{mode hook} as the last step of initialization.  This makes it easy
+for a user to customize the behavior of the mode, by overriding the
+local variable assignments already made by the mode.  But hooks are 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 normal hook is by
 calling @code{add-hook} (see below).  The hook functions may be any of
@@ -1273,20 +1280,20 @@ 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.
 
-  As for abnormal hooks, those whose names end in @samp{-function} have
-a value that is a single function.  Those whose names end in
-@samp{-hooks} have a value that is a list of functions.  Any hook that
-is abnormal is abnormal because a normal hook won't do the job; either
-the functions are called with arguments, or their values are meaningful.
-The name shows you that the hook is abnormal and that you should look at
-its documentation string to see how to use it properly.
-
-  Major mode functions are supposed to run a hook called the @dfn{mode
-hook} as the last step of initialization.  This makes it easy for a user
-to customize the behavior of the mode, by overriding the local variable
-assignments already made by the mode.  But hooks are used in other
-contexts too.  For example, the hook @code{suspend-hook} runs just
-before Emacs suspends itself (@pxref{Suspending Emacs}).
+  If the hook variable's name does not end with @samp{-hook}, that
+indicates it is probably an abnormal hook; you should look at its
+documentation to see how to use the hook properly.
+
+  If the variable's name ends in @samp{-functions} or @samp{-hooks},
+then the value is a list of functions, but it is abnormal in that either
+these functions are called with arguments or their values are used in
+some way.  You can use @code{add-hook} to add a function to the list,
+but you must take care in writing the function.  (A few of these
+variables are actually normal hooks which were named before we
+established the convention of using @samp{-hook} for them.)
+
+  If the variable's name ends in @samp{-function}, then its value
+is just a single function, not a list of functions.
 
   Here's an expression that uses a mode hook to turn on Auto Fill mode
 when in Lisp Interaction mode: