From 854a1c0a61c8754beab95734db772298bc60cbea Mon Sep 17 00:00:00 2001 From: Eli Zaretskii Date: Sat, 20 Jan 2018 21:37:30 +0200 Subject: [PATCH] Improve "Buffers" in the user manual Suggested by John Cummings 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'. --- doc/emacs/buffers.texi | 58 +++++++++++++++++++++++------------------- 1 file 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 -- 2.39.2