[Emacs-diffs] Changes to emacs/lispref/modes.texi

[Lute Kamstra]

Index: emacs/lispref/modes.texi
diff -c emacs/lispref/modes.texi:1.66 emacs/lispref/modes.texi:1.67
*** emacs/lispref/modes.texi:1.66       Fri Oct  3 07:48:55 2003
--- emacs/lispref/modes.texi    Tue Oct  7 08:10:57 2003
***************
*** 1850,1856 ****
  Selecting a special element performs:
  
  @example
! (funcall @var{function} 
           @var{index-name} @var{index-position} @address@hidden)
  @end example
  
--- 1850,1856 ----
  Selecting a special element performs:
  
  @example
! (funcall @var{function}
           @var{index-name} @var{index-position} @address@hidden)
  @end example
  
***************
*** 2331,2338 ****
  @vindex font-lock-constant-face
  Used (typically) for constant names.
  
! @item font-locl-preprocessor-face
! @vindex font-locl-preprocessor-face
  Used (typically) for preprocessor commands.
  
  @item font-lock-warning-face
--- 2331,2338 ----
  @vindex font-lock-constant-face
  Used (typically) for constant names.
  
! @item font-lock-preprocessor-face
! @vindex font-lock-preprocessor-face
  Used (typically) for preprocessor commands.
  
  @item font-lock-warning-face
***************
*** 2436,2441 ****
--- 2436,2453 ----
  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
***************
*** 2465,2473 ****
  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.
  
  If a hook variable has a address@hidden value, that value may be a
  function or a list of functions.  If the value is a function (either a
--- 2477,2486 ----
  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.
  
  If a hook variable has a address@hidden value, that value may be a
  function or a list of functions.  If the value is a function (either a
***************
*** 2497,2529 ****
  @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}.
  @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 address@hidden 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 address@hidden  Then it
! stops, and returns whatever was returned by the last hook function
! that was called.
  @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,
  
  @example
  (add-hook 'text-mode-hook 'my-text-hook-function)
--- 2510,2542 ----
  @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}.
  @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 address@hidden 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
! address@hidden  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} 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)
***************
*** 2537,2554 ****
  
  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 address@hidden, the new hook function goes at
  the end of the hook list and will be executed last.
  
! If @var{local} is address@hidden, that says to add @var{function}
! to the buffer-local hook list instead of to the global hook list.
  @end defun
  
  @defun remove-hook hook function &optional local
! This function removes @var{function} from the hook variable @var{hook}.
  
  If @var{local} is address@hidden, that says to remove @var{function}
  from the buffer-local hook list instead of from the global hook list.
--- 2550,2574 ----
  
  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 address@hidden, the new hook function goes at
  the end of the hook list and will be executed last.
  
! If @var{local} is address@hidden, 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}.  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 address@hidden, that says to remove @var{function}
  from the buffer-local hook list instead of from the global hook list.