(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)