new repository

1 files changed, 74 insertions, 0 deletions

diff --git a/devdocs/elisp/temporary-displays.html b/devdocs/elisp/temporary-displays.html
new file mode 100644
index 00000000..414e69e1
--- /dev/null
+++ b/devdocs/elisp/temporary-displays.html
@@ -0,0 +1,74 @@
+ <h3 class="section">Temporary Displays</h3>   <p>Temporary displays are used by Lisp programs to put output into a buffer and then present it to the user for perusal rather than for editing. Many help commands use this feature. </p> <dl> <dt id="with-output-to-temp-buffer">Macro: <strong>with-output-to-temp-buffer</strong> <em>buffer-name body…</em>
+</dt> <dd>
+<p>This function executes the forms in <var>body</var> while arranging to insert any output they print into the buffer named <var>buffer-name</var>, which is first created if necessary, and put into Help mode. (See the similar form <code>with-temp-buffer-window</code> below.) Finally, the buffer is displayed in some window, but that window is not selected. </p> <p>If the forms in <var>body</var> do not change the major mode in the output buffer, so that it is still Help mode at the end of their execution, then <code>with-output-to-temp-buffer</code> makes this buffer read-only at the end, and also scans it for function and variable names to make them into clickable cross-references. See <a href="https://www.gnu.org/software/emacs/manual/html_node/elisp/Documentation-Tips.html#Docstring-hyperlinks">Tips for Documentation Strings</a>, in particular the item on hyperlinks in documentation strings, for more details. </p> <p>The string <var>buffer-name</var> specifies the temporary buffer, which need not already exist. The argument must be a string, not a buffer. The buffer is erased initially (with no questions asked), and it is marked as unmodified after <code>with-output-to-temp-buffer</code> exits. </p> <p><code>with-output-to-temp-buffer</code> binds <code>standard-output</code> to the temporary buffer, then it evaluates the forms in <var>body</var>. Output using the Lisp output functions within <var>body</var> goes by default to that buffer (but screen display and messages in the echo area, although they are “output” in the general sense of the word, are not affected). See <a href="output-functions">Output Functions</a>. </p> <p>Several hooks are available for customizing the behavior of this construct; they are listed below. </p> <p>The value of the last form in <var>body</var> is returned. </p> <div class="example"> <pre class="example">---------- Buffer: foo ----------
+ This is the contents of foo.
+---------- Buffer: foo ----------
+</pre>
+
+<pre class="example">(with-output-to-temp-buffer "foo"
+    (print 20)
+    (print standard-output))
+⇒ #&lt;buffer foo&gt;
+
+---------- Buffer: foo ----------
+
+20
+
+#&lt;buffer foo&gt;
+
+---------- Buffer: foo ----------
+</pre>
+</div> </dd>
+</dl> <dl> <dt id="temp-buffer-show-function">User Option: <strong>temp-buffer-show-function</strong>
+</dt> <dd>
+<p>If this variable is non-<code>nil</code>, <code>with-output-to-temp-buffer</code> calls it as a function to do the job of displaying a help buffer. The function gets one argument, which is the buffer it should display. </p> <p>It is a good idea for this function to run <code>temp-buffer-show-hook</code> just as <code>with-output-to-temp-buffer</code> normally would, inside of <code>save-selected-window</code> and with the chosen window and buffer selected. </p>
+</dd>
+</dl> <dl> <dt id="temp-buffer-setup-hook">Variable: <strong>temp-buffer-setup-hook</strong>
+</dt> <dd><p>This normal hook is run by <code>with-output-to-temp-buffer</code> before evaluating <var>body</var>. When the hook runs, the temporary buffer is current. This hook is normally set up with a function to put the buffer in Help mode. </p></dd>
+</dl> <dl> <dt id="temp-buffer-show-hook">Variable: <strong>temp-buffer-show-hook</strong>
+</dt> <dd><p>This normal hook is run by <code>with-output-to-temp-buffer</code> after displaying the temporary buffer. When the hook runs, the temporary buffer is current, and the window it was displayed in is selected. </p></dd>
+</dl> <dl> <dt id="with-temp-buffer-window">Macro: <strong>with-temp-buffer-window</strong> <em>buffer-or-name action quit-function body…</em>
+</dt> <dd>
+<p>This macro is similar to <code>with-output-to-temp-buffer</code>. Like that construct, it executes <var>body</var> while arranging to insert any output it prints into the buffer named <var>buffer-or-name</var> and displays that buffer in some window. Unlike <code>with-output-to-temp-buffer</code>, however, it does not automatically switch that buffer to Help mode. </p> <p>The argument <var>buffer-or-name</var> specifies the temporary buffer. It can be either a buffer, which must already exist, or a string, in which case a buffer of that name is created, if necessary. The buffer is marked as unmodified and read-only when <code>with-temp-buffer-window</code> exits. </p> <p>This macro does not call <code>temp-buffer-show-function</code>. Rather, it passes the <var>action</var> argument to <code>display-buffer</code> (see <a href="choosing-window">Choosing Window</a>) in order to display the buffer. </p> <p>The value of the last form in <var>body</var> is returned, unless the argument <var>quit-function</var> is specified. In that case, it is called with two arguments: the window showing the buffer and the result of <var>body</var>. The final return value is then whatever <var>quit-function</var> returns. </p>   <p>This macro uses the normal hooks <code>temp-buffer-window-setup-hook</code> and <code>temp-buffer-window-show-hook</code> in place of the analogous hooks run by <code>with-output-to-temp-buffer</code>. </p>
+</dd>
+</dl> <p>The two constructs described next are mostly identical to <code>with-temp-buffer-window</code> but differ from it as specified: </p> <dl> <dt id="with-current-buffer-window">Macro: <strong>with-current-buffer-window</strong> <em>buffer-or-name action quit-function &amp;rest body</em>
+</dt> <dd><p>This macro is like <code>with-temp-buffer-window</code> but unlike that makes the buffer specified by <var>buffer-or-name</var> current for running <var>body</var>. </p></dd>
+</dl> <p>A window showing a temporary buffer can be fitted to the size of that buffer using the following mode: </p> <dl> <dt id="temp-buffer-resize-mode">User Option: <strong>temp-buffer-resize-mode</strong>
+</dt> <dd>
+<p>When this minor mode is enabled, windows showing a temporary buffer are automatically resized to fit their buffer’s contents. </p> <p>A window is resized if and only if it has been specially created for the buffer. In particular, windows that have shown another buffer before are not resized. By default, this mode uses <code>fit-window-to-buffer</code> (see <a href="resizing-windows">Resizing Windows</a>) for resizing. You can specify a different function by customizing the options <code>temp-buffer-max-height</code> and <code>temp-buffer-max-width</code> below. </p>
+</dd>
+</dl> <dl> <dt id="temp-buffer-max-height">User Option: <strong>temp-buffer-max-height</strong>
+</dt> <dd><p>This option specifies the maximum height (in lines) of a window displaying a temporary buffer when <code>temp-buffer-resize-mode</code> is enabled. It can also be a function to be called to choose the height for such a buffer. It gets one argument, the buffer, and should return a positive integer. At the time the function is called, the window to be resized is selected. </p></dd>
+</dl> <dl> <dt id="temp-buffer-max-width">User Option: <strong>temp-buffer-max-width</strong>
+</dt> <dd><p>This option specifies the maximum width of a window (in columns) displaying a temporary buffer when <code>temp-buffer-resize-mode</code> is enabled. It can also be a function to be called to choose the width for such a buffer. It gets one argument, the buffer, and should return a positive integer. At the time the function is called, the window to be resized is selected. </p></dd>
+</dl> <p>The following function uses the current buffer for temporary display: </p> <dl> <dt id="momentary-string-display">Function: <strong>momentary-string-display</strong> <em>string position &amp;optional char message</em>
+</dt> <dd>
+<p>This function momentarily displays <var>string</var> in the current buffer at <var>position</var>. It has no effect on the undo list or on the buffer’s modification status. </p> <p>The momentary display remains until the next input event. If the next input event is <var>char</var>, <code>momentary-string-display</code> ignores it and returns. Otherwise, that event remains buffered for subsequent use as input. Thus, typing <var>char</var> will simply remove the string from the display, while typing (say) <kbd>C-f</kbd> will remove the string from the display and later (presumably) move point forward. The argument <var>char</var> is a space by default. </p> <p>The return value of <code>momentary-string-display</code> is not meaningful. </p> <p>If the string <var>string</var> does not contain control characters, you can do the same job in a more general way by creating (and then subsequently deleting) an overlay with a <code>before-string</code> property. See <a href="overlay-properties">Overlay Properties</a>. </p> <p>If <var>message</var> is non-<code>nil</code>, it is displayed in the echo area while <var>string</var> is displayed in the buffer. If it is <code>nil</code>, a default message says to type <var>char</var> to continue. </p> <p>In this example, point is initially located at the beginning of the second line: </p> <div class="example"> <pre class="example">---------- Buffer: foo ----------
+This is the contents of foo.
+∗Second line.
+---------- Buffer: foo ----------
+</pre>
+
+<pre class="example">(momentary-string-display
+  "**** Important Message! ****"
+  (point) ?\r
+  "Type RET when done reading")
+⇒ t
+</pre>
+
+<pre class="example">---------- Buffer: foo ----------
+This is the contents of foo.
+**** Important Message! ****Second line.
+---------- Buffer: foo ----------
+
+---------- Echo Area ----------
+Type RET when done reading
+---------- Echo Area ----------
+</pre>
+</div> </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/Temporary-Displays.html" class="_attribution-link">https://www.gnu.org/software/emacs/manual/html_node/elisp/Temporary-Displays.html</a>
+  </p>
+</div>