- There are, in general, many buffers in an Emacs session. At any time,
-one of them is designated as the @dfn{current buffer}. This is the
-buffer in which most editing takes place, because most of the primitives
-for examining or changing text in a buffer operate implicitly on the
-current buffer (@pxref{Text}). Normally the buffer that is displayed on
-the screen in the selected window is the current buffer, but this is not
-always so: a Lisp program can temporarily designate any buffer as
-current in order to operate on its contents, without changing what is
-displayed on the screen.
-
- The way to designate a current buffer in a Lisp program is by calling
-@code{set-buffer}. The specified buffer remains current until a new one
-is designated.
-
- When an editing command returns to the editor command loop, the
-command loop designates the buffer displayed in the selected window as
-current, to prevent confusion: the buffer that the cursor is in when
-Emacs reads a command is the buffer that the command will apply to.
-(@xref{Command Loop}.) Therefore, @code{set-buffer} is not the way to
-switch visibly to a different buffer so that the user can edit it. For
-that, you must use the functions described in @ref{Displaying Buffers}.
-
- @strong{Warning:} Lisp functions that change to a different current buffer
-should not depend on the command loop to set it back afterwards.
-Editing commands written in Emacs Lisp can be called from other programs
-as well as from the command loop; it is convenient for the caller if
-the subroutine does not change which buffer is current (unless, of
-course, that is the subroutine's purpose). Therefore, you should
-normally use @code{set-buffer} within a @code{save-current-buffer} or
-@code{save-excursion} (@pxref{Excursions}) form that will restore the
-current buffer when your function is done. Here is an example, the
-code for the command @code{append-to-buffer} (with the documentation
-string abridged):
+ There are, in general, many buffers in an Emacs session. At any
+time, one of them is designated the @dfn{current buffer}---the buffer
+in which most editing takes place. Most of the primitives for
+examining or changing text operate implicitly on the current buffer
+(@pxref{Text}).
+
+ Normally, the buffer displayed in the selected window is the current
+buffer, but this is not always so: a Lisp program can temporarily
+designate any buffer as current in order to operate on its contents,
+without changing what is displayed on the screen. The most basic
+function for designating a current buffer is @code{set-buffer}.
+
+@defun current-buffer
+This function returns the current buffer.
+
+@example
+@group
+(current-buffer)
+ @result{} #<buffer buffers.texi>
+@end group
+@end example
+@end defun
+
+@defun set-buffer buffer-or-name
+This function makes @var{buffer-or-name} the current buffer.
+@var{buffer-or-name} must be an existing buffer or the name of an
+existing buffer. The return value is the buffer made current.
+
+This function does not display the buffer in any window, so the user
+cannot necessarily see the buffer. But Lisp programs will now operate
+on it.
+@end defun
+
+ When an editing command returns to the editor command loop, Emacs
+automatically calls @code{set-buffer} on the buffer shown in the
+selected window. This is to prevent confusion: it ensures that the
+buffer that the cursor is in, when Emacs reads a command, is the
+buffer to which that command applies (@pxref{Command Loop}). Thus,
+you should not use @code{set-buffer} to switch visibly to a different
+buffer; for that, use the functions described in @ref{Displaying
+Buffers}.
+
+ When writing a Lisp function, do @emph{not} rely on this behavior of
+the command loop to restore the current buffer after an operation.
+Editing commands can also be called as Lisp functions by other
+programs, not just from the command loop; it is convenient for the
+caller if the subroutine does not change which buffer is current
+(unless, of course, that is the subroutine's purpose).
+
+ To operate temporarily on another buffer, put the @code{set-buffer}
+within a @code{save-current-buffer} form. Here, as an example, is a
+simplified version of the command @code{append-to-buffer}: