git-for-steve tweaks.

[sxemacs] / info / sxemacs / buffers.texi

@node Buffers, Windows, Files, Top
@chapter Using Multiple Buffers

@cindex buffers
  Text you are editing in Emacs resides in an object called a
@dfn{buffer}.  Each time you visit a file, Emacs creates a buffer to
hold the file's text.  Each time you invoke Dired, Emacs creates a buffer
to hold the directory listing.  If you send a message with @kbd{C-x m},
a buffer named @samp{*mail*} is used to hold the text of the message.
When you ask for a command's documentation, it appears in a buffer
called @samp{*Help*}.

@cindex selected buffer
@cindex current buffer
  At any time, one and only one buffer is @dfn{selected}.  It is also
called the @dfn{current buffer}.  Saying a command operates on ``the
buffer'' really means that the command operates on the selected
buffer, as most commands do.

  When Emacs creates multiple windows, each window has a chosen buffer which
is displayed there, but at any time only one of the windows is selected and
its chosen buffer is the selected buffer.  Each window's mode line displays
the name of the buffer the window is displaying (@pxref{Windows}).

  Each buffer has a name which can be of any length but is
case-sensitive.  You can select a buffer using its name.  Most
buffers are created when you visit files; their names are derived from
the files' names.  You can also create an empty buffer with any name you
want.  A newly started Emacs has a buffer named @samp{*scratch*} which
you can use for evaluating Lisp expressions in Emacs.

  Each buffer records 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}.

@menu
* Select Buffer::   Creating a new buffer or reselecting an old one.
* List Buffers::    Getting a list of buffers that exist.
* Misc Buffer::     Renaming; changing read-onliness; copying text.
* Kill Buffer::     Killing buffers you no longer need.
* Several Buffers:: How to go through the list of all buffers
                     and operate variously on several of them.
@end menu

@node Select Buffer, List Buffers, Buffers, Buffers
@section Creating and Selecting Buffers
@cindex changing buffers
@cindex switching buffers

@table @kbd
@item C-x b @var{buffer} @key{RET}
Select or create a buffer named @var{buffer} (@code{switch-to-buffer}).
@item C-x 4 b @var{buffer} @key{RET}
Similar, but select a buffer named @var{buffer} in another window
(@code{switch-to-buffer-other-window}).
@item M-x switch-to-other-buffer @var{n}
Switch to the previous buffer.
@end table

@kindex C-x 4 b
@kindex C-x 5 b
@findex switch-to-buffer-other-window
@kindex C-x b
@findex switch-to-buffer
@findex switch-to-buffer-other-frame
  To select a buffer named @var{bufname}, type @kbd{C-x b @var{bufname}
@key{RET}}.  This is the command @code{switch-to-buffer} with argument
@var{bufname}.  You can use completion on an abbreviation for the buffer
name you want (@pxref{Completion}).  An empty argument to @kbd{C-x b}
specifies the most recently selected buffer that is not displayed in any
window.@refill

  Most buffers are created when you visit files, or use Emacs commands
that display text.  You can also create a buffer explicitly by typing
@kbd{C-x b @var{bufname} @key{RET}}, which creates a new, empty buffer
that is not visiting any file, and selects it for editing.  The new
buffer's major mode is determined by the value of
@code{default-major-mode} (@pxref{Major Modes}).  Buffers not visiting
files are usually used for making notes to yourself.  If you try to save
one, you are asked for the file name to use.

 The function @code{switch-to-buffer-other-frame} is similar to
@code{switch-to-buffer} except that it creates a new frame in which to
display the selected buffer.

@findex switch-to-other-buffer
Use @kbd{M-x switch-to-other-buffer} to visit the previous buffer. If
you supply a positive integer @var{n}, the @var{n}th most recent buffer
is displayed. If you supply an argument of 0, the current buffer is
moved to the bottom of the buffer stack.

  Note that you can also use @kbd{C-x C-f} and any other command for
visiting a file to switch buffers.  @xref{Visiting}.

@node List Buffers, Misc Buffer, Select Buffer, Buffers
@section Listing Existing Buffers

@table @kbd
@item C-x C-b
List the existing buffers (@code{list-buffers}).
@end table

@kindex C-x C-b
@findex list-buffers
  To print a list of all existing buffers, type @kbd{C-x C-b}.  Each
line in the list shows one buffer's name, major mode, and visited file.
A @samp{*} at the beginning of a line indicates the buffer has been
``modified''.  If several buffers are modified, it may be time to save
some with @kbd{C-x s} (@pxref{Saving}).  A @samp{%} indicates a read-only
buffer.  A @samp{.} marks the selected buffer.  Here is an example of a
buffer list:@refill

@smallexample
 MR Buffer         Size  Mode           File
 -- ------         ----  ----           ----
.*  emacs.tex      383402 Texinfo       /u2/emacs/man/emacs.tex
    *Help*         1287  Fundamental
    files.el       23076 Emacs-Lisp     /u2/emacs/lisp/files.el
  % RMAIL          64042 RMAIL          /u/rms/RMAIL
 *% man            747   Dired          /u2/emacs/man/
    net.emacs      343885 Fundamental   /u/rms/net.emacs
    fileio.c       27691 C              /u2/emacs/src/fileio.c
    NEWS           67340 Text           /u2/emacs/etc/NEWS
    *scratch*      0     Lisp Interaction
@end smallexample

@noindent
Note that the buffer @samp{*Help*} was made by a help request; it is not
visiting any file.  The buffer @code{man} was made by Dired on the
directory @file{/u2/emacs/man/}.

As you move the mouse over the @samp{*Buffer List*} buffer, the lines
are highlighted.  This visual cue indicates that clicking the right
mouse button (@code{button3}) will pop up a menu of commands on the
buffer represented by this line.  This menu duplicates most of those
commands which are bound to keys in the @samp{*Buffer List*} buffer.

@node Misc Buffer, Kill Buffer, List Buffers, Buffers
@section Miscellaneous Buffer Operations

@table @kbd
@item C-x C-q
Toggle read-only status of buffer (@code{toggle-read-only}).
@item M-x rename-buffer
Change the name of the current buffer.
@item M-x view-buffer
Scroll through a buffer.
@end table

@cindex read-only buffer
@kindex C-x C-q
@findex toggle-read-only
@vindex buffer-read-only
  A buffer can be @dfn{read-only}, which means that commands to change
its text are not allowed.  Normally, read-only buffers are created by
subsystems such as Dired and Rmail that have special commands to operate
on the text.  Emacs also creates a read-only buffer if you
visit a file that is protected.  To make changes in a read-only buffer,
use the command @kbd{C-x C-q} (@code{toggle-read-only}).  It makes a
read-only buffer writable, and makes a writable buffer read-only.  This
works by setting the variable @code{buffer-read-only}, which has a local
value in each buffer and makes a buffer read-only if its value is
non-@code{nil}.

@findex rename-buffer
  @kbd{M-x rename-buffer} changes the name of the current buffer,
prompting for the new name in the minibuffer.  There is no default.  If you
specify a name that is used by a different buffer, an error is signalled and
renaming is not done.

@findex view-buffer
  @kbd{M-x view-buffer} is similar to @kbd{M-x view-file} (@pxref{Misc
File Ops}), but it examines an already existing Emacs buffer.  View mode
provides convenient commands for scrolling through the buffer but not
for changing it.  When you exit View mode, the resulting value of point
remains in effect.

To copy text from one buffer to another, use the commands @kbd{M-x
append-to-buffer} and @kbd{M-x insert-buffer}.  @xref{Accumulating
Text}.@refill

@node Kill Buffer, Several Buffers, Misc Buffer, Buffers
@section Killing Buffers

  After using Emacs for a while, you may accumulate a large number of
buffers and may want to eliminate the ones you no
longer need.  There are several commands for doing this.

@c WideCommands
@table @kbd
@item C-x k
Kill a buffer, specified by name (@code{kill-buffer}).
@item M-x kill-some-buffers
Offer to kill each buffer, one by one.
@end table

@findex kill-buffer
@findex kill-some-buffers
@kindex C-x k

  @kbd{C-x k} (@code{kill-buffer}) kills one buffer, whose name you
specify in the minibuffer.  If you type just @key{RET} in the
minibuffer, the default, killing the current buffer, is used.  If the
current buffer is killed, the buffer that has been selected recently but
does not appear in any window now is selected.  If the buffer being
killed contains unsaved changes, you are asked to 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}.

@node Several Buffers,, Kill Buffer, 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 a
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.
@end table

@findex buffer-menu
  The command @code{buffer-menu} writes a list of all Emacs buffers into
the buffer @samp{*Buffer List*}, and selects that buffer in Buffer Menu
mode.  The buffer is read-only.  You can only change it using the special
commands described in this section.  Most of the commands are graphic
characters.  You can use  Emacs cursor motion commands in the
@samp{*Buffer List*} buffer.  If the cursor is on a line describing a
buffer, the following  special commands apply to that buffer:

@table @kbd
@item d
Request to delete (kill) the buffer, then move down.  A @samp{D} before
the buffer name on a line indicates a deletion request.  Requested
deletions actually take place when you use the @kbd{x} command.
@item k
Synonym for @kbd{d}.
@item C-d
Like @kbd{d} but move up afterwards instead of down.
@item s
Request to save the buffer.  An @samp{S} before the buffer name on a line
indicates the request.  Requested saves actually take place when you use
the @kbd{x} command.  You can request both saving and deletion for the
same buffer.
@item ~
Mark buffer ``unmodified''.  The command @kbd{~} does this
immediately when typed.
@item x
Perform previously requested deletions and saves.
@item u
Remove any request made for the current line, and move down.
@item @key{DEL}
Move to previous line and remove any request made for that line.
@end table

  All commands that add or remove flags to request later operations
also move down a line.  They accept a numeric argument as a repeat count,
unless otherwise specified.

  There are also special commands to use the buffer list to select another
buffer, and to specify one or more other buffers for display in additional
windows.

@table @kbd
@item 1
Select the buffer in a full-frame window.  This command takes effect
immediately.
@item 2
Immediately set up two windows, with this buffer in one and the
buffer selected before @samp{*Buffer List*} in the other.
@item f
Immediately select the buffer in place of the @samp{*Buffer List*} buffer.
@item o
Immediately select the buffer in another window as if by @kbd{C-x 4 b},
leaving @samp{*Buffer List*} visible.
@item q
Immediately select this buffer, and display any buffers previously
flagged with the @kbd{m} command in other windows.  If there are no
buffers flagged with @kbd{m}, this command is equivalent to @kbd{1}.
@item m
Flag this buffer to be displayed in another window if the @kbd{q}
command is used.  The request shows as a @samp{>} at the beginning of
the line.  The same buffer may not have both a delete request and a
display request.
@end table

 Going back between a @code{buffer-menu} buffer and other Emacs buffers is
easy.  You can, for example, switch from the @samp{*Buffer List*}
buffer to another Emacs buffer, and edit there.  You can then reselect the
@code{buffer-menu} buffer and perform operations already
requested, or you can kill that buffer or pay no further attention to it.
 All that @code{buffer-menu} does directly is create and select a
suitable buffer, and turn on Buffer Menu mode.  All the other
capabilities of the buffer menu are implemented by special commands
provided in Buffer Menu mode.

  The only difference between @code{buffer-menu} and @code{list-buffers} is
that @code{buffer-menu} selects the @samp{*Buffer List*} buffer and
@code{list-buffers} does not.  If you run @code{list-buffers} (that is,
type @kbd{C-x C-b}) and select the buffer list manually, you can use all
the commands described here.