[Emacs-diffs] /srv/bzr/emacs/trunk r107054: Document change-major-mode-after-body-hook

[Glenn Morris]

------------------------------------------------------------
revno: 107054
committer: Glenn Morris <address@hidden>
branch nick: trunk
timestamp: Wed 2012-02-01 21:57:26 -0500
message:
  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
modified:
  doc/lispref/ChangeLog
  doc/lispref/hooks.texi
  doc/lispref/modes.texi
  etc/NEWS
  lisp/ChangeLog
  lisp/subr.el

=== modified file 'doc/lispref/ChangeLog'
--- a/doc/lispref/ChangeLog     2012-02-01 08:32:31 +0000
+++ b/doc/lispref/ChangeLog     2012-02-02 02:57:26 +0000
@@ -1,3 +1,9 @@
+2012-02-02  Glenn Morris  <address@hidden>
+
+       * hooks.texi (Standard Hooks):
+       * modes.texi (Major Mode Conventions, Mode Hooks):
+       Document change-major-mode-after-body-hook.
+
 2012-02-01  Glenn Morris  <address@hidden>
 
        * modes.texi (Defining Minor Modes):

=== modified file 'doc/lispref/hooks.texi'
--- a/doc/lispref/hooks.texi    2012-01-19 07:21:25 +0000
+++ b/doc/lispref/hooks.texi    2012-02-02 02:57:26 +0000
@@ -127,6 +127,9 @@
 @xref{Calendar Customizing,,, emacs}.
 @end ifnottex
 
address@hidden change-major-mode-after-body-hook
address@hidden Hooks}.
+
 @item change-major-mode-hook
 @xref{Creating Buffer-Local}.
 

=== modified file 'doc/lispref/modes.texi'
--- a/doc/lispref/modes.texi    2012-02-01 21:19:30 +0000
+++ b/doc/lispref/modes.texi    2012-02-02 02:57:26 +0000
@@ -468,8 +468,9 @@
 @cindex major mode hook
 Each major mode should have a normal @dfn{mode hook} named
 @address@hidden  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 @@
 @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 @@
 @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
address@hidden  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 @@
 @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
address@hidden and
 @code{after-change-major-mode-hook}.
 
 When this function is called during the execution of a
@@ -982,6 +986,11 @@
 construct.
 @end defmac
 
address@hidden change-major-mode-after-body-hook
+This is a normal hook run by @code{run-mode-hooks}.  It is run before
+the mode hooks.
address@hidden 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.

=== modified file 'etc/NEWS'
--- a/etc/NEWS  2012-02-01 08:39:29 +0000
+++ b/etc/NEWS  2012-02-02 02:57:26 +0000
@@ -1287,6 +1287,7 @@
 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.
 

=== modified file 'lisp/ChangeLog'
--- a/lisp/ChangeLog    2012-02-02 00:49:06 +0000
+++ b/lisp/ChangeLog    2012-02-02 02:57:26 +0000
@@ -1,3 +1,7 @@
+2012-02-02  Glenn Morris  <address@hidden>
+
+       * subr.el (run-mode-hooks): Doc fix.
+
 2012-02-02  Juri Linkov  <address@hidden>
 
        * image-mode.el (image-toggle-display-image): Remove tautological

=== modified file 'lisp/subr.el'
--- a/lisp/subr.el      2012-01-23 02:10:36 +0000
+++ b/lisp/subr.el      2012-02-02 02:57:26 +0000
@@ -1539,10 +1539,12 @@
 
 (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)