Document change-major-mode-after-body-hook

* doc/lispref/hooks.texi (Standard Hooks):
* doc/lispref/modes.texi (Major Mode Conventions, Mode Hooks):
Document change-major-mode-after-body-hook.

* lisp/subr.el (run-mode-hooks): Doc fix.

* etc/NEWS: Markup

6 files changed, 38 insertions, 13 deletions

diff --git a/doc/lispref/ChangeLog b/doc/lispref/ChangeLog
index 6a8b7750f0b..1ba070dccc0 100644
--- a/doc/lispref/ChangeLog
+++ b/doc/lispref/ChangeLog
@@ -1,3 +1,9 @@
+2012-02-02  Glenn Morris  <rgm@gnu.org>
+
+        * hooks.texi (Standard Hooks):
+        * modes.texi (Major Mode Conventions, Mode Hooks):
+        Document change-major-mode-after-body-hook.
+
 2012-02-01  Glenn Morris  <rgm@gnu.org>
 
         * modes.texi (Defining Minor Modes):
diff --git a/doc/lispref/hooks.texi b/doc/lispref/hooks.texi
index 95655324ab4..b311da66110 100644
--- a/doc/lispref/hooks.texi
+++ b/doc/lispref/hooks.texi
@@ -127,6 +127,9 @@ not exactly a hook, but does a similar job.
 @xref{Calendar Customizing,,, emacs}.
 @end ifnottex
 
+@item change-major-mode-after-body-hook
+@xref{Mode Hooks}.
+
 @item change-major-mode-hook
 @xref{Creating Buffer-Local}.
 
diff --git a/doc/lispref/modes.texi b/doc/lispref/modes.texi
index f8a21e003e0..e142be44e0d 100644
--- a/doc/lispref/modes.texi
+++ b/doc/lispref/modes.texi
@@ -468,8 +468,9 @@ other packages would interfere with them.
 @cindex major mode hook
 Each major mode should have a normal @dfn{mode hook} named
 @code{@var{modename}-mode-hook}.  The very last thing the major mode command
-should do is to call @code{run-mode-hooks}.  This runs the mode hook,
-and then runs the normal hook @code{after-change-major-mode-hook}.
+should do is to call @code{run-mode-hooks}.  This runs the normal
+hook @code{change-major-mode-after-body-hook}, the mode hook,
+and then the normal hook @code{after-change-major-mode-hook}.
 @xref{Mode Hooks}.
 
 @item
@@ -939,8 +940,9 @@ before it runs the mode hook variable @code{@var{mode}-hook}.
 @node Mode Hooks
 @subsection Mode Hooks
 
-  Every major mode command should finish by running its mode hook and
-the mode-independent normal hook @code{after-change-major-mode-hook}.
+  Every major mode command should finish by running the mode-independent
+normal hook @code{change-major-mode-after-body-hook}, its mode hook,
+and the normal hook @code{after-change-major-mode-hook}.
 It does this by calling @code{run-mode-hooks}.  If the major mode is a
 derived mode, that is if it calls another major mode (the parent mode)
 in its body, it should do this inside @code{delay-mode-hooks} so that
@@ -949,11 +951,12 @@ call to @code{run-mode-hooks} runs the parent's mode hook too.
 @xref{Major Mode Conventions}.
 
   Emacs versions before Emacs 22 did not have @code{delay-mode-hooks}.
-When user-implemented major modes have not been updated to use it,
-they won't entirely follow these conventions: they may run the
-parent's mode hook too early, or fail to run
-@code{after-change-major-mode-hook}.  If you encounter such a major
-mode, please correct it to follow these conventions.
+Versions before 24 did not have @code{change-major-mode-after-body-hook}.
+When user-implemented major modes do not use @code{run-mode-hooks} and
+have not been updated to use these newer features, they won't entirely
+follow these conventions: they may run the parent's mode hook too early,
+or fail to run @code{after-change-major-mode-hook}.  If you encounter
+such a major mode, please correct it to follow these conventions.
 
   When you defined a major mode using @code{define-derived-mode}, it
 automatically makes sure these conventions are followed.  If you
@@ -963,6 +966,7 @@ use the following functions to handle these conventions automatically.
 @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{change-major-mode-after-body-hook} and
 @code{after-change-major-mode-hook}.
 
 When this function is called during the execution of a
@@ -982,6 +986,11 @@ The hooks will actually run during the next call to
 construct.
 @end defmac
 
+@defvar change-major-mode-after-body-hook
+This is a normal hook run by @code{run-mode-hooks}.  It is run before
+the mode hooks.
+@end defvar
+
 @defvar after-change-major-mode-hook
 This is a normal hook run by @code{run-mode-hooks}.  It is run at the
 very end of every properly-written major mode command.
diff --git a/etc/NEWS b/etc/NEWS
index 4aaefe70c4f..0138fa5192e 100644
--- a/etc/NEWS
+++ b/etc/NEWS
@@ -1287,6 +1287,7 @@ should be derived.
 modes, e.g. (add-hook 'prog-mode-hook 'flyspell-prog-mode) to enable
 on-the-fly spell checking for comments and strings.
 
++++
 *** New hook `change-major-mode-after-body-hook', run by
 `run-mode-hooks' just before any other mode hooks.
 
diff --git a/lisp/ChangeLog b/lisp/ChangeLog
index cc6aecd7a26..4290c5e820d 100644
--- a/lisp/ChangeLog
+++ b/lisp/ChangeLog
@@ -1,3 +1,7 @@
+2012-02-02  Glenn Morris  <rgm@gnu.org>
+
+        * subr.el (run-mode-hooks): Doc fix.
+
 2012-02-02  Juri Linkov  <juri@jurta.org>
 
         * image-mode.el (image-toggle-display-image): Remove tautological
diff --git a/lisp/subr.el b/lisp/subr.el
index c9e213c86a0..36bca654208 100644
--- a/lisp/subr.el
+++ b/lisp/subr.el
@@ -1539,10 +1539,12 @@ if it is empty or a duplicate."
 
 (defun run-mode-hooks (&rest hooks)
   "Run mode hooks `delayed-mode-hooks' and HOOKS, or delay HOOKS.
-Execution is delayed if the variable `delay-mode-hooks' is non-nil.
-Otherwise, runs the mode hooks and then `after-change-major-mode-hook'.
-Major mode functions should use this instead of `run-hooks' when running their
-FOO-mode-hook."
+If the variable `delay-mode-hooks' is non-nil, does not run any hooks,
+just adds the HOOKS to the list `delayed-mode-hooks'.
+Otherwise, runs hooks in the sequence: `change-major-mode-after-body-hook',
+`delayed-mode-hooks' (in reverse order), HOOKS, and finally
+`after-change-major-mode-hook'.  Major mode functions should use
+this instead of `run-hooks' when running their FOO-mode-hook."
   (if delay-mode-hooks
       ;; Delaying case.
       (dolist (hook hooks)