+2003-10-07 Lute Kamstra <lute@gnu.org>
+
+ * modes.texi (Faces for Font Lock): Fix typo.
+ (Hooks): Explain how buffer-local hook variables can refer to
+ global hook variables.
+ Various minor clarifications.
+
2003-10-06 Lute Kamstra <lute@gnu.org>
* tips.texi (Coding Conventions): Mention naming conventions for
2003-09-29 Lute Kamstra <lute@gnu.org>
* modes.texi (Mode Line Data): Explain when symbols in mode-line
- constructs should be marked as risky.
+ constructs should be marked as risky.
Change cons cell into proper list.
(Mode Line Variables): Change cons cell into proper list.
* modes.texi (Mode Line Data): Document the :propertize construct.
(Mode Line Variables): Reorder the descriptions of the variables
- to match their order in the default mode-line-format.
+ to match their order in the default mode-line-format.
Describe the new variables mode-line-position and mode-line-modes.
Update the default values of mode-line-frame-identification,
minor-mode-alist, and default-mode-line-format.
2003-09-26 Richard M. Stallman <rms@gnu.org>
- * buffers.texi, commands.texi, debugging.texi, eval.texi:
+ * buffers.texi, commands.texi, debugging.texi, eval.texi:
* loading.texi, minibuf.texi, text.texi, variables.texi:
Avoid @strong{Note:}.
* abbrevs.texi (Defining Abbrevs): Index no-self-insert.
- * variables.texi (Creating Buffer-Local):
+ * variables.texi (Creating Buffer-Local):
Delete duplicate definition of buffer-local-value.
(File Local Variables): Explain about discarding text props.
Selecting a special element performs:
@example
-(funcall @var{function}
+(funcall @var{function}
@var{index-name} @var{index-position} @var{arguments}@dots{})
@end example
@vindex font-lock-constant-face
Used (typically) for constant names.
-@item font-locl-preprocessor-face
-@vindex font-locl-preprocessor-face
+@item font-lock-preprocessor-face
+@vindex font-lock-preprocessor-face
Used (typically) for preprocessor commands.
@item font-lock-warning-face
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.
+
@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
been added with @code{add-hook}.
@defun run-hooks &rest hookvars
-This function takes one or more 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.
+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.
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
@end defmac
@defun run-hook-with-args hook &rest args
-This function is the way to run an abnormal hook which passes arguments
-to the hook functions. 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. It calls each of
+the hook functions, 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 which passes arguments
-to the hook functions, and stops as soon as any hook function fails. It
-calls each of the hook functions, passing each of them the arguments
-@var{args}, until some hook function returns @code{nil}. Then it stops,
-and returns @code{nil} if some hook function returned @code{nil}.
-Otherwise it returns a non-@code{nil} value.
+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 which passes arguments
-to the hook functions, and stops as soon as any 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.
+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}. The argument @var{function} may be any valid Lisp
-function with the proper number of arguments. For example,
+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,
@example
(add-hook 'text-mode-hook 'my-text-hook-function)
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,
+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.
-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 @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}.
+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.
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.
projects / emacs.git / commitdiff