Add :after-hook facility to define-derived-mode.

This allow a form to be evaluated _after_ a major mode's hooks have been run.
It is needed to solve some problems in CC Mode, including bug #16759 and
bug #23476.

* lisp/emacs-lisp/derived.el (define-derived-mode): introduce the new argument
`:after-hook', and generate the requisite code for it.
(derived-mode-make-docstring): Take account of the possibility of :after-hook.

* lisp/subr.el (delayed-after-hook-forms): New variable.
(run-mode-hooks): As the last thing evaluate the forms in
delayed-after-hook-forms.

* doc/lispref/modes.texi (Derived Modes): Document :after-hook.
(Mode Hooks): Document the new feature in run-mode-hooks.

* etc/NEWS: Note the new feature.

2 files changed, 27 insertions, 7 deletions

diff --git a/lisp/emacs-lisp/derived.el b/lisp/emacs-lisp/derived.el
index a615f9a5854..0f7691af0f4 100644
--- a/lisp/emacs-lisp/derived.el
+++ b/lisp/emacs-lisp/derived.el
@@ -137,6 +137,9 @@ BODY can start with a bunch of keyword arguments.  The following keyword
 :abbrev-table TABLE
         Use TABLE instead of the default (CHILD-abbrev-table).
         A nil value means to simply use the same abbrev-table as the parent.
+:after-hook FORM
+        A single lisp form which is evaluated after the mode hooks have been
+        run.  It should not be quoted.
 
 Here is how you could define LaTeX-Thesis mode as a variant of LaTeX mode:
 
@@ -184,7 +187,8 @@ See Info node `(elisp)Derived Modes' for more details."
         (declare-abbrev t)
         (declare-syntax t)
         (hook (derived-mode-hook-name child))
-        (group nil))
+        (group nil)
+        (after-hook nil))
 
     ;; Process the keyword args.
     (while (keywordp (car body))
@@ -192,6 +196,7 @@ See Info node `(elisp)Derived Modes' for more details."
         (`:group (setq group (pop body)))
         (`:abbrev-table (setq abbrev (pop body)) (setq declare-abbrev nil))
         (`:syntax-table (setq syntax (pop body)) (setq declare-syntax nil))
+        (`:after-hook (setq after-hook (pop body)))
         (_ (pop body))))
 
     (setq docstring (derived-mode-make-docstring
@@ -272,7 +277,11 @@ No problems result if this variable is not bound.
           ,@body
           )
          ;; Run the hooks, if any.
-         (run-mode-hooks ',hook)))))
+         (run-mode-hooks ',hook)
+         ,@(when after-hook
+             `((if delay-mode-hooks
+                   (push ',after-hook delayed-after-hook-forms)
+                 ,after-hook)))))))
 
 ;; PUBLIC: find the ultimate class of a derived mode.
 
@@ -344,7 +353,7 @@ which more-or-less shadow%s %s's corresponding table%s."
                          (format "`%s' " parent))
                        "might have run,\nthis mode "))
                     (format "runs the hook `%s'" hook)
-                    ", as the final step\nduring initialization.")))
+                    ", as the final or penultimate step\nduring initialization.")))
 
     (unless (string-match "\\\\[{[]" docstring)
       ;; And don't forget to put the mode's keymap.
diff --git a/lisp/subr.el b/lisp/subr.el
index 094710b026c..0fa6404d37d 100644
--- a/lisp/subr.el
+++ b/lisp/subr.el
@@ -1736,6 +1736,11 @@ if it is empty or a duplicate."
 (make-variable-buffer-local 'delayed-mode-hooks)
 (put 'delay-mode-hooks 'permanent-local t)
 
+(defvar delayed-after-hook-forms nil
+  "List of delayed :after-hook forms waiting to be run.
+These forms come from `define-derived-mode'.")
+(make-variable-buffer-local 'delayed-after-hook-forms)
+
 (defvar change-major-mode-after-body-hook nil
   "Normal hook run in major mode functions, before the mode hooks.")
 
@@ -1751,9 +1756,12 @@ If the variable `delay-mode-hooks' is non-nil, does not do anything,
 just adds the HOOKS to the list `delayed-mode-hooks'.
 Otherwise, runs hooks in the sequence: `change-major-mode-after-body-hook',
 `delayed-mode-hooks' (in reverse order), HOOKS, then runs
-`hack-local-variables' and finally runs the hook
-`after-change-major-mode-hook'.  Major mode functions should use
-this instead of `run-hooks' when running their FOO-mode-hook."
+`hack-local-variables', runs the hook `after-change-major-mode-hook', and
+finally evaluates the forms in `delayed-after-hook-forms' (see
+`define-derived-mode').
+
+Major mode functions should use this instead of `run-hooks' when
+running their FOO-mode-hook."
   (if delay-mode-hooks
       ;; Delaying case.
       (dolist (hook hooks)
@@ -1765,7 +1773,10 @@ this instead of `run-hooks' when running their FOO-mode-hook."
     (if (buffer-file-name)
         (with-demoted-errors "File local-variables error: %s"
           (hack-local-variables 'no-mode)))
-    (run-hooks 'after-change-major-mode-hook)))
+    (run-hooks 'after-change-major-mode-hook)
+    (dolist (form (nreverse delayed-after-hook-forms))
+      (eval form))
+    (setq delayed-after-hook-forms nil)))
 
 (defmacro delay-mode-hooks (&rest body)
   "Execute BODY, but delay any `run-mode-hooks'.