new repository

1 files changed, 44 insertions, 0 deletions

diff --git a/devdocs/elisp/buffer-list.html b/devdocs/elisp/buffer-list.html
new file mode 100644
index 00000000..0a1bb96d
--- /dev/null
+++ b/devdocs/elisp/buffer-list.html
@@ -0,0 +1,44 @@
+ <h3 class="section">The Buffer List</h3>   <p>The <em>buffer list</em> is a list of all live buffers. The order of the buffers in this list is based primarily on how recently each buffer has been displayed in a window. Several functions, notably <code>other-buffer</code>, use this ordering. A buffer list displayed for the user also follows this order. </p> <p>Creating a buffer adds it to the end of the buffer list, and killing a buffer removes it from that list. A buffer moves to the front of this list whenever it is chosen for display in a window (see <a href="switching-buffers">Switching Buffers</a>) or a window displaying it is selected (see <a href="selecting-windows">Selecting Windows</a>). A buffer moves to the end of the list when it is buried (see <code>bury-buffer</code>, below). There are no functions available to the Lisp programmer which directly manipulate the buffer list. </p> <p>In addition to the fundamental buffer list just described, Emacs maintains a local buffer list for each frame, in which the buffers that have been displayed (or had their windows selected) in that frame come first. (This order is recorded in the frame’s <code>buffer-list</code> frame parameter; see <a href="buffer-parameters">Buffer Parameters</a>.) Buffers never displayed in that frame come afterward, ordered according to the fundamental buffer list. </p> <dl> <dt id="buffer-list">Function: <strong>buffer-list</strong> <em>&amp;optional frame</em>
+</dt> <dd>
+<p>This function returns the buffer list, including all buffers, even those whose names begin with a space. The elements are actual buffers, not their names. </p> <p>If <var>frame</var> is a frame, this returns <var>frame</var>’s local buffer list. If <var>frame</var> is <code>nil</code> or omitted, the fundamental buffer list is used: the buffers appear in order of most recent display or selection, regardless of which frames they were displayed on. </p> <div class="example"> <pre class="example">(buffer-list)
+     ⇒ (#&lt;buffer buffers.texi&gt;
+         #&lt;buffer  *Minibuf-1*&gt; #&lt;buffer buffer.c&gt;
+         #&lt;buffer *Help*&gt; #&lt;buffer TAGS&gt;)
+</pre>
+
+<pre class="example">;; <span class="roman">Note that the name of the minibuffer</span>
+;;   <span class="roman">begins with a space!</span>
+(mapcar #'buffer-name (buffer-list))
+    ⇒ ("buffers.texi" " *Minibuf-1*"
+        "buffer.c" "*Help*" "TAGS")
+</pre>
+</div> </dd>
+</dl> <p>The list returned by <code>buffer-list</code> is constructed specifically; it is not an internal Emacs data structure, and modifying it has no effect on the order of buffers. If you want to change the order of buffers in the fundamental buffer list, here is an easy way: </p> <div class="example"> <pre class="example">(defun reorder-buffer-list (new-list)
+  (while new-list
+    (bury-buffer (car new-list))
+    (setq new-list (cdr new-list))))
+</pre>
+</div> <p>With this method, you can specify any order for the list, but there is no danger of losing a buffer or adding something that is not a valid live buffer. </p> <p>To change the order or value of a specific frame’s buffer list, set that frame’s <code>buffer-list</code> parameter with <code>modify-frame-parameters</code> (see <a href="parameter-access">Parameter Access</a>). </p> <dl> <dt id="other-buffer">Function: <strong>other-buffer</strong> <em>&amp;optional buffer visible-ok frame</em>
+</dt> <dd>
+<p>This function returns the first buffer in the buffer list other than <var>buffer</var>. Usually, this is the buffer appearing in the most recently selected window (in frame <var>frame</var> or else the selected frame, see <a href="input-focus">Input Focus</a>), aside from <var>buffer</var>. Buffers whose names start with a space are not considered at all. </p> <p>If <var>buffer</var> is not supplied (or if it is not a live buffer), then <code>other-buffer</code> returns the first buffer in the selected frame’s local buffer list. (If <var>frame</var> is non-<code>nil</code>, it returns the first buffer in <var>frame</var>’s local buffer list instead.) </p> <p>If <var>frame</var> has a non-<code>nil</code> <code>buffer-predicate</code> parameter, then <code>other-buffer</code> uses that predicate to decide which buffers to consider. It calls the predicate once for each buffer, and if the value is <code>nil</code>, that buffer is ignored. See <a href="buffer-parameters">Buffer Parameters</a>. </p> <p>If <var>visible-ok</var> is <code>nil</code>, <code>other-buffer</code> avoids returning a buffer visible in any window on any visible frame, except as a last resort. If <var>visible-ok</var> is non-<code>nil</code>, then it does not matter whether a buffer is displayed somewhere or not. </p> <p>If no suitable buffer exists, the buffer <samp>*scratch*</samp> is returned (and created, if necessary). </p>
+</dd>
+</dl> <dl> <dt id="last-buffer">Function: <strong>last-buffer</strong> <em>&amp;optional buffer visible-ok frame</em>
+</dt> <dd>
+<p>This function returns the last buffer in <var>frame</var>’s buffer list other than <var>buffer</var>. If <var>frame</var> is omitted or <code>nil</code>, it uses the selected frame’s buffer list. </p> <p>The argument <var>visible-ok</var> is handled as with <code>other-buffer</code>, see above. If no suitable buffer can be found, the buffer <samp>*scratch*</samp> is returned. </p>
+</dd>
+</dl> <dl> <dt id="bury-buffer">Command: <strong>bury-buffer</strong> <em>&amp;optional buffer-or-name</em>
+</dt> <dd>
+<p>This command puts <var>buffer-or-name</var> at the end of the buffer list, without changing the order of any of the other buffers on the list. This buffer therefore becomes the least desirable candidate for <code>other-buffer</code> to return. The argument can be either a buffer itself or the name of one. </p> <p>This function operates on each frame’s <code>buffer-list</code> parameter as well as the fundamental buffer list; therefore, the buffer that you bury will come last in the value of <code>(buffer-list <var>frame</var>)</code> and in the value of <code>(buffer-list)</code>. In addition, it also puts the buffer at the end of the list of buffers of the selected window (see <a href="window-history">Window History</a>) provided it is shown in that window. </p> <p>If <var>buffer-or-name</var> is <code>nil</code> or omitted, this means to bury the current buffer. In addition, if the current buffer is displayed in the selected window (see <a href="selecting-windows">Selecting Windows</a>), this makes sure that the window is either deleted or another buffer is shown in it. More precisely, if the selected window is dedicated (see <a href="dedicated-windows">Dedicated Windows</a>) and there are other windows on its frame, the window is deleted. If it is the only window on its frame and that frame is not the only frame on its terminal, the frame is dismissed by calling the function specified by <code>frame-auto-hide-function</code> (see <a href="quitting-windows">Quitting Windows</a>). Otherwise, it calls <code>switch-to-prev-buffer</code> (see <a href="window-history">Window History</a>) to show another buffer in that window. If <var>buffer-or-name</var> is displayed in some other window, it remains displayed there. </p> <p>To replace a buffer in all the windows that display it, use <code>replace-buffer-in-windows</code>, See <a href="buffers-and-windows">Buffers and Windows</a>. </p>
+</dd>
+</dl> <dl> <dt id="unbury-buffer">Command: <strong>unbury-buffer</strong>
+</dt> <dd><p>This command switches to the last buffer in the local buffer list of the selected frame. More precisely, it calls the function <code>switch-to-buffer</code> (see <a href="switching-buffers">Switching Buffers</a>), to display the buffer returned by <code>last-buffer</code> (see above), in the selected window. </p></dd>
+</dl> <dl> <dt id="buffer-list-update-hook">Variable: <strong>buffer-list-update-hook</strong>
+</dt> <dd>
+<p>This is a normal hook run whenever the buffer list changes. Functions (implicitly) running this hook are <code>get-buffer-create</code> (see <a href="creating-buffers">Creating Buffers</a>), <code>rename-buffer</code> (see <a href="buffer-names">Buffer Names</a>), <code>kill-buffer</code> (see <a href="killing-buffers">Killing Buffers</a>), <code>bury-buffer</code> (see above), and <code>select-window</code> (see <a href="selecting-windows">Selecting Windows</a>). This hook is not run for internal or temporary buffers created by <code>get-buffer-create</code> or <code>generate-new-buffer</code> with a non-<code>nil</code> argument <var>inhibit-buffer-hooks</var>. </p> <p>Functions run by this hook should avoid calling <code>select-window</code> with a <code>nil</code> <var>norecord</var> argument since this may lead to infinite recursion. </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/Buffer-List.html" class="_attribution-link">https://www.gnu.org/software/emacs/manual/html_node/elisp/Buffer-List.html</a>
+  </p>
+</div>