[Emacs-diffs] Changes to emacs/doc/emacs/buffers.texi,v

[Chong Yidong]

CVSROOT:        /sources/emacs
Module name:    emacs
Changes by:     Chong Yidong <cyd>      08/10/11 17:35:25

Index: buffers.texi
===================================================================
RCS file: /sources/emacs/emacs/doc/emacs/buffers.texi,v
retrieving revision 1.3
retrieving revision 1.4
diff -u -b -r1.3 -r1.4
--- buffers.texi        2 May 2008 07:20:33 -0000       1.3
+++ buffers.texi        11 Oct 2008 17:35:20 -0000      1.4
@@ -13,32 +13,31 @@
 @samp{*mail*} is used to hold the text of the message.  When you ask for a
 command's documentation, that appears in a buffer called @samp{*Help*}.
 
+  Each buffer has a unique name, which can be of any length.  When a
+buffer is displayed in a window, its name is shown in the mode line
+(@pxref{Mode Line}).  The distinction between upper and lower case
+matters in buffer names.  Most buffers are made by visiting files, and
+their names are derived from the files' names; however, you can also
+create an empty buffer with any name you want.  A newly started Emacs
+has a buffer named @samp{*scratch*}, which is not associated with any
+file and can be used for evaluating Lisp expressions in Emacs
+(@pxref{Lisp Interaction}).
+
 @cindex selected buffer
 @cindex current buffer
-  At any time, one and only one buffer is @dfn{current}.  It is also
-called the @dfn{selected buffer}.  Often we say that a command operates on
-``the buffer'' as if there were only one; but really this means that the
-command operates on the current buffer (most commands do).
-
-  When Emacs has multiple windows, each window has its own chosen
-buffer and displays it; at any time, only one of the windows is
-selected, and its chosen buffer is the current buffer.  Each window's
-mode line normally displays the name of the window's chosen buffer
-(@pxref{Windows}).
-
-  Each buffer has a name, which can be of any length, and you can select
-any buffer by giving its name.  Most buffers are made by visiting files,
-and their names are derived from the files' names.  But you can also create
-an empty buffer with any name you want.  A newly started Emacs has a buffer
-named @samp{*scratch*} which can be used for evaluating Lisp expressions in
-Emacs.  The distinction between upper and lower case matters in buffer
-names.
-
-  Each buffer records individually what file it is visiting, whether it is
-modified, and what major mode and minor modes are in effect in it
-(@pxref{Major Modes}).  Any Emacs variable can be made @dfn{local to} a
-particular buffer, meaning its value in that buffer can be different from
-the value in other buffers.  @xref{Locals}.
+  At any time, one and only one buffer is @dfn{current}.  This is also
+called the @dfn{selected buffer}.  We often say that a command
+operates on ``the buffer''; this really means that the command
+operates on the current buffer (most commands do).  When there is only
+one Emacs window, the buffer displayed in that window is current.
+When there are multiple windows present, the buffer displayed in the
address@hidden window} is current.  @xref{Windows}.
+
+  Each buffer records individually what file it is visiting (if any),
+whether it is modified, and what major mode and minor modes are in
+effect (@pxref{Major Modes}).  Any Emacs variable can be made
address@hidden to} a particular buffer, meaning its value in that buffer
+can be different from the value in other buffers.  @xref{Locals}.
 
 @cindex buffer size, maximum
   A buffer's size cannot be larger than some maximum, which is defined
@@ -85,13 +84,22 @@
 
 @kindex C-x b
 @findex switch-to-buffer
-  To select the buffer named @var{bufname}, type @kbd{C-x b @var{bufname}
address@hidden  This runs the command @code{switch-to-buffer} with argument
address@hidden  You can use completion to enter the buffer
-name (@pxref{Completion}).  An empty argument to @kbd{C-x b}
-specifies the buffer that was current most recently among those not
+  To select the buffer named @var{bufname}, type @kbd{C-x b
address@hidden @key{RET}}.  This runs the command
address@hidden with argument @var{bufname}.  While entering
+the buffer name, you can use the usual minibuffer completion and
+history commands (@pxref{Minibuffer}).  An empty argument to @kbd{C-x
+b} specifies the buffer that was current most recently among those not
 now displayed in any window.
 
+  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
+editing.  You can use such a buffer for making temporary notes.  If
+you try to save it, you are asked for the file name to use.  The new
+buffer's major mode is determined by the variable
address@hidden; the default value is Fundamental mode.
address@hidden Modes}.
+
 @kindex C-x @key{LEFT}
 @kindex C-x @key{RIGHT}
 @findex next-buffer
@@ -106,19 +114,23 @@
 @findex switch-to-buffer-other-window
 @vindex even-window-heights
   To select a buffer in a window other than the current one, type
address@hidden 4 b @var{bufname} @key{RET}}.  This runs the command
address@hidden which displays the buffer
address@hidden in another window.  By default, if displaying the buffer
-causes two vertically adjacent windows to be displayed, the heights of
-those windows are evened out; to countermand that and preserve the
-window configuration, set the variable @code{even-window-heights} to
address@hidden
address@hidden 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.  By default, if displaying
+the buffer causes two vertically adjacent windows to be displayed, the
+heights of those windows are evened out; to countermand that and
+preserve the window configuration, set the variable
address@hidden to @code{nil}.
 
 @kindex C-x 5 b
 @findex switch-to-buffer-other-frame
-  Similarly, @kbd{C-x 5 b @var{buffer} @key{RET}} runs the command
address@hidden which selects a buffer in another
-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.
+
+  In addition, @kbd{C-x C-f}, and any other command for visiting a
+file, can also be used to switch to an existing file-visiting buffer.
address@hidden
 
 @vindex display-buffer-reuse-frames
   You can control how certain buffers are handled by these commands by
@@ -130,31 +142,18 @@
 address@hidden, and the buffer you want to switch to is already
 displayed in some frame, Emacs will just raise that frame.
 
-  Most buffers are created by visiting files, or by Emacs commands that
-want to display some text, but you can also create a buffer explicitly
-by typing @kbd{C-x b @var{bufname} @key{RET}}.  This makes a new, empty
-buffer that is not visiting any file, and selects it for editing.  Such
-buffers are used for making notes to yourself.  If you try to save one,
-you are asked for the file name to use.  The new buffer's major mode is
-determined by the value of @code{default-major-mode} (@pxref{Major
-Modes}).
-
-  Note that @kbd{C-x C-f}, and any other command for visiting a file,
-can also be used to switch to an existing file-visiting buffer.
address@hidden
-
-  @kbd{C-u M-g M-g}, that is @code{goto-line} with a prefix argument
-of just @kbd{C-u}, reads a number @var{n} using the minibuffer,
-selects the most recently selected buffer other than the current
-buffer in another window, and then moves point to the beginning of
-line number @var{n} in that buffer.  This is mainly useful in a buffer
-that refers to line numbers in another buffer: if point is on or just
-after a number, @code{goto-line} uses that number as the default for
address@hidden  Note that prefix arguments other than just @kbd{C-u} behave
-differently.  @kbd{C-u 4 M-g M-g} goes to line 4 in the @emph{current}
-buffer, without reading a number from the minibuffer.  (Remember that
address@hidden M-g} without prefix argument reads a number @var{n} and then
-moves to line number @var{n} in the current buffer.)
+  @kbd{C-u M-g M-g}, that is @code{goto-line} with a plain prefix
+argument, reads a number @var{n} using the minibuffer, selects the
+most recently selected buffer other than the current buffer in another
+window, and then moves point to the beginning of line number @var{n}
+in that buffer.  This is mainly useful in a buffer that refers to line
+numbers in another buffer: if point is on or just after a number,
address@hidden uses that number as the default for @var{n}.  Note
+that prefix arguments other than just @kbd{C-u} behave differently.
address@hidden 4 M-g M-g} goes to line 4 in the @emph{current} buffer,
+without reading a number from the minibuffer.  (Remember that @kbd{M-g
+M-g} without prefix argument reads a number @var{n} and then moves to
+line number @var{n} in the current buffer.  @xref{Moving Point}.)
 
   Emacs uses buffer names that start with a space for internal purposes.
 It treats these buffers specially in minor ways---for example, by
@@ -177,11 +176,11 @@
 The buffers are listed in the order that they were current; the
 buffers that were current most recently come first.
 
-  @samp{*} in the first field of a line indicates the buffer is
-``modified.''  If several buffers are modified, it may be time to save
-some with @kbd{C-x s} (@pxref{Save Commands}).  @samp{%} indicates a
-read-only buffer.  @samp{.} marks the current buffer.  Here is an
-example of a buffer list:@refill
+  @samp{.} in the first field of a line indicates that the buffer is
+current.  @samp{%} indicates a read-only buffer.  @samp{*} indicates
+that the buffer is ``modified.''  If several buffers are modified, it
+may be time to save some with @kbd{C-x s} (@pxref{Save Commands}).
+Here is an example of a buffer list:
 
 @smallexample
 CRM Buffer                Size  Mode              File
@@ -197,16 +196,15 @@
 @end smallexample
 
 @noindent
-Note that the buffer @samp{*Help*} was made by a help request; it is
-not visiting any file.  The buffer @code{src} was made by Dired on the
-directory @file{~/cvs/emacs/src/}.  You can list only buffers that are
-visiting files by giving the command a prefix argument, as in
+The buffer @samp{*Help*} was made by a help request (@pxref{Help}); it
+is not visiting any file.  The buffer @code{src} was made by Dired on
+the directory @file{~/cvs/emacs/src/}.  You can list only buffers that
+are visiting files by giving the command a prefix argument, as in
 @kbd{C-u C-x C-b}.
 
   @code{list-buffers} omits buffers whose names begin with a space,
 unless they visit files: such buffers are used internally by Emacs.
 
address@hidden 2000
 @node Misc Buffer
 @section Miscellaneous Buffer Operations
 
@@ -291,28 +289,37 @@
 Kill buffer @var{bufname} (@code{kill-buffer}).
 @item M-x kill-some-buffers
 Offer to kill each buffer, one by one.
address@hidden M-x kill-matching-buffers
+Offer to kill all buffers matching a regular expression.
 @end table
 
 @findex kill-buffer
address@hidden kill-some-buffers
 @kindex C-x k
-
   @kbd{C-x k} (@code{kill-buffer}) kills one buffer, whose name you
 specify in the minibuffer.  The default, used if you type just
 @key{RET} in the minibuffer, is to kill the current buffer.  If you
 kill the current buffer, another buffer becomes current: one that was
 current in the recent past but is not displayed in any window now.  If
-you ask to kill a file-visiting buffer that is modified (has unsaved
-editing), then you must confirm with @kbd{yes} before the buffer is
-killed.
-
-  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.  Killing the current
-buffer or a buffer containing unsaved changes selects a new buffer or asks
-for confirmation just like @code{kill-buffer}.
+you ask to kill a file-visiting buffer that is modified, then you must
+confirm with @kbd{yes} before the buffer is killed.
 
-  The buffer menu feature (@pxref{Several Buffers}) is also convenient
-for killing various buffers.
address@hidden 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
address@hidden  This command ignores buffers whose names begin
+with a space, which are used internally by Emacs.
+
address@hidden kill-matching-buffers
+  The command @kbd{M-x kill-matching-buffers} prompts for a regular
+expression and kills all buffers whose names match that expression.
address@hidden  Like @code{kill-some-buffers}, it asks for
+confirmation before each kill.  This command normally ignores buffers
+whose names begin with a space, which are used internally by Emacs.
+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
+buffers.  @xref{Several Buffers}.
 
 @vindex kill-buffer-hook
   If you want to do something special every time a buffer is killed, you
@@ -332,24 +339,17 @@
 @vindex midnight-mode
 @vindex midnight-hook
   You can also have this buffer purging done for you, every day at
-midnight, by enabling Midnight mode.  Midnight mode operates each day at
-midnight; at that time, it runs @code{clean-buffer-list}, or whichever
-functions you have placed in the normal hook @code{midnight-hook}
-(@pxref{Hooks}).
-
-  To enable Midnight mode, use the Customization buffer to set the
-variable @code{midnight-mode} to @code{t}.  @xref{Easy Customization}.
+midnight, by enabling Midnight mode.  Midnight mode operates each day
+at midnight; at that time, it runs @code{clean-buffer-list}, or
+whichever functions you have placed in the normal hook
address@hidden (@pxref{Hooks}).  To enable Midnight mode, use
+the Customization buffer to set the variable @code{midnight-mode} to
address@hidden  @xref{Easy Customization}.
 
 @node Several Buffers
 @section Operating on Several Buffers
 @cindex buffer menu
 
-  The @dfn{buffer-menu} facility is like a ``Dired for buffers''; it allows
-you to request operations on various Emacs buffers by editing an Emacs
-buffer containing a list of them.  You can save buffers, kill them
-(here called @dfn{deleting} them, for consistency with Dired), or display
-them.
-
 @table @kbd
 @item M-x buffer-menu
 Begin editing a buffer listing all Emacs buffers.
@@ -357,19 +357,24 @@
 Similar, but do it in another window.
 @end table
 
+  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
address@hidden them, for consistency with Dired), or display them.
+
 @findex buffer-menu
 @findex buffer-menu-other-window
-  The command @code{buffer-menu} writes a list of all Emacs
address@hidden which don't visit files and whose names begin
-with a space are omitted: these are used internally by Emacs.} into the
-buffer @samp{*Buffer List*}, and selects that buffer in Buffer Menu
-mode.
-
-  The buffer is read-only, and can be
-changed only through the special commands described in this section.
-The usual Emacs cursor motion commands can be used in the @samp{*Buffer
-List*} buffer.  The following commands apply to the buffer described on
-the current line.
+  To use the buffer menu, type @kbd{C-x C-b} and switch to the window
+displaying the @samp{*Buffer List*} buffer.  You can also type
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 is a read-only buffer, and can be changed only
+through the special commands described in this section.  The usual
+Emacs 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
@@ -460,16 +465,6 @@
 perform the operations already requested, or you can kill it, or pay
 no further attention to it.
 
-  The list in the @samp{*Buffer List*} buffer looks exactly like the
-buffer list described in @ref{List Buffers}, because they really are
-the same.  The only difference between @code{buffer-menu} and
address@hidden is that @code{buffer-menu} switches to the
address@hidden List*} buffer in the selected window;
address@hidden displays the same buffer in another window.  If
-you run @code{list-buffers} (that is, type @kbd{C-x C-b}) and select
-the buffer list manually, you can use all of the commands described
-here.
-
   Normally, the buffer @samp{*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
@@ -486,11 +481,6 @@
 @xref{Autorevert, global-auto-revert-non-file-buffers}, for details.
 @end ifnottex
 
-
-  The command @code{buffer-menu-other-window} works the same as
address@hidden, except that it displays the buffers list in
-another window.
-
 @node Indirect Buffers
 @section Indirect Buffers
 @cindex indirect buffer
@@ -518,7 +508,7 @@
   The text of the indirect buffer is always identical to the text of its
 base buffer; changes made by editing either one are visible immediately
 in the other.  But in all other respects, the indirect buffer and its
-base buffer are completely separate.  They have different names,
+base buffer are completely separate.  They can have different names,
 different values of point, different narrowing, different markers,
 different major modes, and different local variables.
 
@@ -530,6 +520,7 @@
   One way to use indirect buffers is to display multiple views of an
 outline.  @xref{Outline Views}.
 
address@hidden clone-indirect-buffer-hook
   A quick and handy way to make an indirect buffer is with the command
 @kbd{M-x clone-indirect-buffer}.  It creates and selects an indirect
 buffer whose base buffer is the current buffer.  With a numeric
@@ -537,7 +528,8 @@
 uses the name of the current buffer, with a @samp{<@var{n}>} suffix
 added.  @kbd{C-x 4 c} (@code{clone-indirect-buffer-other-window})
 works like @kbd{M-x clone-indirect-buffer}, but it selects the new
-buffer in another window.
+buffer in another window.  These functions run the hook
address@hidden after creating the indirect buffer.
 
   The more general way to make an indirect buffer is with the command
 @kbd{M-x make-indirect-buffer}.  It creates an indirect buffer from