new repository

1 files changed, 46 insertions, 0 deletions

diff --git a/devdocs/elisp/displaying-messages.html b/devdocs/elisp/displaying-messages.html
new file mode 100644
index 00000000..d56ba3ed
--- /dev/null
+++ b/devdocs/elisp/displaying-messages.html
@@ -0,0 +1,46 @@
+ <h4 class="subsection">Displaying Messages in the Echo Area</h4>  <p>This section describes the standard functions for displaying messages in the echo area. </p> <dl> <dt id="message">Function: <strong>message</strong> <em>format-string &amp;rest arguments</em>
+</dt> <dd>
+<p>This function displays a message in the echo area. <var>format-string</var> is a format string, and <var>arguments</var> are the objects for its format specifications, like in the <code>format-message</code> function (see <a href="formatting-strings">Formatting Strings</a>). The resulting formatted string is displayed in the echo area; if it contains <code>face</code> text properties, it is displayed with the specified faces (see <a href="faces">Faces</a>). The string is also added to the <samp>*Messages*</samp> buffer, but without text properties (see <a href="logging-messages">Logging Messages</a>). </p> <p>Typically grave accent and apostrophe in the format translate to matching curved quotes, e.g., <tt>"Missing `%s'"</tt> might result in <tt>"Missing ‘foo’"</tt>. See <a href="text-quoting-style">Text Quoting Style</a>, for how to influence or inhibit this translation. </p> <p>In batch mode, the message is printed to the standard error stream, followed by a newline. </p> <p>When <code>inhibit-message</code> is non-<code>nil</code>, no message will be displayed in the echo area, it will only be logged to ‘<samp>*Messages*</samp>’. </p> <p>If <var>format-string</var> is <code>nil</code> or the empty string, <code>message</code> clears the echo area; if the echo area has been expanded automatically, this brings it back to its normal size. If the minibuffer is active, this brings the minibuffer contents back onto the screen immediately. </p> <div class="example"> <pre class="example">(message "Reverting `%s'..." (buffer-name))
+ -| Reverting ‘subr.el’...
+⇒ "Reverting ‘subr.el’..."
+</pre>
+
+<pre class="example">---------- Echo Area ----------
+Reverting ‘subr.el’...
+---------- Echo Area ----------
+</pre>
+</div> <p>To automatically display a message in the echo area or in a pop-buffer, depending on its size, use <code>display-message-or-buffer</code> (see below). </p> <p><strong>Warning:</strong> If you want to use your own string as a message verbatim, don’t just write <code>(message <var>string</var>)</code>. If <var>string</var> contains ‘<samp>%</samp>’, ‘<samp>`</samp>’, or ‘<samp>'</samp>’ it may be reformatted, with undesirable results. Instead, use <code>(message
+"%s" <var>string</var>)</code>. </p>
+</dd>
+</dl> <dl> <dt id="set-message-function">Variable: <strong>set-message-function</strong>
+</dt> <dd>
+<p>If this variable is non-<code>nil</code>, 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</code> and related functions. If the function returns <code>nil</code>, 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</code> values, that means the message was already handled, so <code>message</code> will not display anything in the echo area. See also <code>clear-message-function</code> that can be used to clear the message displayed by this function. </p> <p>The default value is the function that displays the message at the end of the minibuffer when the minibuffer is active. However, if the text shown in the active minibuffer has the <code>minibuffer-message</code> text property (see <a href="special-properties">Special Properties</a>) on some character, the message will be displayed before the first character having that property. </p>
+</dd>
+</dl> <dl> <dt id="clear-message-function">Variable: <strong>clear-message-function</strong>
+</dt> <dd>
+<p>If this variable is non-<code>nil</code>, <code>message</code> and related functions call it with no arguments when their argument message is <code>nil</code> or the empty string. </p> <p>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</code>. </p> <p>The default value is the function that clears the message displayed in an active minibuffer. </p>
+</dd>
+</dl> <dl> <dt id="inhibit-message">Variable: <strong>inhibit-message</strong>
+</dt> <dd><p>When this variable is non-<code>nil</code>, <code>message</code> and related functions will not use the Echo Area to display messages. </p></dd>
+</dl> <dl> <dt id="with-temp-message">Macro: <strong>with-temp-message</strong> <em>message &amp;rest body</em>
+</dt> <dd><p>This construct displays a message in the echo area temporarily, during the execution of <var>body</var>. It displays <var>message</var>, executes <var>body</var>, then returns the value of the last body form while restoring the previous echo area contents. </p></dd>
+</dl> <dl> <dt id="message-or-box">Function: <strong>message-or-box</strong> <em>format-string &amp;rest arguments</em>
+</dt> <dd>
+<p>This function displays a message like <code>message</code>, but may display it in a dialog box instead of the echo area. If this function is called in a command that was invoked using the mouse—more precisely, if <code>last-nonmenu-event</code> (see <a href="command-loop-info">Command Loop Info</a>) is either <code>nil</code> or a list—then it uses a dialog box or pop-up menu to display the message. Otherwise, it uses the echo area. (This is the same criterion that <code>y-or-n-p</code> uses to make a similar decision; see <a href="yes_002dor_002dno-queries">Yes-or-No Queries</a>.) </p> <p>You can force use of the mouse or of the echo area by binding <code>last-nonmenu-event</code> to a suitable value around the call. </p>
+</dd>
+</dl> <dl> <dt id="message-box">Function: <strong>message-box</strong> <em>format-string &amp;rest arguments</em>
+</dt> <dd>
+<p>This function displays a message like <code>message</code>, but uses a dialog box (or a pop-up menu) whenever that is possible. If it is impossible to use a dialog box or pop-up menu, because the terminal does not support them, then <code>message-box</code> uses the echo area, like <code>message</code>. </p>
+</dd>
+</dl> <dl> <dt id="display-message-or-buffer">Function: <strong>display-message-or-buffer</strong> <em>message &amp;optional buffer-name action frame</em>
+</dt> <dd>
+<p>This function displays the message <var>message</var>, which may be either a string or a buffer. If it is shorter than the maximum height of the echo area, as defined by <code>max-mini-window-height</code>, it is displayed in the echo area, using <code>message</code>. Otherwise, <code>display-buffer</code> is used to show it in a pop-up buffer. </p> <p>Returns either the string shown in the echo area, or when a pop-up buffer is used, the window used to display it. </p> <p>If <var>message</var> is a string, then the optional argument <var>buffer-name</var> is the name of the buffer used to display it when a pop-up buffer is used, defaulting to <samp>*Message*</samp>. In the case where <var>message</var> is a string and displayed in the echo area, it is not specified whether the contents are inserted into the buffer anyway. </p> <p>The optional arguments <var>action</var> and <var>frame</var> are as for <code>display-buffer</code>, and only used if a buffer is displayed. </p>
+</dd>
+</dl> <dl> <dt id="current-message">Function: <strong>current-message</strong>
+</dt> <dd><p>This function returns the message currently being displayed in the echo area, or <code>nil</code> if there is none. </p></dd>
+</dl><div class="_attribution">
+  <p class="_attribution-p">
+    Copyright &copy; 1990-1996, 1998-2022 Free Software Foundation, Inc. <br>Licensed under the GNU GPL license.<br>
+    <a href="https://www.gnu.org/software/emacs/manual/html_node/elisp/Displaying-Messages.html" class="_attribution-link">https://www.gnu.org/software/emacs/manual/html_node/elisp/Displaying-Messages.html</a>
+  </p>
+</div>