[Emacs-diffs] /srv/bzr/emacs/emacs-24 r110800: Doc improvements for Buffer Menu.

[Chong Yidong]

------------------------------------------------------------
revno: 110800
committer: Chong Yidong <address@hidden>
branch nick: emacs-24
timestamp: Wed 2012-11-07 14:54:43 +0800
message:
  Doc improvements for Buffer Menu.
  
  * buffers.texi (Several Buffers): List Buffer Menu command anmes,
  and index the keybindings.  Document tabulated-list-sort.
  (Kill Buffer): Capitalize Buffer Menu.
  
  * trouble.texi (Memory Full): Capitalize Buffer Menu.
modified:
  doc/emacs/ChangeLog
  doc/emacs/buffers.texi
  doc/emacs/trouble.texi
  etc/NEWS

=== modified file 'doc/emacs/ChangeLog'
--- a/doc/emacs/ChangeLog       2012-11-05 18:01:20 +0000
+++ b/doc/emacs/ChangeLog       2012-11-07 06:54:43 +0000
@@ -1,3 +1,11 @@
+2012-11-07  Chong Yidong  <address@hidden>
+
+       * buffers.texi (Several Buffers): List Buffer Menu command anmes,
+       and index the keybindings.  Document tabulated-list-sort.
+       (Kill Buffer): Capitalize Buffer Menu.
+
+       * trouble.texi (Memory Full): Capitalize Buffer Menu.
+
 2012-11-05  Eli Zaretskii  <address@hidden>
 
        * display.texi (Auto Scrolling): Clarify that scroll-step is

=== modified file 'doc/emacs/buffers.texi'
--- a/doc/emacs/buffers.texi    2012-09-23 10:46:50 +0000
+++ b/doc/emacs/buffers.texi    2012-11-07 06:54:43 +0000
@@ -309,7 +309,7 @@
 To kill internal buffers as well, call @code{kill-matching-buffers}
 with a prefix argument.
 
-  The buffer menu feature is also convenient for killing various
+  The Buffer Menu feature is also convenient for killing various
 buffers.  @xref{Several Buffers}.
 
 @vindex kill-buffer-hook
@@ -339,7 +339,7 @@
 
 @node Several Buffers
 @section Operating on Several Buffers
address@hidden buffer menu
address@hidden Buffer Menu
 
 @table @kbd
 @item M-x buffer-menu
@@ -348,7 +348,7 @@
 Similar, but do it in another window.
 @end table
 
-  The @dfn{buffer menu} opened by @kbd{C-x C-b} (@pxref{List Buffers})
+  The @dfn{Buffer Menu} opened by @kbd{C-x C-b} (@pxref{List Buffers})
 does not merely list buffers.  It also allows you to perform various
 operations on buffers, through an interface similar to Dired
 (@pxref{Dired}).  You can save buffers, kill them (here called
@@ -356,106 +356,169 @@
 
 @findex buffer-menu
 @findex buffer-menu-other-window
-  To use the buffer menu, type @kbd{C-x C-b} and switch to the window
+  To use the Buffer Menu, type @kbd{C-x C-b} and switch to the window
 displaying the @file{*Buffer List*} buffer.  You can also type
address@hidden buffer-menu} to open the buffer menu in the selected window.
address@hidden buffer-menu} to open the Buffer Menu in the selected window.
 Alternatively, the command @kbd{M-x buffer-menu-other-window} opens
-the buffer menu in another window, and selects that window.
+the Buffer Menu in another window, and selects that window.
 
-  The buffer menu is a read-only buffer, and can be changed only
+  The Buffer Menu is a read-only buffer, and can be changed only
 through the special commands described in this section.  The usual
-cursor motion commands can be used in this buffer.  The
-following commands apply to the buffer described on the current line:
+cursor motion commands can be used in this buffer.  The following
+commands apply to the buffer described on the current line:
 
 @table @kbd
 @item d
-Request to delete (kill) the buffer, then move down.  The request
-shows as a @samp{D} on the line, before the buffer name.  Requested
-deletions take place when you type the @kbd{x} command.
address@hidden Buffer-menu-delete
address@hidden d @r{(Buffer Menu)}
+Flag the buffer for deletion (killing), then move point to the next
+line (@code{Buffer-menu-delete}).  The deletion flag is indicated by
+the character @samp{D} on the line, before the buffer name.  The
+deletion occurs only when you type the @kbd{x} command (see below).
+
 @item C-d
-Like @kbd{d} but move up afterwards instead of down.
address@hidden Buffer-menu-delete-backwards
address@hidden C-d @r{(Buffer Menu)}
+Like @kbd{d}, but move point up instead of down
+(@code{Buffer-menu-delete-backwards}).
+
 @item s
-Request to save the buffer.  The request shows as an @samp{S} on the
-line.  Requested saves take place when you type the @kbd{x} command.
-You may request both saving and deletion for the same buffer.
address@hidden Buffer-menu-save
address@hidden s @r{(Buffer Menu)}
+Flag the buffer for saving (@code{Buffer-menu-save}).  The save flag
+is indicated by the character @samp{S} on the line, before the buffer
+name.  The saving occurs only when you type @kbd{x}.  You may request
+both saving and deletion for the same buffer.
+
 @item x
-Perform previously requested deletions and saves.
address@hidden Buffer-menu-execute
address@hidden x @r{(Buffer Menu)}
+Perform all flagged deletions and saves (@code{Buffer-menu-execute}).
+
 @item u
-Remove any request made for the current line, and move down.
address@hidden Buffer-menu-unmark
address@hidden u @r{(Buffer Menu)}
+Remove all flags from the current line, and move down
+(@code{Buffer-menu-unmark}).
+
 @item @key{DEL}
-Move to previous line and remove any request made for that line.
address@hidden Buffer-menu-backup-unmark
address@hidden DEL @r{(Buffer Menu)}
+Move to the previous line and remove all flags on that line
+(@code{Buffer-menu-backup-unmark}).
 @end table
 
-  The @kbd{d}, @kbd{C-d}, @kbd{s} and @kbd{u} commands to add or remove
-flags also move down (or up) one line.  They accept a numeric argument
-as a repeat count.
address@hidden
+The commands for adding or removing flags, @kbd{d}, @kbd{C-d}, @kbd{s}
+and @kbd{u}, all accept a numeric argument as a repeat count.
 
-  These commands operate immediately on the buffer listed on the current
-line:
+  The following commands operate immediately on the buffer listed on
+the current line.  They also accept a numeric argument as a repeat
+count.
 
 @table @kbd
 @item ~
-Mark the buffer ``unmodified''.  The command @kbd{~} does this
-immediately when you type it.
address@hidden Buffer-menu-not-modified
address@hidden ~ @r{(Buffer Menu)}
+Mark the buffer as unmodified (@code{Buffer-menu-not-modified}).
address@hidden Commands}.
+
 @item %
-Toggle the buffer's read-only flag.  The command @kbd{%} does
-this immediately when you type it.
address@hidden Buffer-menu-toggle-read-only
address@hidden % @r{(Buffer Menu)}
+Toggle the buffer's read-only status
+(@code{Buffer-menu-toggle-read-only}).  @xref{Misc Buffer}.
+
 @item t
-Visit the buffer as a tags table.  @xref{Select Tags Table}.
address@hidden Buffer-menu-visit-tags-table
address@hidden % @r{(Buffer Menu)}
+Visit the buffer as a tags table
+(@code{Buffer-menu-visit-tags-table}).  @xref{Select Tags Table}.
 @end table
 
-  There are also commands to select another buffer or buffers:
+  The following commands are used to select another buffer or buffers:
 
 @table @kbd
 @item q
-Quit the buffer menu---immediately display the most recent formerly
-visible buffer in its place.
address@hidden quit-window
address@hidden q @r{(Buffer Menu)}
+Quit the Buffer Menu (@code{quit-window}).  The most recent formerly
+visible buffer is displayed in its place.
+
 @item @key{RET}
 @itemx f
-Immediately select this line's buffer in place of the @file{*Buffer
-List*} buffer.
address@hidden Buffer-menu-this-window
address@hidden f @r{(Buffer Menu)}
address@hidden RET @r{(Buffer Menu)}
+Select this line's buffer, replacing the @file{*Buffer List*} buffer
+in its window (@code{Buffer-menu-this-window}).
+
 @item o
-Immediately select this line's buffer in another window as if by
address@hidden 4 b}, leaving @file{*Buffer List*} visible.
address@hidden Buffer-menu-other-window
address@hidden o @r{(Buffer Menu)}
+Select this line's buffer in another window, as if by @kbd{C-x 4 b},
+leaving @file{*Buffer List*} visible
+(@code{Buffer-menu-other-window}).
+
 @item C-o
-Immediately display this line's buffer in another window, but don't
-select the window.
address@hidden Buffer-menu-switch-other-window
address@hidden C-o @r{(Buffer Menu)}
+Display this line's buffer in another window, without selecting it
+(@code{Buffer-menu-switch-other-window}).
+
 @item 1
-Immediately select this line's buffer in a full-screen window.
address@hidden Buffer-menu-1-window
address@hidden 1 @r{(Buffer Menu)}
+Select this line's buffer in a full-frame window
+(@code{Buffer-menu-1-window}).
+
 @item 2
-Immediately set up two windows, with this line's buffer selected in
-one, and the previously current buffer (aside from the buffer
address@hidden List*}) displayed in the other.
address@hidden Buffer-menu-2-window
address@hidden 2 @r{(Buffer Menu)}
+Set up two windows on the current frame, with this line's buffer
+selected in one, and a previously current buffer (aside from
address@hidden List*}) in the other (@code{Buffer-menu-2-window}).
+
 @item b
-Bury the buffer listed on this line.
address@hidden Buffer-menu-bury
address@hidden b @r{(Buffer Menu)}
+Bury this line's buffer (@code{Buffer-menu-bury}).
+
 @item m
address@hidden Buffer-menu-mark
address@hidden m @r{(Buffer Menu)}
 Mark this line's buffer to be displayed in another window if you exit
-with the @kbd{v} command.  The request shows as a @samp{>} at the
-beginning of the line.  (A single buffer may not have both a delete
-request and a display request.)
+with the @kbd{v} command (@code{Buffer-menu-mark}).  The display flag
+is indicated by the character @samp{>} at the beginning of the line.
+(A single buffer may not have both deletion and display flags.)
+
 @item v
-Immediately select this line's buffer, and also display in other windows
-any buffers previously marked with the @kbd{m} command.  If you have not
-marked any buffers, this command is equivalent to @kbd{1}.
address@hidden Buffer-menu-select
address@hidden v @r{(Buffer Menu)}
+Select this line's buffer, and also display in other windows any
+buffers flagged with the @kbd{m} command (@code{Buffer-menu-select}).
+If you have not flagged any buffers, this command is equivalent to
address@hidden
 @end table
 
-  There is also a command that affects the entire buffer list:
+  The following commands affect the entire buffer list:
 
 @table @kbd
address@hidden S
address@hidden tabulated-list-sort
address@hidden S @r{(Buffer Menu)}
+Sort the Buffer Menu entries according to their values in the column
+at point.  With a numeric prefix argument @var{n}, sort according to
+the @var{n}-th column (@code{tabulated-list-sort}).
+
 @item T
-Delete, or reinsert, lines for non-file buffers.  This command toggles
-the inclusion of such buffers in the buffer list.
address@hidden Buffer-menu-toggle-files-only
address@hidden T @r{(Buffer Menu)}
+Delete, or reinsert, lines for non-file buffers
address@hidden).  This command toggles the
+inclusion of such buffers in the buffer list.
 @end table
 
-  What @code{buffer-menu} actually does is create and switch to a
-suitable buffer, and turn on Buffer Menu mode in it.  Everything else
-described above is implemented by the special commands provided in
-Buffer Menu mode.  One consequence of this is that you can switch from
-the @file{*Buffer List*} buffer to another Emacs buffer, and edit
-there.  You can reselect the @file{*Buffer List*} buffer later, to
-perform the operations already requested, or you can kill it, or pay
-no further attention to it.
-
   Normally, the buffer @file{*Buffer List*} is not updated
 automatically when buffers are created and killed; its contents are
 just text.  If you have created, deleted or renamed buffers, the way
@@ -633,7 +696,6 @@
 @findex msb-mode
 @cindex mode, MSB
 @cindex MSB mode
address@hidden buffer menu
 @findex mouse-buffer-menu
 @kindex C-Down-Mouse-1
   MSB global minor mode (``MSB'' stands for ``mouse select buffer'')

=== modified file 'doc/emacs/trouble.texi'
--- a/doc/emacs/trouble.texi    2012-10-30 12:48:42 +0000
+++ b/doc/emacs/trouble.texi    2012-11-07 06:54:43 +0000
@@ -275,7 +275,7 @@
 editing in the same Emacs session.
 
   Do not use @kbd{M-x buffer-menu} to save or kill buffers when you run
-out of memory, because the buffer menu needs a fair amount of memory
+out of memory, because the Buffer Menu needs a fair amount of memory
 itself, and the reserve supply may not be enough.
 
 @node Crashing

=== modified file 'etc/NEWS'
--- a/etc/NEWS  2012-11-07 05:22:10 +0000
+++ b/etc/NEWS  2012-11-07 06:54:43 +0000
@@ -577,7 +577,7 @@
 that the sql statement will be terminated by a semicolon.
 
 ** Tabulated List and packages derived from it
-
++++
 *** New command `tabulated-list-sort', bound to `S', sorts the column
 at point, or the Nth column if a numeric prefix argument is given.