new repository

1 files changed, 25 insertions, 0 deletions

diff --git a/devdocs/elisp/quitting-windows.html b/devdocs/elisp/quitting-windows.html
new file mode 100644
index 00000000..cca7b9d1
--- /dev/null
+++ b/devdocs/elisp/quitting-windows.html
@@ -0,0 +1,25 @@
+ <h3 class="section">Quitting Windows</h3>  <p>After a command uses <code>display-buffer</code> to put a buffer on the screen, the user may decide to hide it and return to the previous configuration of the Emacs display. We call that <em>quitting the window</em>. The way to do this is to call <code>quit-window</code> while the window used by <code>display-buffer</code> is the selected window. </p> <p>The right way to restore the previous configuration of the display depends on what was done to the window where the buffer now appears. It might be right to delete that window, or delete its frame, or just display another buffer in that window. One complication is that the user may have changed the window configuration since the act of displaying that buffer, and it would be undesirable to undo the user’s explicitly requested changes. </p> <p>To enable <code>quit-window</code> to do the right thing, <code>display-buffer</code> saves information about what it did in the window’s <code>quit-restore</code> parameter (see <a href="window-parameters">Window Parameters</a>). </p> <dl> <dt id="quit-window">Command: <strong>quit-window</strong> <em>&amp;optional kill window</em>
+</dt> <dd>
+<p>This command quits <var>window</var> and buries its buffer. The argument <var>window</var> must be a live window and defaults to the selected one. With prefix argument <var>kill</var> non-<code>nil</code>, it kills the buffer instead of burying it. </p>  <p>The function <code>quit-window</code> first runs <code>quit-window-hook</code>. Then it calls the function <code>quit-restore-window</code>, described next, which does the hard work. </p>
+</dd>
+</dl> <p>You can get more control by calling <code>quit-restore-window</code> instead. </p> <dl> <dt id="quit-restore-window">Function: <strong>quit-restore-window</strong> <em>&amp;optional window bury-or-kill</em>
+</dt> <dd>
+<p>This function handles <var>window</var> and its buffer after quitting. The optional argument <var>window</var> must be a live window and defaults to the selected one. The function takes account of the <var>window</var>’s <code>quit-restore</code> parameter. </p> <p>The optional argument <var>bury-or-kill</var> specifies how to deal with <var>window</var>’s buffer. The following values are meaningful: </p> <dl compact> <dt><code>nil</code></dt> <dd>
+<p>This means to not deal with the buffer in any particular way. As a consequence, if <var>window</var> is not deleted, invoking <code>switch-to-prev-buffer</code> will usually show the buffer again. </p> </dd> <dt><code>append</code></dt> <dd>
+<p>This means that if <var>window</var> is not deleted, its buffer is moved to the end of <var>window</var>’s list of previous buffers (see <a href="window-history">Window History</a>), so it’s less likely that future invocations of <code>switch-to-prev-buffer</code> will switch to it. Also, it moves the buffer to the end of the frame’s buffer list (see <a href="buffer-list">Buffer List</a>). </p> </dd> <dt><code>bury</code></dt> <dd>
+<p>This means that if <var>window</var> is not deleted, its buffer is removed from <var>window</var>’s list of previous buffers. Also, it moves the buffer to the end of the frame’s buffer list. This is the most reliable way to prevent <code>switch-to-prev-buffer</code> from switching to this buffer again, short of killing the buffer. </p> </dd> <dt><code>kill</code></dt> <dd><p>This means to kill <var>window</var>’s buffer. </p></dd> </dl> <p>The argument <var>bury-or-kill</var> also specifies what to do with <var>window</var>’s frame when <var>window</var> should be deleted, if it is the only window on its frame, and there are other frames on that frame’s terminal. If <var>bury-or-kill</var> equals <code>kill</code>, it means to delete the frame. Otherwise, the fate of the frame is determined by calling <code>frame-auto-hide-function</code> (see below) with that frame as sole argument. </p> <p>This function always sets <var>window</var>’s <code>quit-restore</code> parameter to <code>nil</code> unless it deletes the window. </p>
+</dd>
+</dl> <p>The window <var>window</var>’s <code>quit-restore</code> parameter (see <a href="window-parameters">Window Parameters</a>) should be <code>nil</code> or a list of four elements: </p> <div class="lisp"> <pre class="lisp">(<var>method</var> <var>obuffer</var> <var>owindow</var> <var>this-buffer</var>)
+</pre>
+</div> <p>The first element, <var>method</var>, is one of the four symbols <code>window</code>, <code>frame</code>, <code>same</code> and <code>other</code>. <code>frame</code> and <code>window</code> control how to delete <var>window</var>, while <code>same</code> and <code>other</code> control displaying some other buffer in it. </p> <p>Specifically, <code>window</code> means that the window has been specially created by <code>display-buffer</code>; <code>frame</code> means that a separate frame has been created; <code>same</code>, that the window has only ever displayed this buffer; <code>other</code>, that the window showed another buffer before. </p> <p>The second element, <var>obuffer</var>, is either one of the symbols <code>window</code> or <code>frame</code>, or a list of the form </p> <div class="lisp"> <pre class="lisp">(<var>prev-buffer</var> <var>prev-window-start</var> <var>prev-window-point</var> <var>height</var>)
+</pre>
+</div> <p>which says which buffer was shown in <var>window</var> before, that buffer’s window start (see <a href="window-start-and-end">Window Start and End</a>) and window point (see <a href="window-point">Window Point</a>) positions at that time, and <var>window</var>’s height at that time. If <var>prev-buffer</var> is still live when quitting <var>window</var>, quitting the window may reuse <var>window</var> to display <var>prev-buffer</var>. </p> <p>The third element, <var>owindow</var>, is the window that was selected just before the displaying was done. If quitting deletes <var>window</var>, it tries to select <var>owindow</var>. </p> <p>The fourth element, <var>this-buffer</var>, is the buffer whose displaying set the <code>quit-restore</code> parameter. Quitting <var>window</var> may delete that window only if it still shows that buffer. </p> <p>Quitting <var>window</var> tries to delete it if and only if (1) <var>method</var> is either <code>window</code> or <code>frame</code>, (2) the window has no history of previously-displayed buffers and (3) <var>this-buffer</var> equals the buffer currently displayed in <var>window</var>. If <var>window</var> is part of an atomic window (see <a href="atomic-windows">Atomic Windows</a>), quitting will try to delete the root of that atomic window instead. In either case, it tries to avoid signaling an error when <var>window</var> cannot be deleted. </p> <p>If <var>obuffer</var> is a list, and <var>prev-buffer</var> is still live, quitting displays <var>prev-buffer</var> in <var>window</var> according to the rest of the elements of <var>obuffer</var>. This includes resizing the window to <var>height</var> if it was temporarily resized to display <var>this-buffer</var>. </p> <p>Otherwise, if <var>window</var> was previously used for displaying other buffers (see <a href="window-history">Window History</a>), the most recent buffer in that history will be displayed. </p> <p>The following option specifies a function to do the right thing with a frame containing one window when quitting that window. </p> <dl> <dt id="frame-auto-hide-function">User Option: <strong>frame-auto-hide-function</strong>
+</dt> <dd>
+<p>The function specified by this option is called to automatically hide frames. This function is called with one argument—a frame. </p> <p>The function specified here is called by <code>bury-buffer</code> (see <a href="buffer-list">Buffer List</a>) when the selected window is dedicated and shows the buffer to bury. It is also called by <code>quit-restore-window</code> (see above) when the frame of the window to quit has been specially created for displaying that window’s buffer and the buffer is not killed. </p> <p>The default is to call <code>iconify-frame</code> (see <a href="visibility-of-frames">Visibility of Frames</a>). Alternatively, you may specify either <code>delete-frame</code> (see <a href="deleting-frames">Deleting Frames</a>) to remove the frame from its display, <code>make-frame-invisible</code> to make the frame invisible, <code>ignore</code> to leave the frame unchanged, or any other function that can take a frame as its sole argument. </p> <p>Note that the function specified by this option is called only if the specified frame contains just one live window and there is at least one other frame on the same terminal. </p> <p>For a particular frame, the value specified here may be overridden by that frame’s <code>auto-hide-function</code> frame parameter (see <a href="frame-interaction-parameters">Frame Interaction Parameters</a>). </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/Quitting-Windows.html" class="_attribution-link">https://www.gnu.org/software/emacs/manual/html_node/elisp/Quitting-Windows.html</a>
+  </p>
+</div>