(Mode Hooks): Explain that after-change-major-mode-hook is

new, and what that implies.  Clarify.

1 files changed, 32 insertions, 24 deletions

diff --git a/lispref/modes.texi b/lispref/modes.texi
index 61bc878b581..488265b0b68 100644
--- a/lispref/modes.texi
+++ b/lispref/modes.texi
@@ -1117,7 +1117,7 @@ it runs the mode hook variable @code{@var{mode}-hook}.
 @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 @@ 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.
+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
-@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
+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}.
+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