Commit 801f0dc3 authored by Richard M. Stallman's avatar Richard M. Stallman
Browse files

(Mode Hooks): Explain that after-change-major-mode-hook is

new, and what that implies.  Clarify.
parent a1a886a1
...@@ -1117,7 +1117,7 @@ it runs the mode hook variable @code{@var{mode}-hook}. ...@@ -1117,7 +1117,7 @@ it runs the mode hook variable @code{@var{mode}-hook}.
@node Mode Hooks @node Mode Hooks
@subsection Mode Hooks @subsection Mode Hooks
The two last things a major mode function does is to run its mode The two last things a major mode function should do is run its mode
hook and finally the mode independent normal hook hook and finally the mode independent normal hook
@code{after-change-major-mode-hook}. If the major mode is a derived @code{after-change-major-mode-hook}. If the major mode is a derived
mode, that is if it calls another major mode (the parent mode) in its mode, that is if it calls another major mode (the parent mode) in its
...@@ -1125,45 +1125,53 @@ body, then the parent's mode hook is run just before the derived ...@@ -1125,45 +1125,53 @@ body, then the parent's mode hook is run just before the derived
mode's hook. Neither the parent's mode hook nor mode's hook. Neither the parent's mode hook nor
@code{after-change-major-mode-hook} are run at the end of the actual @code{after-change-major-mode-hook} are run at the end of the actual
call to the parent mode. This applies recursively if the parent mode call to the parent mode. This applies recursively if the parent mode
has itself a parent. That is, the mode hooks of all major modes called has itself a parent. That is, the mode hooks of all major modes
directly or indirectly by the major mode function are all run in called directly or indirectly by the major mode function are all run
sequence at the end, just before @code{after-change-major-mode-hook}. in sequence at the end, just before
@code{after-change-major-mode-hook}.
If you are customizing a major mode, rather than defining one, the
above is all you need to know about the hooks run at the end of a These conventions are new in Emacs 22, and some major modes
major mode. This also applies if you use @code{define-derived-mode} implemented by users do not follow them yet. So if you put a function
to define a major mode, because that macro will automatically onto @code{after-change-major-mode-hook}, keep in mind that some modes
implement the above for you. will fail to run it. If user complains about that, you can respond,
``That major mode fails to follow Emacs conventions, and that's why it
Programmers wishing to define a major mode without using fails to work. Please fix the major mode.'' In most cases, that is
@code{define-derived-mode}, should make sure that their major mode good enough, so go ahead and use @code{after-change-major-mode-hook}.
follows the above conventions. @xref{Major Mode Conventions}, for how However, if a certain feature needs to be completely reliable,
this should be accomplished. Below, we give some implementation it should not use @code{after-change-major-mode-hook} as of yet.
details.
When you defined a major mode using @code{define-derived-mode}, it
automatically makes sure these conventions are followed. If you
define a major mode ``from scratch'', not using
@code{define-derived-mode}, make sure the major mode command follows
these and other conventions. @xref{Major Mode Conventions}. You use
these functions to do it properly.
@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 if run inside a similar to @code{run-hooks} (@pxref{Hooks}), but it also runs
@code{delay-mode-hooks} form, this function does not run any hooks.
Instead, it arranges for @var{hookvars} to be run at a later call to
the function. Otherwise, @code{run-mode-hooks} runs any delayed hooks
in order, then @var{hookvars} and finally
@code{after-change-major-mode-hook}. @code{after-change-major-mode-hook}.
When the call to this function is dynamically inside a
@code{delay-mode-hooks} form, this function does not run any hooks.
Instead, it arranges for the next call to @code{run-mode-hooks} to run
@var{hookvars}.
@end defun @end defun
@defmac delay-mode-hooks body... @defmac delay-mode-hooks body...
This macro executes @var{body} like @code{progn}, but all calls to This macro executes @var{body} like @code{progn}, but all calls to
@code{run-mode-hooks} inside @var{body} delay running their hooks. @code{run-mode-hooks} inside @var{body} delay running their hooks.
They will be run by the first call to @code{run-mode-hooks} after exit They will be run by the first call to @code{run-mode-hooks} after exit
from @code{delay-mode-hooks}. from @code{delay-mode-hooks}. This is the proper way for a major mode
command to invoke its parent mode.
@end defmac @end defmac
@defvar after-change-major-mode-hook @defvar after-change-major-mode-hook
Every major mode function should run this normal hook at its very end. Every major mode function should run this normal hook at its very end.
It normally does not need to do so explicitly. Indeed, a major mode It normally does not need to do so explicitly. Indeed, a major mode
function should normally run its mode hook with @code{run-mode-hooks} function should normally run its mode hook with @code{run-mode-hooks}
as the very last thing it does and @code{run-mode-hooks} runs as the very last thing it does, and the last thing
@code{after-change-major-mode-hook} at its very end. @code{run-mode-hooks} does is run @code{after-change-major-mode-hook}.
@end defvar @end defvar
@node Minor Modes @node Minor Modes
......
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