From 12f381b73de44148af86efd823ff69c637dedeec Mon Sep 17 00:00:00 2001 From: Glenn Morris Date: Wed, 1 Feb 2012 21:57:26 -0500 Subject: [PATCH] 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 --- doc/lispref/ChangeLog | 6 ++++++ doc/lispref/hooks.texi | 3 +++ doc/lispref/modes.texi | 27 ++++++++++++++++++--------- etc/NEWS | 1 + lisp/ChangeLog | 4 ++++ lisp/subr.el | 10 ++++++---- 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 + + * hooks.texi (Standard Hooks): + * modes.texi (Major Mode Conventions, Mode Hooks): + Document change-major-mode-after-body-hook. + 2012-02-01 Glenn Morris * 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 + + * subr.el (run-mode-hooks): Doc fix. + 2012-02-02 Juri Linkov * 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) -- 2.11.4.GIT