# HG changeset patch # User Luc Teirlinck # Date 1096078856 0 # Node ID 3497eca006fe5d0e5ed95fd544267d61922d6b54 # Parent fddea2c6200384e6533454d799c3a571ccd993ce Various minor changes in addition to: (Major Mode Conventions): Final call to `run-mode-hooks' should not be inside the `delay-mode-hooks' form. (Mode Hooks): New node. (Hooks): Delete obsolete example. Move definitions of `run-mode-hooks' and `delay-mode-hooks' to new node "Mode Hooks". diff -r fddea2c62003 -r 3497eca006fe lispref/modes.texi --- a/lispref/modes.texi Sat Sep 25 02:08:41 2004 +0000 +++ b/lispref/modes.texi Sat Sep 25 02:20:56 2004 +0000 @@ -1,6 +1,6 @@ @c -*-texinfo-*- @c This is part of the GNU Emacs Lisp Reference Manual. -@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 1999, 2003 +@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 1999, 2003, 2004 @c Free Software Foundation, Inc. @c See the file elisp.texi for copying conditions. @setfilename ../info/modes @@ -103,6 +103,7 @@ * Mode Help:: Finding out how to use a mode. * Derived Modes:: Defining a new major mode based on another major mode. +* Mode Hooks:: Hooks run at the end of major mode functions. @end menu @node Major Mode Conventions @@ -276,7 +277,7 @@ Each major mode should have a @dfn{mode hook} named @code{@var{modename}-mode-hook}. The major mode command should run that hook, with @code{run-mode-hooks}, as the very last thing it -does. @xref{Hooks}. +does. @xref{Mode Hooks}. @item The major mode command may start by calling some other major mode @@ -284,9 +285,11 @@ settings. A mode that does this is called a @dfn{derived mode}. The recommended way to define one is to use @code{define-derived-mode}, but this is not required. Such a mode should use -@code{delay-mode-hooks} around its entire body, including the call to -the parent mode command and the final call to @code{run-mode-hooks}. -(Using @code{define-derived-mode} does this automatically.) +@code{delay-mode-hooks} around its entire body (including the call to +the parent mode command) @emph{except} for the final call to +@code{run-mode-hooks}, which runs the derived mode's hook. (Using +@code{define-derived-mode} does this automatically.) @xref{Derived +Modes}, and @ref{Mode Hooks}. @item If something special should be done if the user switches a buffer from @@ -575,7 +578,7 @@ in particular. Other major modes are defined in effect by comparison with this one---their definitions say what to change, starting from Fundamental mode. The @code{fundamental-mode} function does @emph{not} -run any hooks; you're not supposed to customize it. (If you want Emacs +run any mode hooks; you're not supposed to customize it. (If you want Emacs to behave differently in Fundamental mode, change the @emph{global} state of Emacs.) @end deffn @@ -808,6 +811,58 @@ @code{define-derived-mode} does that automatically. @end defmac +@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 +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}. + +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 @section Minor Modes @cindex minor mode @@ -2087,7 +2142,7 @@ Obviously, fontification of the subexpression numbered @var{subexp} will not occur. However, fontification of other subexpressions (and other regexps) will continue. If @var{laxmatch} is @code{nil}, and the -specified subexpression is missing, then an error is signalled which +specified subexpression is missing, then an error is signaled which terminates search-based fontification. Here are some examples of elements of this kind, and what they do: @@ -2450,7 +2505,7 @@ For buffers not visiting a file to have their state saved, the major mode must bind the buffer local variable @code{desktop-save-buffer} to -a non-nil value. +a non-@code{nil} value. @defvar desktop-save-buffer If this buffer-local variable is non-@code{nil}, the buffer will have @@ -2563,26 +2618,8 @@ a symbol with a function definition), it is called. If it is a list that isn't a function, its elements are called, consecutively. All the hook functions are called with no arguments. - -For example, here's how @code{emacs-lisp-mode} runs its mode hook: - -@example -(run-hooks 'emacs-lisp-mode-hook) -@end example @end defun -@defun run-mode-hooks &rest hookvars -Like @code{run-hooks}, but is affected by the @code{delay-mode-hooks} -macro. -@end defun - -@defmac delay-mode-hooks body... -This macro executes the @var{body} forms but defers all calls to -@code{run-mode-hooks} within them until the end of @var{body}. -This macro enables a derived mode to arrange not to run -its parent modes' mode hooks until the end. -@end defmac - @defun run-hook-with-args hook &rest args This function is the way to run an abnormal hook and always call all of the hook functions. It calls each of the hook functions one by