[Top][All Lists]
[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[Emacs-diffs] Changes to emacs/lispref/modes.texi
From: |
Luc Teirlinck |
Subject: |
[Emacs-diffs] Changes to emacs/lispref/modes.texi |
Date: |
Fri, 24 Sep 2004 22:31:57 -0400 |
Index: emacs/lispref/modes.texi
diff -c emacs/lispref/modes.texi:1.79 emacs/lispref/modes.texi:1.80
*** emacs/lispref/modes.texi:1.79 Sun Aug 22 17:41:15 2004
--- emacs/lispref/modes.texi Sat Sep 25 02:20:56 2004
***************
*** 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 Free Software Foundation, Inc.
@c See the file elisp.texi for copying conditions.
@setfilename ../info/modes
--- 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, 2004
@c Free Software Foundation, Inc.
@c See the file elisp.texi for copying conditions.
@setfilename ../info/modes
***************
*** 103,108 ****
--- 103,109 ----
* 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,282 ****
Each major mode should have a @dfn{mode hook} named
@address@hidden The major mode command should run that
hook, with @code{run-mode-hooks}, as the very last thing it
! does. @xref{Hooks}.
@item
The major mode command may start by calling some other major mode
--- 277,283 ----
Each major mode should have a @dfn{mode hook} named
@address@hidden The major mode command should run that
hook, with @code{run-mode-hooks}, as the very last thing it
! does. @xref{Mode Hooks}.
@item
The major mode command may start by calling some other major mode
***************
*** 284,292 ****
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.)
@item
If something special should be done if the user switches a buffer from
--- 285,295 ----
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) @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,581 ****
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
to behave differently in Fundamental mode, change the @emph{global}
state of Emacs.)
@end deffn
--- 578,584 ----
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 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,813 ****
--- 811,868 ----
@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,2093 ****
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
terminates search-based fontification.
Here are some examples of elements of this kind, and what they do:
--- 2142,2148 ----
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 signaled which
terminates search-based fontification.
Here are some examples of elements of this kind, and what they do:
***************
*** 2450,2456 ****
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.
@defvar desktop-save-buffer
If this buffer-local variable is address@hidden, the buffer will have
--- 2505,2511 ----
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 address@hidden value.
@defvar desktop-save-buffer
If this buffer-local variable is address@hidden, the buffer will have
***************
*** 2563,2588 ****
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
--- 2618,2625 ----
[Prev in Thread] |
Current Thread |
[Next in Thread] |
- [Emacs-diffs] Changes to emacs/lispref/modes.texi,
Luc Teirlinck <=