--- /dev/null
+
+@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.
projects / chise / xemacs-chise.git / blobdiff