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".

2 files changed, 73 insertions, 26 deletions

diff --git a/lispref/ChangeLog b/lispref/ChangeLog
index 2dd35cd1844..a7681ddfbf0 100644
--- a/lispref/ChangeLog
+++ b/lispref/ChangeLog
@@ -1,3 +1,13 @@
+2004-09-24  Luc Teirlinck  <teirllm@auburn.edu>
+
+        * modes.texi: 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".
+
 2004-09-22  Luc Teirlinck  <teirllm@auburn.edu>
 
         * display.texi: Correct various typos.
diff --git a/lispref/modes.texi b/lispref/modes.texi
index 78b8fc440d7..f74f7c89da7 100644
--- a/lispref/modes.texi
+++ b/lispref/modes.texi
@@ -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 @@ Fundamental mode.  Rmail mode is a complicated and specialized mode.
 * 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 @@ other packages would interfere with them.
 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 @@ command (called the @dfn{parent mode}) and then alter some of its
 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 @@ visited.  It also processes local variables specified in the file text.
 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 @@ Do not write an @code{interactive} spec in the definition;
 @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 @@ if there is no subexpression numbered @var{subexp} in @var{matcher}.
 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 @@ a file, don't have to do anything to use this feature.
 
 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 @@ obsolete.)  If the value is a function (either a lambda expression or
 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