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
@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
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: