From 2591eb1190a24074357a2f178bc02ddc86c94b43 Mon Sep 17 00:00:00 2001 From: Eli Zaretskii Date: Tue, 20 Jun 2023 15:31:57 +0300 Subject: [PATCH] Improve documentation of 'minibuffer-message' * doc/lispref/minibuf.texi (Minibuffer Misc): Clarify that 'minibuffer-message' behaves like 'message' if called from a buffer that is not a minibuffer. * lisp/minibuffer.el (minibuffer-message) (set-minibuffer-message, clear-minibuffer-message): Doc fixes. (Bug#64165) --- doc/lispref/minibuf.texi | 24 +++++++++++++++++------- lisp/minibuffer.el | 24 +++++++++++++++++------- 2 files changed, 34 insertions(+), 14 deletions(-) diff --git a/doc/lispref/minibuf.texi b/doc/lispref/minibuf.texi index 9a386ff310d..52eea3b9535 100644 --- a/doc/lispref/minibuf.texi +++ b/doc/lispref/minibuf.texi @@ -2805,13 +2805,23 @@ minibuffer window, it returns @code{nil}. @vindex minibuffer-message-timeout @defun minibuffer-message string &rest args -This function displays @var{string} temporarily at the end of the -minibuffer text, for a few seconds, or until the next input event -arrives, whichever comes first. The variable -@code{minibuffer-message-timeout} specifies the number of seconds to -wait in the absence of input. It defaults to 2. If @var{args} is -non-@code{nil}, the actual message is obtained by passing @var{string} -and @var{args} through @code{format-message}. @xref{Formatting Strings}. +This function is like @code{message} (@pxref{Displaying Messages}), +but it displays the messages specially when the user types in the +minibuffer, typically because Emacs prompted the user for some input. +When the minibuffer is the current buffer, this function displays the +message specified by @var{string} temporarily at the end of the +minibuffer text, and thus avoids hiding the minibuffer text by the +echo-area display of the message. It leaves the message on display +for a few seconds, or until the next input event arrives, whichever +comes first. The variable @code{minibuffer-message-timeout} specifies +the number of seconds to wait in the absence of input. It defaults to +2. If @var{args} is non-@code{nil}, the actual message is obtained by +passing @var{string} and @var{args} through @code{format-message}. +@xref{Formatting Strings}. + +If called when the minibuffer is not the current buffer, this function +just calls @code{message}, and thus @var{string} will be shown in the +echo-area. @end defun @deffn Command minibuffer-inactive-mode diff --git a/lisp/minibuffer.el b/lisp/minibuffer.el index 41eb95fd20f..4aa1ab3e890 100644 --- a/lisp/minibuffer.el +++ b/lisp/minibuffer.el @@ -715,11 +715,21 @@ for use at QPOS." "Text properties added to the text shown by `minibuffer-message'.") (defun minibuffer-message (message &rest args) - "Temporarily display MESSAGE at the end of the minibuffer. -The text is displayed for `minibuffer-message-timeout' seconds, -or until the next input event arrives, whichever comes first. -Enclose MESSAGE in [...] if this is not yet the case. -If ARGS are provided, then pass MESSAGE through `format-message'." + "Temporarily display MESSAGE at the end of minibuffer text. +This function is designed to be called from the minibuffer, i.e., +when Emacs prompts the user for some input, and the user types +into the minibuffer. If called when the current buffer is not +the minibuffer, this function just calls `message', and thus +displays MESSAGE in the echo-area. +When called from the minibuffer, this function displays MESSAGE +at the end of minibuffer text for `minibuffer-message-timeout' +seconds, or until the next input event arrives, whichever comes first. +It encloses MESSAGE in [...] if it is not yet enclosed. +The intent is to show the message without hiding what the user typed. +If ARGS are provided, then the function first passes MESSAGE +through `format-message'. +If some of the minibuffer text has the `minibuffer-message' text +property, MESSAGE is shown at that position instead of EOB." (if (not (minibufferp (current-buffer) t)) (progn (if args @@ -796,7 +806,7 @@ The minibuffer message functions include `minibuffer-message' and (next-single-property-change pt 'minibuffer-message nil (point-max))))) (defun set-minibuffer-message (message) - "Temporarily display MESSAGE at the end of the minibuffer. + "Temporarily display MESSAGE at the end of the active minibuffer window. If some part of the minibuffer text has the `minibuffer-message' property, the message will be displayed before the first such character, instead of at the end of the minibuffer. @@ -954,7 +964,7 @@ is at its default value `grow-only'." multi-message-separator))) (defun clear-minibuffer-message () - "Clear minibuffer message. + "Clear message temporarily shown in the minibuffer. Intended to be called via `clear-message-function'." (when (not noninteractive) (when (timerp minibuffer-message-timer) -- 2.39.2