Improve "Buffers" in the user manual

Suggested by John Cummings <john@rootabega.net> in
emacs-manual-bugs@gnu.org:
* doc/emacs/buffers.texi (Select Buffer): Add cross-references to
"Windows" and "Frames".
(Misc Buffer, Kill Buffer): Use BUFFER consistently in commands
that accept buffer names.
(Select Buffer): Improve description of "M-g M-g".  Improve
wording.
(Misc Buffer, Kill Buffer): Improve wording.
(Kill Buffer): Fix the response required by kill-some-buffers.
Mention customizable options that control what clean-buffer-list
does.
(Several Buffers): More detail about
'Buffer-menu-unmark-all-buffers'.

1 files changed, 32 insertions, 26 deletions

diff --git a/doc/emacs/buffers.texi b/doc/emacs/buffers.texi
index 47ac8d4b05c..6a8e32bc84b 100644
--- a/doc/emacs/buffers.texi
+++ b/doc/emacs/buffers.texi
@@ -81,7 +81,7 @@ Select the next buffer in the buffer list (@code{next-buffer}).
 @item C-u M-g M-g
 @itemx C-u M-g g
 Read a number @var{n} and move to line @var{n} in the most recently
-selected buffer other than the current buffer.
+selected buffer other than the current buffer, in another window.
 @end table
 
 @kindex C-x b
@@ -94,12 +94,12 @@ now displayed in any window.
 
   While entering the buffer name, you can use the usual completion and
 history commands (@pxref{Minibuffer}).  Note that @kbd{C-x b}, and
-related commands, use @dfn{permissive completion with confirmation} for
-minibuffer completion: if you type @key{RET} immediately after
-completing up to a nonexistent buffer name, Emacs prints
-@samp{[Confirm]} and you must type a second @key{RET} to submit that
-buffer name.  @xref{Completion Exit}, for details.  For other
-completion options and features, see @ref{Completion Options}.
+related commands, use @dfn{permissive completion with confirmation}
+for minibuffer completion: if you type @key{RET} when the minibuffer
+text names a nonexistent buffer, Emacs prints @samp{[Confirm]} and you
+must type a second @key{RET} to submit that buffer name.
+@xref{Completion Exit}, for details.  For other completion options and
+features, see @ref{Completion Options}.
 
   If you specify a buffer that does not exist, @kbd{C-x b} creates a
 new, empty buffer that is not visiting any file, and selects it for
@@ -124,18 +124,19 @@ direction.
 
 @kindex C-x 4 b
 @findex switch-to-buffer-other-window
-  To select a buffer in a window other than the current one, type
-@kbd{C-x 4 b} (@code{switch-to-buffer-other-window}).  This prompts
-for a buffer name using the minibuffer, displays that buffer in
-another window, and selects that window.
+  To select a buffer in a window other than the current one
+(@pxref{Windows}), type @kbd{C-x 4 b}
+(@code{switch-to-buffer-other-window}).  This prompts for a buffer
+name using the minibuffer, displays that buffer in another window, and
+selects that window.
 
 @kindex C-x 5 b
 @findex switch-to-buffer-other-frame
   Similarly, @kbd{C-x 5 b} (@code{switch-to-buffer-other-frame})
-prompts for a buffer name, displays that buffer in another frame, and
-selects that frame.  If the buffer is already being shown in a window
-on another frame, Emacs selects that window and frame instead of
-creating a new frame.
+prompts for a buffer name, displays that buffer in another frame
+(@pxref{Frames}), and selects that frame.  If the buffer is already
+being shown in a window on another frame, Emacs selects that window
+and frame instead of creating a new frame.
 
   @xref{Displaying Buffers}, for how the @kbd{C-x 4 b} and @kbd{C-x 5
 b} commands get the window and/or frame to display in.
@@ -219,7 +220,7 @@ unless they visit files: such buffers are used internally by Emacs.
 @table @kbd
 @item C-x C-q
 Toggle read-only status of buffer (@code{read-only-mode}).
-@item M-x rename-buffer @key{RET} @var{name} @key{RET}
+@item M-x rename-buffer @key{RET} @var{buffer} @key{RET}
 Change the name of the current buffer.
 @item M-x rename-uniquely
 Rename the current buffer by adding @samp{<@var{number}>} to the end.
@@ -234,8 +235,9 @@ Scroll through buffer @var{buffer}.  @xref{View Mode}.
 its contents are not allowed.  The mode line indicates read-only
 buffers with @samp{%%} or @samp{%*} near the left margin.  @xref{Mode
 Line}.  Read-only buffers are usually made by subsystems such as Dired
-and Rmail that have special commands to operate on the text; also by
-visiting a file whose access control says you cannot write it.
+and Rmail that have special commands to operate on the text.  Visiting
+a file whose access control says you cannot write it also makes the
+buffer read-only.
 
 @findex read-only-mode
 @vindex view-read-only
@@ -282,13 +284,13 @@ large number of buffers.  You may then find it convenient to @dfn{kill}
 the buffers you no longer need.  (Some other editors call this
 operation @dfn{close}, and talk about ``closing the buffer'' or
 ``closing the file'' visited in the buffer.)  On most operating
-systems, killing a buffer releases its space back to the operating
-system so that other programs can use it.  Here are some commands for
-killing buffers:
+systems, killing a buffer releases the memory Emacs used for the buffer
+back to the operating system so that other programs can use it.  Here
+are some commands for killing buffers:
 
 @table @kbd
-@item C-x k @var{bufname} @key{RET}
-Kill buffer @var{bufname} (@code{kill-buffer}).
+@item C-x k @var{buffer} @key{RET}
+Kill buffer @var{buffer} (@code{kill-buffer}).
 @item M-x kill-some-buffers
 Offer to kill each buffer, one by one.
 @item M-x kill-matching-buffers
@@ -307,7 +309,7 @@ confirm with @kbd{yes} before the buffer is killed.
 
 @findex kill-some-buffers
   The command @kbd{M-x kill-some-buffers} asks about each buffer, one
-by one.  An answer of @kbd{y} means to kill the buffer, just like
+by one.  An answer of @kbd{yes} means to kill the buffer, just like
 @code{kill-buffer}.  This command ignores buffers whose names begin
 with a space, which are used internally by Emacs.
 
@@ -335,7 +337,9 @@ all the unmodified buffers that you have not used for a long time.  An
 ordinary buffer is killed if it has not been displayed for three days;
 however, you can specify certain buffers that should never be killed
 automatically, and others that should be killed if they have been unused
-for a mere hour.
+for a mere hour.  These defaults, and other aspects of this command's
+behavior, can be controlled by customizing several options described
+in the doc string of @code{clean-buffer-list}.
 
 @cindex Midnight mode
 @vindex midnight-mode
@@ -422,7 +426,9 @@ Move to the previous line and remove all flags on that line
 @findex Buffer-menu-unmark-all-buffers
 @kindex M-DEL @r{(Buffer Menu)}
 Remove a particular flag from all lines
-(@code{Buffer-menu-unmark-all-buffers}).
+(@code{Buffer-menu-unmark-all-buffers}).  This asks for a single
+character, and unmarks buffers marked with that character; typing
+@key{RET} removes all marks.
 
 @item U
 @findex Buffer-menu-unmark-all