Re: enriched-mode and switching major modes.

[Luc Teirlinck <teirllm@dms.auburn.edu>]

Richard Stallman wrote:

   This change seems good to me.  Please install it.

   Could you also add after-change-major-mode-hook to NEWS
   and to lispref/modes.texi?

I installed the change and a NEWS entry.  In as far as the changes to
the Elisp manual (and docstrings) are concerned, what about the
following patches?

===File ~/modes.texi-diff===================================
*** modes.texi	22 Aug 2004 13:05:50 -0500	1.79
--- modes.texi	19 Sep 2004 14:15:07 -0500	
***************
*** 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
***************
*** 287,292 ****
--- 287,293 ----
  @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.)
+ @xref{Derived Modes}, and @ref{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
--- 576,582 ----
  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
***************
*** 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
--- 2564,2600 ----
  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.
  @end defun
  
  @defun run-mode-hooks &rest hookvars
! Major modes should run their mode hook using this function.  It is
! similar to @code{run-hooks}, but if the variable
! @code{delay-mode-hooks} is non-@code{nil}, this function delays
! running @var{hookvars}, as well as any previously delayed hooks, until
! a later call.  If that variable is @code{nil}, @code{run-mode-hooks}
! runs @code{after-change-major-mode-hook} (see below) before running
! any delayed hooks in order and finally @var{hookvars}.
  @end defun
  
+ @defvar delay-mode-hooks
+ If the value of this variable is non-@code{nil}, @code{run-mode-hooks}
+ delays running any hooks until a later call..
+ @end defvar
+ 
  @defmac delay-mode-hooks body...
! This macro executes the @var{body} forms with the variable
! @code{delay-mode-hooks} buffer locally bound to @code{t} in the
! current buffer.  This macro enables a derived mode to arrange not to
! run its parent modes' mode hooks until the end.
  @end defmac
  
+ @defvar after-change-major-mode-hook
+ @code{run-mode-hooks} runs this mode independent normal hook before
+ the mode hooks.  This hook is also called at the end of
+ @code{fundamental-mode} (which is the only major mode function that
+ does not run @code{run-mode-hooks} at its end).
+ @end defvar
+ 
  @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
============================================================

===File ~/hooks.texi-diff===================================
*** hooks.texi	06 Aug 2004 20:46:37 -0500	1.17
--- hooks.texi	19 Sep 2004 12:58:27 -0500	
***************
*** 35,40 ****
--- 35,41 ----
  @table @code
  @item activate-mark-hook
  @item after-change-functions
+ @item after-change-major-mode-hook
  @item after-init-hook
  @item after-insert-file-functions
  @item after-make-frame-functions
============================================================

===File ~/subr.el-diff======================================
*** subr.el	19 Sep 2004 09:52:28 -0500	1.410
--- subr.el	19 Sep 2004 13:43:41 -0500	
***************
*** 1944,1949 ****
--- 1944,1951 ----
  (defun run-mode-hooks (&rest hooks)
    "Run mode hooks `delayed-mode-hooks' and HOOKS, or delay HOOKS.
  Execution is delayed if `delay-mode-hooks' is non-nil.
+ If `delay-mode-hooks' is nil, run `after-change-major-mode-hook'
+ before running the mode hooks.
  Major mode functions should use this."
    (if delay-mode-hooks
        ;; Delaying case.
============================================================