(elisp's) buffer.texi: Vagueness in chapter "The Buffer List"

(elisp's) buffer.texi: Vagueness in chapter "The Buffer List"

[Alan Mackenzie]

Hi, Emacs!

Emacs 21.3, .../lispref/buffers.texi V1.43:

When I evaluate the following form by M-:

  (progn (generate-new-buffer "asdf") (set-buffer "asdf") (buffer-list))

, I find that the new buffer is at the _end_ of the buffer list.  Having
done a set-buffer, I would have expected it to be at the front of the
list.

Would some kind soul please be nice enough to tell me what function I
need here to get my new buffer to the front of the buffer list?  Surely I
don't need to go through a loop calling `bury-buffer' on the other
(infinity - 1) buffers, as suggested in the manual?

#########################################################################

Looking at the fine manual, chapter "The Buffer List" in Elisp, I read
this:

    The "buffer list" is a list of all live buffers.  Creating a buffer
  adds[1] it to this list, and killing a buffer removes it.  The order
  of the buffers in the list is based primarily on[2] how recently each
  buffer has been displayed in the selected window[3].  Buffers move to
  the front of the list when they are selected[4] (selecting a window
  that already displays the buffer counts as selecting the buffer), and
  to the end when they are buried (see `bury-buffer', below). ......

My reactions to it:

[1] Shouldn't this read "adds it to THE END of this list"?
[2] "Based primarily on ..."?  This is very vague, and very irritating.
[3] Surely the Elisp manual (as opposed to the Emacs manual), should say
  what lisp functions change this order, not what user actions.
[4] "when they are selected".  What is the lisp function which does this
  "selection"?  I assumed that it would be `set-buffer', but no.

Thanks in advance for the help!

-- 
Alan Mackenzie (Munich, Germany)

Re: (elisp's) buffer.texi: Vagueness in chapter "The Buffer List"

[Alan Mackenzie]

Hi, Emacs!

I've sorted out my difficulties with the buffer list.  I'd like to
suggest the following patch to the Elisp manual, which I think clears up
the vagueness I was complaining about yesterday.

2005-08-15  Alan Mackenzie  <acm@muc.de>

	* buffers.texi (The Buffer List): Clarify the manipulation of the
	buffer list.


*** buffers.texi	Sun Aug 14 09:23:39 2005
--- buffers-1.43.new.texi	Mon Aug 15 09:27:29 2005
***************
*** 757,772 ****
  @section The Buffer List
  @cindex buffer list
  
!   The @dfn{buffer list} is a list of all live buffers.  Creating a
! buffer adds it to this list, and killing a buffer removes it.  The
! order of the buffers in the list is based primarily on how recently
! each buffer has been displayed in the selected window.  Buffers move
! to the front of the list when they are selected (selecting a window
! that already displays the buffer counts as selecting the buffer), and
! to the end when they are buried (see @code{bury-buffer}, below).
! Several functions, notably @code{other-buffer}, use this ordering.  A
! buffer list displayed for the user also follows this order.
  
    In addition to the fundamental Emacs buffer list, each frame has its
  own version of the buffer list, in which the buffers that have been
  selected in that frame come first, starting with the buffers most
--- 757,775 ----
  @section The Buffer List
  @cindex buffer list
  
!   The @dfn{buffer list} is a list of all live buffers.  The order of
! the buffers in the list is based primarily on how recently each buffer
! has been displayed in a window.  Several functions, notably
! @code{other-buffer}, use this ordering.  A buffer list displayed for
! the user also follows this order.
  
+   Creating a buffer adds it to the end of the buffer list, and killing
+ a buffer removes it.  Buffers move to the front of the list when they
+ are selected for display in a window (@pxref{Displaying Buffers}), and
+ to the end when they are buried (see @code{bury-buffer}, below).
+ There are no functions available to the Lisp programmer which directly
+ manipulate the buffer list.
+   
    In addition to the fundamental Emacs buffer list, each frame has its
  own version of the buffer list, in which the buffers that have been
  selected in that frame come first, starting with the buffers most


-- 
Alan Mackenzie (Munich, Germany)