4 files changed, 33 insertions, 28 deletions

diff --git a/doc/lispref/display.texi b/doc/lispref/display.texi
index 0085f3b6750..6952cb58130 100644
--- a/doc/lispref/display.texi
+++ b/doc/lispref/display.texi
@@ -307,28 +307,29 @@ reformatted, with undesirable results.  Instead, use @code{(message
 @end defun
 
 @defvar set-message-function
-When this variable is non-@code{nil}, @code{message} and related functions
-call it as a function with one argument that is the message to show.
-
-When this function returns @code{nil}, the message is displayed in the
-echo area as usual.  When the function returns a string, the returned
-string is displayed in the echo area.  When this function returns
-other non-@code{nil} values, this means that the message was handled
-specially, so the same message is not displayed in the echo area.
-See also @code{clear-message-function} that can be used to clear the
-message displayed by this function.
+If this variable is non-@code{nil}, it should be a function of one
+argument, the text of a message to display in the echo area.  This
+function will be called by @code{message} and related functions.  If
+the function returns @code{nil}, the message is displayed in the echo
+area as usual.  If this function returns a string, that string is
+displayed in the echo area instead of the original one.  If this
+function returns other non-@code{nil} values, that means the message
+was already handled, so @code{message} will not display anything in
+the echo area.  See also @code{clear-message-function} that can be
+used to clear the message displayed by this function.
 
 The default value is the function that displays the message at the end
 of the minibuffer when the minibuffer is active.
 @end defvar
 
 @defvar clear-message-function
-When this variable is non-@code{nil}, @code{message} and related functions
-call it without arguments when their message is @code{nil} or the empty string.
+If this variable is non-@code{nil}, @code{message} and related
+functions call it with no arguments when their argument message is
+@code{nil} or the empty string.
 
-Usually this function is called when the next input event arrives.
-The function is called without arguments.  It is expected to clear the
-message displayed by its counterpart function specified by
+Usually this function is called when the next input event arrives
+after displaying an echo-area message.  The function is expected to
+clear the message displayed by its counterpart function specified by
 @code{set-message-function}.
 
 The default value is the function that clears the message displayed at
diff --git a/etc/NEWS b/etc/NEWS
index cd835f3d2a9..20288398bd3 100644
--- a/etc/NEWS
+++ b/etc/NEWS
@@ -782,8 +782,11 @@ the minibuffer.  If non-nil, point will move to the end of the prompt
 (if point is after the end of the prompt).
 
 +++
-*** When the minibuffer is active, messages are displayed at the end of
-the minibuffer instead of overwriting the minibuffer by the echo area.
+*** When the minibuffer is active, echo-area messages are displayed at
+the end of the minibuffer instead of hiding the minibuffer by the echo
+area display.  The new option 'minibuffer-message-clear-timeout'
+controls how messages displayed in this situation are removed from the
+minibuffer.
 
 ---
 *** Minibuffer now uses 'minibuffer-message' to display error messages
diff --git a/lisp/minibuffer.el b/lisp/minibuffer.el
index 96931162cc1..c0df383e288 100644
--- a/lisp/minibuffer.el
+++ b/lisp/minibuffer.el
@@ -748,9 +748,10 @@ If ARGS are provided, then pass MESSAGE through `format-message'."
 
 (defcustom minibuffer-message-clear-timeout nil
   "How long to display an echo-area message when the minibuffer is active.
-If the value is a number, it should be specified in seconds.
-If the value is not a number, such messages never time out,
-and the text is displayed until the next input event arrives.
+If the value is a number, it is the time in seconds after which to
+remove the echo-area message from the active minibuffer.
+If the value is not a number, such messages are never removed,
+and their text is displayed until the next input event arrives.
 Unlike `minibuffer-message-timeout' used by `minibuffer-message',
 this option affects the pair of functions `set-minibuffer-message'
 and `clear-minibuffer-message' called automatically via
diff --git a/src/xdisp.c b/src/xdisp.c
index 8cba5c5028d..2dfc4cbfeb4 100644
--- a/src/xdisp.c
+++ b/src/xdisp.c
@@ -34968,19 +34968,19 @@ display table takes effect; in this case, Emacs does not consult
   Vdebug_on_message = Qnil;
 
   DEFVAR_LISP ("set-message-function", Vset_message_function,
-               doc: /* If non-nil, function to show the message.
-The function is called with one argument that is the message.
-When this function returns nil, the message is displayed in the echo
-area as usual.  When the function returns a string, the returned
-string is displayed in the echo area.  When this function returns
-other non-nil values, this means that the message was handled
-specially, so the same message is not displayed in the echo area.
+               doc: /* If non-nil, function to handle display of echo-area messages.
+The function is called with one argument that is the text of a message.
+If this function returns nil, the message is displayed in the echo area
+as usual.  If the function returns a string, the returned string is
+displayed in the echo area.  If this function returns any other non-nil
+value, this means that the message was already handled, and the original
+message text will not be displayed in the echo area.
 See also `clear-message-function' that can be used to clear the
 message displayed by this function.  */);
   Vset_message_function = Qnil;
 
   DEFVAR_LISP ("clear-message-function", Vclear_message_function,
-               doc: /* If non-nil, function to clear message.
+               doc: /* If non-nil, function to clear echo-area messages.
 Usually this function is called when the next input event arrives.
 The function is called without arguments.  It is expected to clear the
 message displayed by its counterpart function specified by