X-Git-Url: https://code.delx.au/gnu-emacs/blobdiff_plain/89ce83b20249dfb4e45f09dfdddf4c4b66d82968..85b3eca57a5ae5335c11b157bb481cf8f7a35684:/doc/lispref/modes.texi

diff --git a/doc/lispref/modes.texi b/doc/lispref/modes.texi
index 76e5174bd2..368d882a4b 100644
--- a/doc/lispref/modes.texi
+++ b/doc/lispref/modes.texi
@@ -752,7 +752,8 @@ The new mode has its own abbrev table, kept in the variable
 @item
 The new mode has its own mode hook, @code{@var{variant}-hook}.  It
 runs this hook, after running the hooks of its ancestor modes, with
-@code{run-mode-hooks}, as the last thing it does.  @xref{Mode Hooks}.
+@code{run-mode-hooks}, as the last thing it does, apart from running
+any @code{:after-hook} form it may have.  @xref{Mode Hooks}.
 @end itemize
 
 In addition, you can specify how to override other aspects of
@@ -776,8 +777,9 @@ about the mode's hook, followed by the mode's keymap, at the end of this
 documentation string.  If you omit @var{docstring},
 @code{define-derived-mode} generates a documentation string.
 
-The @var{keyword-args} are pairs of keywords and values.  The values
-are evaluated.  The following keywords are currently supported:
+The @var{keyword-args} are pairs of keywords and values.  The values,
+except for @code{:after-hook}'s, are evaluated.  The following
+keywords are currently supported:
 
 @table @code
 @item :syntax-table
@@ -797,10 +799,18 @@ if @var{parent} is @code{nil}.  (Again, a @code{nil} value is
 
 @item :group
 If this is specified, the value should be the customization group for
-this mode.  (Not all major modes have one.)  Only the (still
-experimental and unadvertised) command @code{customize-mode} currently
-uses this.  @code{define-derived-mode} does @emph{not} automatically
-define the specified customization group.
+this mode.  (Not all major modes have one.)  The command
+@code{customize-mode} uses this.  @code{define-derived-mode} does
+@emph{not} automatically define the specified customization group.
+
+@item :after-hook
+This optional keyword specifies a single Lisp form to evaluate as the
+final act of the mode function, after the mode hooks have been run.
+It should not be quoted.  Since the form might be evaluated after the
+mode function has terminated, it should not access any element of the
+mode function's local state.  An @code{:after-hook} form is useful for
+setting up aspects of the mode which depend on the user's settings,
+which in turn may have been changed in a mode hook.
 @end table
 
 Here is a hypothetical example:
@@ -902,7 +912,7 @@ follow these conventions: they may run the parent's mode hook too early,
 or fail to run @code{after-change-major-mode-hook}.  If you encounter
 such a major mode, please correct it to follow these conventions.
 
-  When you defined a major mode using @code{define-derived-mode}, it
+  When you define a major mode using @code{define-derived-mode}, it
 automatically makes sure these conventions are followed.  If you
 define a major mode ``by hand'', not using @code{define-derived-mode},
 use the following functions to handle these conventions automatically.
@@ -912,12 +922,15 @@ Major modes should run their mode hook using this function.  It is
 similar to @code{run-hooks} (@pxref{Hooks}), but it also runs
 @code{change-major-mode-after-body-hook}, @code{hack-local-variables}
 (when the buffer is visiting a file) (@pxref{File Local Variables}),
-and @code{after-change-major-mode-hook}.
+and @code{after-change-major-mode-hook}.  The last thing it does is to
+evaluate any @code{:after-hook} forms declared by parent modes
+(@pxref{Derived Modes}).
 
 When this function is called during the execution of a
 @code{delay-mode-hooks} form, it does not run the hooks or
-@code{hack-local-variables} immediately.  Instead, it arranges for the
-next call to @code{run-mode-hooks} to run them.
+@code{hack-local-variables} or evaluate the forms immediately.
+Instead, it arranges for the next call to @code{run-mode-hooks} to run
+them.
 @end defun
 
 @defmac delay-mode-hooks body@dots{}
@@ -1052,7 +1065,7 @@ to invert the sort order.
 @defun tabulated-list-init-header
 This function computes and sets @code{header-line-format} for the
 Tabulated List buffer (@pxref{Header Lines}), and assigns a keymap to
-the header line to allow sort entries by clicking on column headers.
+the header line to allow sorting entries by clicking on column headers.
 
 Modes derived from Tabulated List mode should call this after setting
 the above variables (in particular, only after setting