From: Richard M. Stallman Date: Mon, 13 Oct 2003 19:25:50 +0000 (+0000) Subject: (Hooks): Don't explain local hook details here. X-Git-Tag: ttn-vms-21-2-B4~8546 X-Git-Url: http://git.eshelyaron.com/gitweb/?a=commitdiff_plain;h=da3178e26d1bee1d1951e01987e9defd7a167fb9;p=emacs.git (Hooks): Don't explain local hook details here. Clarify run-hooks and run-hook-with-args a little. Clean up add-hook and remove-hook. --- diff --git a/lispref/modes.texi b/lispref/modes.texi index 6a1eddca0c4..e29dd25587a 100644 --- a/lispref/modes.texi +++ b/lispref/modes.texi @@ -2433,21 +2433,10 @@ are used in other contexts too. For example, the hook 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. - -With @code{add-hook}, you can also add hook functions to the -buffer-local value of a hook variable. If necessary, @code{add-hook} -first makes the hook variable buffer-local and adds @code{t} to the -buffer-local value. The element @code{t} in the buffer-local value of -a hook variable acts as a signal for the various functions that run -hooks to run the default value of the hook variable as well; @code{t} -is basically substituted with the elements of the default value of a -hook variable. Since @code{add-hook} normally adds hook functions to -the front of hook variables, this means that the hook functions in the -buffer-local value are called before the hook functions in the default -value of hook variables. +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 @@ -2480,16 +2469,15 @@ been added with @code{add-hook}. @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 hook variable. These arguments are processed in the -order specified. +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. 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, the elements are called, in order. The hook functions -are called with no arguments. Nowadays, storing a single function in -the hook variable is semi-obsolete; you should always use a list of -functions. +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. For example, here's how @code{emacs-lisp-mode} runs its mode hook: @@ -2511,8 +2499,9 @@ its parent modes' mode hooks until the end. @end defmac @defun run-hook-with-args hook &rest args -This function is the way to run an abnormal hook. It calls each of -the hook functions, passing each of them the arguments @var{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 @@ -2534,10 +2523,9 @@ the last hook function that was called. If all hook functions return @defun add-hook hook function &optional append local This function is the handy way to add function @var{function} to hook -variable @var{hook}. The argument @var{function} is not added if it -is already present on @var{hook} (comparisons are performed with -@code{equal}; @pxref{Equality Predicates}). @var{function} may be any -valid Lisp function with the proper number of arguments. For example, +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) @@ -2546,8 +2534,8 @@ valid Lisp function with the proper number of arguments. For example, @noindent adds @code{my-text-hook-function} to the hook called @code{text-mode-hook}. -You can use @code{add-hook} for abnormal hooks as well as for normal -hooks. +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 @@ -2566,10 +2554,9 @@ functions in the default value as well as in the local value. @defun remove-hook hook function &optional local This function removes @var{function} from the hook variable -@var{hook}. The argument @var{function} is compared with elements of -@var{hook} by means of @code{equal} (@pxref{Equality Predicates}). -This means that you can remove symbols with a function definition as -well as lambda expressions. +@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.