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

[Miles Bader]

Index: emacs/lispref/modes.texi
diff -c emacs/lispref/modes.texi:1.49.2.9 emacs/lispref/modes.texi:1.49.2.10
*** emacs/lispref/modes.texi:1.49.2.9   Sat Sep  4 09:26:23 2004
--- emacs/lispref/modes.texi    Wed Oct  6 05:21:50 2004
***************
*** 1,6 ****
  @c -*-texinfo-*-
  @c This is part of the GNU Emacs Lisp Reference Manual.
! @c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 1999, 2003
  @c   Free Software Foundation, Inc.
  @c See the file elisp.texi for copying conditions.
  @setfilename ../info/modes
--- 1,6 ----
  @c -*-texinfo-*-
  @c This is part of the GNU Emacs Lisp Reference Manual.
! @c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 1999, 2003, 2004
  @c   Free Software Foundation, Inc.
  @c See the file elisp.texi for copying conditions.
  @setfilename ../info/modes
***************
*** 103,108 ****
--- 103,109 ----
  * Mode Help::               Finding out how to use a mode.
  * Derived Modes::           Defining a new major mode based on another major
                                mode.
+ * Mode Hooks::              Hooks run at the end of major mode functions.
  @end menu
  
  @node Major Mode Conventions
***************
*** 276,282 ****
  Each major mode should have a @dfn{mode hook} named
  @address@hidden  The major mode command should run that
  hook, with @code{run-mode-hooks}, as the very last thing it
! does.  @xref{Hooks}.
  
  @item
  The major mode command may start by calling some other major mode
--- 277,283 ----
  Each major mode should have a @dfn{mode hook} named
  @address@hidden  The major mode command should run that
  hook, with @code{run-mode-hooks}, as the very last thing it
! does.  @xref{Mode Hooks}.
  
  @item
  The major mode command may start by calling some other major mode
***************
*** 284,292 ****
  settings.  A mode that does this is called a @dfn{derived mode}.  The
  recommended way to define one is to use @code{define-derived-mode},
  but this is not required.  Such a mode should use
! @code{delay-mode-hooks} around its entire body, including the call to
! the parent mode command and the final call to @code{run-mode-hooks}.
! (Using @code{define-derived-mode} does this automatically.)
  
  @item
  If something special should be done if the user switches a buffer from
--- 285,295 ----
  settings.  A mode that does this is called a @dfn{derived mode}.  The
  recommended way to define one is to use @code{define-derived-mode},
  but this is not required.  Such a mode should use
! @code{delay-mode-hooks} around its entire body (including the call to
! the parent mode command) @emph{except} for the final call to
! @code{run-mode-hooks}, which runs the derived mode's hook.  (Using
! @code{define-derived-mode} does this automatically.)  @xref{Derived
! Modes}, and @ref{Mode Hooks}.
  
  @item
  If something special should be done if the user switches a buffer from
***************
*** 575,581 ****
  in particular.  Other major modes are defined in effect by comparison
  with this one---their definitions say what to change, starting from
  Fundamental mode.  The @code{fundamental-mode} function does @emph{not}
! run any hooks; you're not supposed to customize it.  (If you want Emacs
  to behave differently in Fundamental mode, change the @emph{global}
  state of Emacs.)
  @end deffn
--- 578,584 ----
  in particular.  Other major modes are defined in effect by comparison
  with this one---their definitions say what to change, starting from
  Fundamental mode.  The @code{fundamental-mode} function does @emph{not}
! run any mode hooks; you're not supposed to customize it.  (If you want Emacs
  to behave differently in Fundamental mode, change the @emph{global}
  state of Emacs.)
  @end deffn
***************
*** 808,813 ****
--- 811,868 ----
  @code{define-derived-mode} does that automatically.
  @end defmac
  
+ @node Mode Hooks
+ @subsection Mode Hooks
+ 
+ The two last things a major mode function does is to run its mode
+ hook and finally the mode independent normal hook
+ @code{after-change-major-mode-hook}.  If the major mode is a derived
+ mode, that is if it calls another major mode (the parent mode) in its
+ body, then the parent's mode hook is run just before the derived
+ mode's hook.  Neither the parent's mode hook nor
+ @code{after-change-major-mode-hook} are run at the end of the actual
+ call to the parent mode.  This applies recursively if the parent mode
+ has itself a parent.  That is, the mode hooks of all major modes called
+ directly or indirectly by the major mode function are all run in
+ sequence at the end, just before @code{after-change-major-mode-hook}.
+ 
+ If you are customizing a major mode, rather than defining one, the
+ above is all you need to know about the hooks run at the end of a
+ major mode.  This also applies if you use @code{define-derived-mode}
+ to define a major mode, because that macro will automatically
+ implement the above for you.
+ 
+ Programmers wishing to define a major mode without using
+ @code{define-derived-mode}, should make sure that their major mode
+ follows the above conventions.  @xref{Major Mode Conventions}, for how
+ this should be accomplished.  Below, we give some implementation
+ details.
+ 
+ @defun run-mode-hooks &rest hookvars
+ Major modes should run their mode hook using this function.  It is
+ similar to @code{run-hooks} (@pxref{Hooks}), but if run inside a
+ @code{delay-mode-hooks} form, this function does not run any hooks.
+ Instead, it arranges for @var{hookvars} to be run at a later call to
+ the function.  Otherwise, @code{run-mode-hooks} runs any delayed hooks
+ in order, then @var{hookvars} and finally
+ @code{after-change-major-mode-hook}.
+ @end defun
+ 
+ @defmac delay-mode-hooks body...
+ This macro executes @var{body} like @code{progn}, but all calls to
+ @code{run-mode-hooks} inside @var{body} delay running their hooks.
+ They will be run by the first call to @code{run-mode-hooks} after exit
+ from @code{delay-mode-hooks}.
+ @end defmac
+ 
+ @defvar after-change-major-mode-hook
+ Every major mode function should run this normal hook at its very end.
+ It normally does not need to do so explicitly.  Indeed, a major mode
+ function should normally run its mode hook with @code{run-mode-hooks}
+ as the very last thing it does and @code{run-mode-hooks} runs
+ @code{after-change-major-mode-hook} at its very end.
+ @end defvar
+ 
  @node Minor Modes
  @section Minor Modes
  @cindex minor mode
***************
*** 2087,2093 ****
  Obviously, fontification of the subexpression numbered @var{subexp} will
  not occur.  However, fontification of other subexpressions (and other
  regexps) will continue.  If @var{laxmatch} is @code{nil}, and the
! specified subexpression is missing, then an error is signalled which
  terminates search-based fontification.
  
  Here are some examples of elements of this kind, and what they do:
--- 2142,2148 ----
  Obviously, fontification of the subexpression numbered @var{subexp} will
  not occur.  However, fontification of other subexpressions (and other
  regexps) will continue.  If @var{laxmatch} is @code{nil}, and the
! specified subexpression is missing, then an error is signaled which
  terminates search-based fontification.
  
  Here are some examples of elements of this kind, and what they do:
***************
*** 2450,2456 ****
  
  For buffers not visiting a file to have their state saved, the major
  mode must bind the buffer local variable @code{desktop-save-buffer} to
! a non-nil value.
  
  @defvar desktop-save-buffer
  If this buffer-local variable is address@hidden, the buffer will have
--- 2505,2511 ----
  
  For buffers not visiting a file to have their state saved, the major
  mode must bind the buffer local variable @code{desktop-save-buffer} to
! a address@hidden value.
  
  @defvar desktop-save-buffer
  If this buffer-local variable is address@hidden, the buffer will have
***************
*** 2563,2588 ****
  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:
- 
- @example
- (run-hooks 'emacs-lisp-mode-hook)
- @end example
- @end defun
- 
- @defun run-mode-hooks &rest hookvars
- Like @code{run-hooks}, but is affected by the @code{delay-mode-hooks}
- macro.
  @end defun
  
- @defmac delay-mode-hooks body...
- This macro executes the @var{body} forms but defers all calls to
- @code{run-mode-hooks} within them until the end of @var{body}.
- This macro enables a derived mode to arrange not to run
- 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 and always call all
  of the hook functions.  It calls each of the hook functions one by
--- 2618,2625 ----