update.
[chise/xemacs-chise.git.1] / man / xemacs / buffers.texi
1
2 @node Buffers, Windows, Files, Top
3 @chapter Using Multiple Buffers
4
5 @cindex buffers
6   Text you are editing in Emacs resides in an object called a
7 @dfn{buffer}.  Each time you visit a file, Emacs creates a buffer to
8 hold the file's text.  Each time you invoke Dired, Emacs creates a buffer
9 to hold the directory listing.  If you send a message with @kbd{C-x m},
10 a buffer named @samp{*mail*} is used to hold the text of the message.
11 When you ask for a command's documentation, it appears in a buffer
12 called @samp{*Help*}.
13
14 @cindex selected buffer
15 @cindex current buffer
16   At any time, one and only one buffer is @dfn{selected}.  It is also
17 called the @dfn{current buffer}.  Saying a command operates on ``the
18 buffer'' really means that the command operates on the selected
19 buffer, as most commands do.
20
21   When Emacs creates multiple windows, each window has a chosen buffer which
22 is displayed there, but at any time only one of the windows is selected and
23 its chosen buffer is the selected buffer.  Each window's mode line displays
24 the name of the buffer the window is displaying (@pxref{Windows}).
25
26   Each buffer has a name which can be of any length but is
27 case-sensitive.  You can select a buffer using its name.  Most
28 buffers are created when you visit files; their names are derived from
29 the files' names.  You can also create an empty buffer with any name you
30 want.  A newly started Emacs has a buffer named @samp{*scratch*} which
31 you can use for evaluating Lisp expressions in Emacs.
32
33   Each buffer records what file it is visiting, whether it is
34 modified, and what major mode and minor modes are in effect in it
35 (@pxref{Major Modes}).  Any Emacs variable can be made @dfn{local to} a
36 particular buffer, meaning its value in that buffer can be different from
37 the value in other buffers.  @xref{Locals}.
38
39 @menu
40 * Select Buffer::   Creating a new buffer or reselecting an old one.
41 * List Buffers::    Getting a list of buffers that exist.
42 * Misc Buffer::     Renaming; changing read-onliness; copying text.
43 * Kill Buffer::     Killing buffers you no longer need.
44 * Several Buffers:: How to go through the list of all buffers
45                      and operate variously on several of them.
46 @end menu
47
48 @node Select Buffer, List Buffers, Buffers, Buffers
49 @section Creating and Selecting Buffers
50 @cindex changing buffers
51 @cindex switching buffers
52
53 @table @kbd
54 @item C-x b @var{buffer} @key{RET}
55 Select or create a buffer named @var{buffer} (@code{switch-to-buffer}).
56 @item C-x 4 b @var{buffer} @key{RET}
57 Similar, but select a buffer named @var{buffer} in another window
58 (@code{switch-to-buffer-other-window}).
59 @item M-x switch-to-other-buffer @var{n}
60 Switch to the previous buffer.
61 @end table
62
63 @kindex C-x 4 b
64 @kindex C-x 5 b
65 @findex switch-to-buffer-other-window
66 @kindex C-x b
67 @findex switch-to-buffer
68 @findex switch-to-buffer-other-frame
69   To select a buffer named @var{bufname}, type @kbd{C-x b @var{bufname}
70 @key{RET}}.  This is the command @code{switch-to-buffer} with argument
71 @var{bufname}.  You can use completion on an abbreviation for the buffer
72 name you want (@pxref{Completion}).  An empty argument to @kbd{C-x b}
73 specifies the most recently selected buffer that is not displayed in any
74 window.@refill
75
76   Most buffers are created when you visit files, or use Emacs commands
77 that display text.  You can also create a buffer explicitly by typing
78 @kbd{C-x b @var{bufname} @key{RET}}, which creates a new, empty buffer
79 that is not visiting any file, and selects it for editing.  The new
80 buffer's major mode is determined by the value of
81 @code{default-major-mode} (@pxref{Major Modes}).  Buffers not visiting
82 files are usually used for making notes to yourself.  If you try to save
83 one, you are asked for the file name to use.
84
85  The function @code{switch-to-buffer-other-frame} is similar to
86 @code{switch-to-buffer} except that it creates a new frame in which to
87 display the selected buffer.
88
89 @findex switch-to-other-buffer
90 Use @kbd{M-x switch-to-other-buffer} to visit the previous buffer. If
91 you supply a positive integer @var{n}, the @var{n}th most recent buffer
92 is displayed. If you supply an argument of 0, the current buffer is
93 moved to the bottom of the buffer stack.
94
95   Note that you can also use @kbd{C-x C-f} and any other command for
96 visiting a file to switch buffers.  @xref{Visiting}.
97
98 @node List Buffers, Misc Buffer, Select Buffer, Buffers
99 @section Listing Existing Buffers
100
101 @table @kbd
102 @item C-x C-b
103 List the existing buffers (@code{list-buffers}).
104 @end table
105
106 @kindex C-x C-b
107 @findex list-buffers
108   To print a list of all existing buffers, type @kbd{C-x C-b}.  Each
109 line in the list shows one buffer's name, major mode, and visited file.
110 A @samp{*} at the beginning of a line indicates the buffer has been
111 ``modified''.  If several buffers are modified, it may be time to save
112 some with @kbd{C-x s} (@pxref{Saving}).  A @samp{%} indicates a read-only
113 buffer.  A @samp{.} marks the selected buffer.  Here is an example of a
114 buffer list:@refill
115
116 @smallexample
117  MR Buffer         Size  Mode           File
118  -- ------         ----  ----           ----
119 .*  emacs.tex      383402 Texinfo       /u2/emacs/man/emacs.tex
120     *Help*         1287  Fundamental    
121     files.el       23076 Emacs-Lisp     /u2/emacs/lisp/files.el
122   % RMAIL          64042 RMAIL          /u/rms/RMAIL
123  *% man            747   Dired          /u2/emacs/man/
124     net.emacs      343885 Fundamental   /u/rms/net.emacs
125     fileio.c       27691 C              /u2/emacs/src/fileio.c
126     NEWS           67340 Text           /u2/emacs/etc/NEWS
127     *scratch*      0     Lisp Interaction
128 @end smallexample
129
130 @noindent
131 Note that the buffer @samp{*Help*} was made by a help request; it is not
132 visiting any file.  The buffer @code{man} was made by Dired on the
133 directory @file{/u2/emacs/man/}.
134
135 As you move the mouse over the @samp{*Buffer List*} buffer, the lines
136 are highlighted.  This visual cue indicates that clicking the right
137 mouse button (@code{button3}) will pop up a menu of commands on the
138 buffer represented by this line.  This menu duplicates most of those
139 commands which are bound to keys in the @samp{*Buffer List*} buffer.
140
141 @node Misc Buffer, Kill Buffer, List Buffers, Buffers
142 @section Miscellaneous Buffer Operations
143
144 @table @kbd
145 @item C-x C-q
146 Toggle read-only status of buffer (@code{toggle-read-only}).
147 @item M-x rename-buffer
148 Change the name of the current buffer.
149 @item M-x view-buffer
150 Scroll through a buffer.
151 @end table
152
153 @cindex read-only buffer
154 @kindex C-x C-q
155 @findex toggle-read-only
156 @vindex buffer-read-only
157   A buffer can be @dfn{read-only}, which means that commands to change
158 its text are not allowed.  Normally, read-only buffers are created by
159 subsystems such as Dired and Rmail that have special commands to operate
160 on the text.  Emacs also creates a read-only buffer if you
161 visit a file that is protected.  To make changes in a read-only buffer,
162 use the command @kbd{C-x C-q} (@code{toggle-read-only}).  It makes a
163 read-only buffer writable, and makes a writable buffer read-only.  This
164 works by setting the variable @code{buffer-read-only}, which has a local
165 value in each buffer and makes a buffer read-only if its value is
166 non-@code{nil}.
167
168 @findex rename-buffer
169   @kbd{M-x rename-buffer} changes the name of the current buffer,
170 prompting for the new name in the minibuffer.  There is no default.  If you
171 specify a name that is used by a different buffer, an error is signalled and
172 renaming is not done.
173
174 @findex view-buffer
175   @kbd{M-x view-buffer} is similar to @kbd{M-x view-file} (@pxref{Misc
176 File Ops}), but it examines an already existing Emacs buffer.  View mode
177 provides convenient commands for scrolling through the buffer but not
178 for changing it.  When you exit View mode, the resulting value of point
179 remains in effect.
180
181 To copy text from one buffer to another, use the commands @kbd{M-x
182 append-to-buffer} and @kbd{M-x insert-buffer}.  @xref{Accumulating
183 Text}.@refill
184
185 @node Kill Buffer, Several Buffers, Misc Buffer, Buffers
186 @section Killing Buffers
187
188   After using Emacs for a while, you may accumulate a large number of
189 buffers and may want to eliminate the ones you no
190 longer need.  There are several commands for doing this.
191
192 @c WideCommands
193 @table @kbd
194 @item C-x k
195 Kill a buffer, specified by name (@code{kill-buffer}).
196 @item M-x kill-some-buffers
197 Offer to kill each buffer, one by one.
198 @end table
199
200 @findex kill-buffer
201 @findex kill-some-buffers
202 @kindex C-x k
203  
204   @kbd{C-x k} (@code{kill-buffer}) kills one buffer, whose name you
205 specify in the minibuffer.  If you type just @key{RET} in the
206 minibuffer, the default, killing the current buffer, is used.  If the
207 current buffer is killed, the buffer that has been selected recently but
208 does not appear in any window now is selected.  If the buffer being
209 killed contains unsaved changes, you are asked to confirm with @kbd{yes}
210 before the buffer is killed.
211
212   The command @kbd{M-x kill-some-buffers} asks about each buffer, one by
213 one.  An answer of @kbd{y} means to kill the buffer.  Killing the current
214 buffer or a buffer containing unsaved changes selects a new buffer or asks
215 for confirmation just like @code{kill-buffer}.
216
217 @node Several Buffers,, Kill Buffer, Buffers
218 @section Operating on Several Buffers
219 @cindex buffer menu
220
221   The @dfn{buffer-menu} facility is like a ``Dired for buffers''; it allows
222 you to request operations on various Emacs buffers by editing a
223 buffer containing a list of them.  You can save buffers, kill them
224 (here called @dfn{deleting} them, for consistency with Dired), or display
225 them.
226
227 @table @kbd
228 @item M-x buffer-menu
229 Begin editing a buffer listing all Emacs buffers.
230 @end table
231
232 @findex buffer-menu
233   The command @code{buffer-menu} writes a list of all Emacs buffers into
234 the buffer @samp{*Buffer List*}, and selects that buffer in Buffer Menu
235 mode.  The buffer is read-only.  You can only change it using the special
236 commands described in this section.  Most of the commands are graphic
237 characters.  You can use  Emacs cursor motion commands in the
238 @samp{*Buffer List*} buffer.  If the cursor is on a line describing a
239 buffer, the following  special commands apply to that buffer:
240
241 @table @kbd
242 @item d
243 Request to delete (kill) the buffer, then move down.  A @samp{D} before
244 the buffer name on a line indicates a deletion request.  Requested
245 deletions actually take place when you use the @kbd{x} command.
246 @item k
247 Synonym for @kbd{d}.
248 @item C-d
249 Like @kbd{d} but move up afterwards instead of down.
250 @item s
251 Request to save the buffer.  An @samp{S} before the buffer name on a line
252 indicates the request.  Requested saves actually take place when you use
253 the @kbd{x} command.  You can request both saving and deletion for the
254 same buffer.
255 @item ~
256 Mark buffer ``unmodified''.  The command @kbd{~} does this
257 immediately when typed.
258 @item x
259 Perform previously requested deletions and saves.
260 @item u
261 Remove any request made for the current line, and move down.
262 @item @key{DEL}
263 Move to previous line and remove any request made for that line.
264 @end table
265
266   All commands that add or remove flags to request later operations
267 also move down a line.  They accept a numeric argument as a repeat count,
268 unless otherwise specified.
269
270   There are also special commands to use the buffer list to select another
271 buffer, and to specify one or more other buffers for display in additional
272 windows.
273
274 @table @kbd
275 @item 1
276 Select the buffer in a full-frame window.  This command takes effect
277 immediately.
278 @item 2
279 Immediately set up two windows, with this buffer in one and the
280 buffer selected before @samp{*Buffer List*} in the other.
281 @item f
282 Immediately select the buffer in place of the @samp{*Buffer List*} buffer.
283 @item o
284 Immediately select the buffer in another window as if by @kbd{C-x 4 b},
285 leaving @samp{*Buffer List*} visible.
286 @item q
287 Immediately select this buffer, and display any buffers previously
288 flagged with the @kbd{m} command in other windows.  If there are no 
289 buffers flagged with @kbd{m}, this command is equivalent to @kbd{1}.
290 @item m
291 Flag this buffer to be displayed in another window if the @kbd{q}
292 command is used.  The request shows as a @samp{>} at the beginning of
293 the line.  The same buffer may not have both a delete request and a
294 display request.
295 @end table
296
297  Going back between a @code{buffer-menu} buffer and other Emacs buffers is
298 easy.  You can, for example, switch from the @samp{*Buffer List*}
299 buffer to another Emacs buffer, and edit there.  You can then reselect the
300 @code{buffer-menu} buffer and perform operations already
301 requested, or you can kill that buffer or pay no further attention to it.
302  All that @code{buffer-menu} does directly is create and select a
303 suitable buffer, and turn on Buffer Menu mode.  All the other
304 capabilities of the buffer menu are implemented by special commands
305 provided in Buffer Menu mode.  
306
307   The only difference between @code{buffer-menu} and @code{list-buffers} is
308 that @code{buffer-menu} selects the @samp{*Buffer List*} buffer and
309 @code{list-buffers} does not.  If you run @code{list-buffers} (that is,
310 type @kbd{C-x C-b}) and select the buffer list manually, you can use all
311 the commands described here.