# HG changeset patch # User Richard M. Stallman # Date 1117355331 0 # Node ID 9f2d0e4a66d0cff955b9d0fb206dc0c6509c2309 # Parent 19deaa395e8540567b3c1efc0cb8ec26b3c19631 (Mode Hooks): Explain that after-change-major-mode-hook is new, and what that implies. Clarify. diff -r 19deaa395e85 -r 9f2d0e4a66d0 lispref/modes.texi --- a/lispref/modes.texi Sun May 29 08:27:37 2005 +0000 +++ b/lispref/modes.texi Sun May 29 08:28:51 2005 +0000 @@ -1117,7 +1117,7 @@ @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 @@ 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}. - -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. - -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. +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}. + + 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. + + 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 +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 @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}. +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