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>
* modes.texi (Defining Minor Modes):
......
......@@ -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}.
......
......@@ -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.
......
......@@ -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.
......
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
......
......@@ -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)
......
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