Commit 12f381b7 authored by Glenn Morris's avatar Glenn Morris
Browse files

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
parent 44f92739
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> 2012-02-01 Glenn Morris <rgm@gnu.org>
* modes.texi (Defining Minor Modes): * modes.texi (Defining Minor Modes):
......
...@@ -127,6 +127,9 @@ not exactly a hook, but does a similar job. ...@@ -127,6 +127,9 @@ not exactly a hook, but does a similar job.
@xref{Calendar Customizing,,, emacs}. @xref{Calendar Customizing,,, emacs}.
@end ifnottex @end ifnottex
@item change-major-mode-after-body-hook
@xref{Mode Hooks}.
@item change-major-mode-hook @item change-major-mode-hook
@xref{Creating Buffer-Local}. @xref{Creating Buffer-Local}.
......
...@@ -468,8 +468,9 @@ other packages would interfere with them. ...@@ -468,8 +468,9 @@ other packages would interfere with them.
@cindex major mode hook @cindex major mode hook
Each major mode should have a normal @dfn{mode hook} named Each major mode should have a normal @dfn{mode hook} named
@code{@var{modename}-mode-hook}. The very last thing the major mode command @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, should do is to call @code{run-mode-hooks}. This runs the normal
and then runs the normal hook @code{after-change-major-mode-hook}. 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}. @xref{Mode Hooks}.
@item @item
...@@ -939,8 +940,9 @@ before it runs the mode hook variable @code{@var{mode}-hook}. ...@@ -939,8 +940,9 @@ before it runs the mode hook variable @code{@var{mode}-hook}.
@node Mode Hooks @node Mode Hooks
@subsection Mode Hooks @subsection Mode Hooks
Every major mode command should finish by running its mode hook and Every major mode command should finish by running the mode-independent
the mode-independent normal hook @code{after-change-major-mode-hook}. 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 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) 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 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. ...@@ -949,11 +951,12 @@ call to @code{run-mode-hooks} runs the parent's mode hook too.
@xref{Major Mode Conventions}. @xref{Major Mode Conventions}.
Emacs versions before Emacs 22 did not have @code{delay-mode-hooks}. Emacs versions before Emacs 22 did not have @code{delay-mode-hooks}.
When user-implemented major modes have not been updated to use it, Versions before 24 did not have @code{change-major-mode-after-body-hook}.
they won't entirely follow these conventions: they may run the When user-implemented major modes do not use @code{run-mode-hooks} and
parent's mode hook too early, or fail to run have not been updated to use these newer features, they won't entirely
@code{after-change-major-mode-hook}. If you encounter such a major follow these conventions: they may run the parent's mode hook too early,
mode, please correct it to follow these conventions. 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 When you defined a major mode using @code{define-derived-mode}, it
automatically makes sure these conventions are followed. If you automatically makes sure these conventions are followed. If you
...@@ -963,6 +966,7 @@ use the following functions to handle these conventions automatically. ...@@ -963,6 +966,7 @@ use the following functions to handle these conventions automatically.
@defun run-mode-hooks &rest hookvars @defun run-mode-hooks &rest hookvars
Major modes should run their mode hook using this function. It is Major modes should run their mode hook using this function. It is
similar to @code{run-hooks} (@pxref{Hooks}), but it also runs 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}. @code{after-change-major-mode-hook}.
When this function is called during the execution of a When this function is called during the execution of a
...@@ -982,6 +986,11 @@ The hooks will actually run during the next call to ...@@ -982,6 +986,11 @@ The hooks will actually run during the next call to
construct. construct.
@end defmac @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 @defvar after-change-major-mode-hook
This is a normal hook run by @code{run-mode-hooks}. It is run at the 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. very end of every properly-written major mode command.
......
...@@ -1287,6 +1287,7 @@ should be derived. ...@@ -1287,6 +1287,7 @@ should be derived.
modes, e.g. (add-hook 'prog-mode-hook 'flyspell-prog-mode) to enable modes, e.g. (add-hook 'prog-mode-hook 'flyspell-prog-mode) to enable
on-the-fly spell checking for comments and strings. on-the-fly spell checking for comments and strings.
+++
*** New hook `change-major-mode-after-body-hook', run by *** New hook `change-major-mode-after-body-hook', run by
`run-mode-hooks' just before any other mode hooks. `run-mode-hooks' just before any other mode hooks.
......
2012-02-02 Glenn Morris <rgm@gnu.org>
* subr.el (run-mode-hooks): Doc fix.
2012-02-02 Juri Linkov <juri@jurta.org> 2012-02-02 Juri Linkov <juri@jurta.org>
* image-mode.el (image-toggle-display-image): Remove tautological * image-mode.el (image-toggle-display-image): Remove tautological
......
...@@ -1539,10 +1539,12 @@ if it is empty or a duplicate." ...@@ -1539,10 +1539,12 @@ if it is empty or a duplicate."
(defun run-mode-hooks (&rest hooks) (defun run-mode-hooks (&rest hooks)
"Run mode hooks `delayed-mode-hooks' and HOOKS, or delay HOOKS. "Run mode hooks `delayed-mode-hooks' and HOOKS, or delay HOOKS.
Execution is delayed if the variable `delay-mode-hooks' is non-nil. If the variable `delay-mode-hooks' is non-nil, does not run any hooks,
Otherwise, runs the mode hooks and then `after-change-major-mode-hook'. just adds the HOOKS to the list `delayed-mode-hooks'.
Major mode functions should use this instead of `run-hooks' when running their Otherwise, runs hooks in the sequence: `change-major-mode-after-body-hook',
FOO-mode-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 (if delay-mode-hooks
;; Delaying case. ;; Delaying case.
(dolist (hook hooks) (dolist (hook hooks)
......
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment