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

3 files changed, 27 insertions, 9 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.