Github/emacs
2
0
Fork 1
mirror of git://git.sv.gnu.org/emacs.git synced 2026-02-23 05:17:35 +00:00
Code Issues Projects Releases Packages Wiki Activity

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

Browse source 
new, and what that implies.  Clarify.
This commit is contained in:
Richard M. Stallman 2005-05-29 08:28:51 +00:00
parent a1a886a1d5
commit 801f0dc37d
1 changed files with 30 additions and 22 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

52
lispref/modes.texi
View file

@ -1117,7 +1117,7 @@ it runs the mode hook variable @code{@var{mode}-hook}.
@node 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
@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
@ -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
@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
has itself a parent. That is, the mode hooks of all major modes called
directly or indirectly by the major mode function are all run in
sequence at the end, just before @code{after-change-major-mode-hook}.
has itself a parent. That is, the mode hooks of all major modes
called directly or indirectly by the major mode function are all run
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
major mode. This also applies if you use @code{define-derived-mode}
to define a major mode, because that macro will automatically
implement the above for you.
These conventions are new in Emacs 22, and some major modes
implemented by users do not follow them yet. So if you put a function
onto @code{after-change-major-mode-hook}, keep in mind that some modes
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
fails to work. Please fix the major mode.'' In most cases, that is
good enough, so go ahead and use @code{after-change-major-mode-hook}.
However, if a certain feature needs to be completely reliable,
it should not use @code{after-change-major-mode-hook} as of yet.
Programmers wishing to define a major mode without using
@code{define-derived-mode}, should make sure that their major mode
follows the above conventions. @xref{Major Mode Conventions}, for how
this should be accomplished. Below, we give some implementation
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
Major modes should run their mode hook using this function. It is
similar to @code{run-hooks} (@pxref{Hooks}), but if run inside a
@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
similar to @code{run-hooks} (@pxref{Hooks}), but it also runs
@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
@defmac delay-mode-hooks body...
This macro executes @var{body} like @code{progn}, but all calls to
@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
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
@defvar after-change-major-mode-hook
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
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
@code{after-change-major-mode-hook} at its very end.
as the very last thing it does, and the last thing
@code{run-mode-hooks} does is run @code{after-change-major-mode-hook}.
@end defvar
@node Minor Modes