Index: emacs/lispref/modes.texi
diff -c emacs/lispref/modes.texi:1.109 emacs/lispref/modes.texi:1.110
*** emacs/lispref/modes.texi:1.109 Mon May 23 12:01:08 2005
--- emacs/lispref/modes.texi Sun May 29 08:28:51 2005
***************
*** 1117,1123 ****
@node Mode Hooks
@subsection Mode Hooks
! The two last things a major mode function does is to 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
--- 1117,1123 ----
@node Mode Hooks
@subsection Mode Hooks
! 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,1169 ****
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.
@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
@code{after-change-major-mode-hook}.
@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}.
@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.
@end defvar
@node Minor Modes
--- 1125,1177 ----
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}.
!
! 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 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}. 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 the last thing
! @code{run-mode-hooks} does is run @code{after-change-major-mode-hook}.
@end defvar
@node Minor Modes
_______________________________________________
Emacs-diffs mailing list
[email protected]
http://lists.gnu.org/mailman/listinfo/emacs-diffs
