X-Git-Url: http://git.chise.org/gitweb/?a=blobdiff_plain;f=man%2Fxemacs%2Fbuffers.texi;fp=man%2Fxemacs%2Fbuffers.texi;h=a58710be6466ed25a606c509f3af4edf4c03f4ff;hb=8dd5c14289d68929b069fa5078f10ea3905f6fa5;hp=0000000000000000000000000000000000000000;hpb=f82a8b0d39ee6a8fc9a5373f29b4761184dcc399;p=chise%2Fxemacs-chise.git diff --git a/man/xemacs/buffers.texi b/man/xemacs/buffers.texi new file mode 100644 index 0000000..a58710b --- /dev/null +++ b/man/xemacs/buffers.texi @@ -0,0 +1,311 @@ + +@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.