+@node Hooks
+@section Hooks
+@cindex hooks
+
+ A @dfn{hook} is a variable where you can store a function or functions
+to be called on a particular occasion by an existing program. Emacs
+provides hooks for the sake of customization. Most often, hooks are set
+up in the init file (@pxref{Init File}), but Lisp programs can set them also.
+@xref{Standard Hooks}, for a list of standard hook variables.
+
+@cindex normal hook
+ Most of the hooks in Emacs are @dfn{normal hooks}. These variables
+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
+buffer-local variable assignments already made by the mode. Most
+minor modes also run a mode hook at their end. 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
+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. You can add hooks either
+globally or buffer-locally with @code{add-hook}.
+
+@cindex abnormal hook
+ If the hook variable's name does not end with @samp{-hook}, that
+indicates it is probably an @dfn{abnormal hook}. Then 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, notably those ending in @samp{-hooks}, 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 example that uses a mode hook to turn on Auto Fill mode when
+in Lisp Interaction mode:
+
+@example
+(add-hook 'lisp-interaction-mode-hook 'turn-on-auto-fill)
+@end example
+
+ At the appropriate time, Emacs uses the @code{run-hooks} function to
+run particular hooks.
+
+@defun run-hooks &rest hookvars
+This function takes one or more normal hook variable names as
+arguments, and runs each hook in turn. Each argument should be a
+symbol that is a normal hook variable. These arguments are processed
+in the order specified.
+
+If a hook variable has a non-@code{nil} value, that value may be a
+function or a list of functions. (The former option is considered
+obsolete.) If the value is a function (either a lambda expression or
+a symbol with a function definition), it is called. If it is a list
+that isn't a function, its elements are called, consecutively. All
+the hook functions are called with no arguments.
+@end defun
+
+@defun run-hook-with-args hook &rest args
+This function is the way to run an abnormal hook and always call all
+of the hook functions. It calls each of the hook functions one by
+one, passing each of them the arguments @var{args}.
+@end defun
+
+@defun run-hook-with-args-until-failure hook &rest args
+This function is the way to run an abnormal hook until one of the hook
+functions fails. It calls each of the hook functions, passing each of
+them the arguments @var{args}, until some hook function returns
+@code{nil}. It then stops and returns @code{nil}. If none of the
+hook functions return @code{nil}, it returns a non-@code{nil} value.
+@end defun
+
+@defun run-hook-with-args-until-success hook &rest args
+This function is the way to run an abnormal hook until a hook function
+succeeds. It calls each of the hook functions, passing each of them
+the arguments @var{args}, until some hook function returns
+non-@code{nil}. Then it stops, and returns whatever was returned by
+the last hook function that was called. If all hook functions return
+@code{nil}, it returns @code{nil} as well.
+@end defun
+
+@defun add-hook hook function &optional append local
+This function is the handy way to add function @var{function} to hook
+variable @var{hook}. You can use it for abnormal hooks as well as for
+normal hooks. @var{function} can be any Lisp function that can accept
+the proper number of arguments for @var{hook}. For example,
+
+@example
+(add-hook 'text-mode-hook 'my-text-hook-function)
+@end example
+
+@noindent
+adds @code{my-text-hook-function} to the hook called @code{text-mode-hook}.
+
+If @var{function} is already present in @var{hook} (comparing using
+@code{equal}), then @code{add-hook} does not add it a second time.
+
+It is best to design your hook functions so that the order in which they
+are executed does not matter. Any dependence on the order is ``asking
+for trouble''. However, the order is predictable: normally,
+@var{function} goes at the front of the hook list, so it will be
+executed first (barring another @code{add-hook} call). If the optional
+argument @var{append} is non-@code{nil}, the new hook function goes at
+the end of the hook list and will be executed last.
+
+@code{add-hook} can handle the cases where @var{hook} is void or its
+value is a single function; it sets or changes the value to a list of
+functions.
+
+If @var{local} is non-@code{nil}, that says to add @var{function} to
+the buffer-local hook list instead of to the global hook list. If
+needed, this makes the hook buffer-local and adds @code{t} to the
+buffer-local value. The latter acts as a flag to run the hook
+functions in the default value as well as in the local value.
+@end defun
+
+@defun remove-hook hook function &optional local
+This function removes @var{function} from the hook variable
+@var{hook}. It compares @var{function} with elements of @var{hook}
+using @code{equal}, so it works for both symbols and lambda
+expressions.
+
+If @var{local} is non-@code{nil}, that says to remove @var{function}
+from the buffer-local hook list instead of from the global hook list.
+@end defun
+