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

[Richard M . Stallman]

Index: emacs/lispref/modes.texi
diff -c emacs/lispref/modes.texi:1.109 emacs/lispref/modes.texi:1.110
*** emacs/lispref/modes.texi:1.109      Mon May 23 12:01:08 2005
--- emacs/lispref/modes.texi    Sun May 29 08:28:51 2005
***************
*** 1117,1123 ****
  @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
--- 1117,1123 ----
  @node Mode Hooks
  @subsection Mode Hooks
  
!   The two last things a major mode function should do is 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
***************
*** 1125,1169 ****
  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
--- 1125,1177 ----
  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}.
! 
!   These conventions are new in Emacs 22, and some major modes
! implemented by users do not follow them yet.  So if you put a function
! onto @code{after-change-major-mode-hook}, keep in mind that some modes
! will fail to run it.  If user complains about that, you can respond,
! ``That major mode fails to follow Emacs conventions, and that's why it
! fails to work.  Please fix the major mode.''  In most cases, that is
! good enough, so go ahead and use @code{after-change-major-mode-hook}.
! However, if a certain feature needs to be completely reliable,
! it should not use @code{after-change-major-mode-hook} as of yet.
! 
!   When you defined a major mode using @code{define-derived-mode}, it
! automatically makes sure these conventions are followed.  If you
! define a major mode ``from scratch'', not using
! @code{define-derived-mode}, make sure the major mode command follows
! these and other conventions.  @xref{Major Mode Conventions}.  You use
! these functions to do it properly.
  
  @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 it also runs
  @code{after-change-major-mode-hook}.
+ 
+ When the call to this function is dynamically inside a
+ @code{delay-mode-hooks} form, this function does not run any hooks.
+ Instead, it arranges for the next call to @code{run-mode-hooks} to run
+ @var{hookvars}.
  @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}.  This is the proper way for a major mode
! command to invoke its parent mode.
  @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 the last thing
! @code{run-mode-hooks} does is run @code{after-change-major-mode-hook}.
  @end defvar
  
  @node Minor Modes