4 files changed, 17 insertions, 8 deletions

diff --git a/doc/misc/mh-e.texi b/doc/misc/mh-e.texi
index 0630b60ca6f..962f22af5d2 100644
--- a/doc/misc/mh-e.texi
+++ b/doc/misc/mh-e.texi
@@ -2256,10 +2256,10 @@ signature block is more to your liking.
 Two hooks can be used to control how messages are displayed. The first
 hook, @code{mh-show-mode-hook}, is called early on in the process of
 the message display. It is usually used to perform some action on the
-message's content. The second hook, @code{mh-show-hook}, is the last
+message's buffer. The second hook, @code{mh-show-hook}, is the last
 thing called after messages are displayed. It's used to affect the
-behavior of MH-E in general or when @code{mh-show-mode-hook} is too
-early.
+message's content, the behavior of MH-E in general, or when
+@code{mh-show-mode-hook} is too early.
 
 @cindex MH-Show mode
 @cindex modes, MH-Show
diff --git a/etc/NEWS b/etc/NEWS
index 433f1f76b80..54a71c9e494 100644
--- a/etc/NEWS
+++ b/etc/NEWS
@@ -2630,6 +2630,14 @@ will be chosen even if you have an entry for "image/*" in your
 overrides all system and Emacs-provided defaults.  To get the old
 method back, set 'mailcap-prefer-mailcap-viewers' to nil.
 
+** MH-E
++++
+*** The hook 'mh-show-mode-hook' is now called before the message is inserted.
+Functions that want to affect the message text (for example, to change
+highlighting) can no longer use 'mh-show-mode-hook', because the
+message contents will not yet have been inserted when the hook is
+called.  Such functions should now be attached to 'mh-show-hook'.
+
 ** URL
 
 ---
diff --git a/lisp/mh-e/mh-e.el b/lisp/mh-e/mh-e.el
index 5c85b3907e6..dd05d691c91 100644
--- a/lisp/mh-e/mh-e.el
+++ b/lisp/mh-e/mh-e.el
@@ -3380,13 +3380,14 @@ used to affect the behavior of MH-E in general or when
 (defcustom-mh mh-show-mode-hook nil
   "Hook run upon entry to `mh-show-mode'.
 
-This hook is called early on in the process of the message
-display. It is usually used to perform some action on the
-message's content. See `mh-show-hook'."
+This hook is called early on in the process of the message display,
+before the message contents have been inserted into the buffer.
+It is usually used to perform some action on the
+buffer itself. See also `mh-show-hook'."
   :type 'hook
   :group 'mh-hooks
   :group 'mh-show
-  :package-version '(MH-E . "6.0"))
+  :package-version '(MH-E . "8.7"))
 
 (defcustom-mh mh-unseen-updated-hook nil
   "Hook run after the unseen sequence has been updated.
diff --git a/lisp/mh-e/mh-show.el b/lisp/mh-e/mh-show.el
index 952579fd3dd..00f0908f99a 100644
--- a/lisp/mh-e/mh-show.el
+++ b/lisp/mh-e/mh-show.el
@@ -63,7 +63,7 @@ you wish to see all of them, use the command \\[mh-header-display].
 Two hooks can be used to control how messages are displayed. The
 first hook, `mh-show-mode-hook', is called early on in the
 process of the message display. It is usually used to perform
-some action on the message's content. The second hook,
+some action on the message's buffer. The second hook,
 `mh-show-hook', is the last thing called after messages are
 displayed. It's used to affect the behavior of MH-E in general or
 when `mh-show-mode-hook' is too early.