X-Git-Url: https://code.delx.au/gnu-emacs/blobdiff_plain/8f7cad1fa5a7ee6a8d49b353ec02af52881aebd7..937640a621a4ce2e5e56eaecca37a2a28a584318:/man/buffers.texi diff --git a/man/buffers.texi b/man/buffers.texi index 22b05a3934..558b636de6 100644 --- a/man/buffers.texi +++ b/man/buffers.texi @@ -1,5 +1,5 @@ @c This is part of the Emacs manual. -@c Copyright (C) 1985, 86, 87, 93, 94, 95, 97, 2000 +@c Copyright (C) 1985, 86, 87, 93, 94, 95, 97, 2000, 2001, 2004 @c Free Software Foundation, Inc. @c See file emacs.texi for copying conditions. @node Buffers, Windows, Files, Top @@ -15,14 +15,14 @@ command's documentation, that 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}. Often we say that a command operates on + 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 selected buffer (most commands do). +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 selected buffer. Each window's +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}). @@ -40,6 +40,13 @@ modified, and what major mode and minor modes are in effect in it 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 +by the largest buffer position representable by the @dfn{Emacs integer} +data type. This is because Emacs tracks buffer positions using that +data type. For 32-bit machines, the largest buffer size is 256 +megabytes. + @menu * Select Buffer:: Creating a new buffer or reselecting an old one. * List Buffers:: Getting a list of buffers that exist. @@ -47,7 +54,7 @@ the value in other buffers. @xref{Locals}. * 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. -* Indirect Buffers:: An indirect buffer shares the text of another buffer. +* Indirect Buffers:: An indirect buffer shares the text of another buffer. * Buffer Convenience:: Convenience and customization features for buffer handling. @end menu @@ -74,8 +81,8 @@ Similar, but select @var{buffer} in a separate frame @key{RET}}. This runs 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 +specifies the buffer that was current most recently among those not +now displayed in any window. @kindex C-x 4 b @findex switch-to-buffer-other-window @@ -139,39 +146,41 @@ Each line in the list shows one buffer's name, major mode and visited file. The buffers are listed in the order that they were current; the buffers that were current most recently come first. - @samp{*} at the beginning of a line indicates the buffer is ``modified.'' + @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{Saving}). @samp{%} indicates a read-only buffer. @samp{.} marks the -selected buffer. Here is an example of a buffer list:@refill +current 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 +CRM Buffer Size Mode File +. * .emacs 3294 Emacs-Lisp ~/.emacs + % *Help* 101 Help + search.c 86055 C ~/cvs/emacs/src/search.c + % src 20959 Dired by name ~/cvs/emacs/src/ + * *mail* 42 Mail + % HELLO 1607 Fundamental ~/cvs/emacs/etc/HELLO + % NEWS 481184 Outline ~/cvs/emacs/etc/NEWS + *scratch* 191 Lisp Interaction + * *Messages* 1554 Fundamental @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/}. You can list only buffers that are +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; for instance, by typing @kbd{C-u C-x C-b}. +@code{list-buffers} omits buffers whose name begins with a blank, +unless they visit files: such buffers are used internally by Emacs. + @need 2000 @node Misc Buffer @section Miscellaneous Buffer Operations @table @kbd @item C-x C-q -Toggle read-only status of buffer (@code{vc-toggle-read-only}). +Toggle read-only status of buffer (@code{toggle-read-only}). @item M-x rename-buffer @key{RET} @var{name} @key{RET} Change the name of the current buffer. @item M-x rename-uniquely @@ -181,9 +190,6 @@ Scroll through buffer @var{buffer}. @end table @kindex C-x C-q -@c Don't index vc-toggle-read-only here, it is indexed in files.texi, -@c in the node "Basic VC Editing". -@c @findex vc-toggle-read-only @vindex buffer-read-only @cindex read-only buffer A buffer can be @dfn{read-only}, which means that commands to change @@ -193,14 +199,16 @@ buffers are usually made by subsystems such as Dired and Rmail that have special commands to operate on the text; also by visiting a file whose access control says you cannot write it. +@findex toggle-read-only If you wish to make changes in a read-only buffer, use the command -@kbd{C-x C-q} (@code{vc-toggle-read-only}). It makes a read-only buffer -writable, and makes a writable buffer read-only. In most cases, this +@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 the buffer read-only if its value is -non-@code{nil}. If the file is maintained with version control, -@kbd{C-x C-q} works through the version control system to change the -read-only status of the file as well as the buffer. @xref{Version +non-@code{nil}. If you have files under version control, you may find +it convenient to bind @kbd{C-x C-q} to @code{vc-toggle-read-only} +instead. Then, typing @kbd{C-x C-q} not only changes the read-only +flag, but it also checks the file in or out. @xref{Version Control}. @findex rename-buffer @@ -209,14 +217,19 @@ the new name as a minibuffer argument. There is no default. If you specify a name that is in use for some other buffer, an error happens and no renaming is done. - @kbd{M-x rename-uniquely} renames the current buffer to a similar name -with a numeric suffix added to make it both different and unique. This -command does not need an argument. It is useful for creating multiple -shell buffers: if you rename the @samp{*Shell*} buffer, then do @kbd{M-x -shell} again, it makes a new shell buffer named @samp{*Shell*}; -meanwhile, the old shell buffer continues to exist under its new name. -This method is also good for mail buffers, compilation buffers, and most -Emacs features that create special buffers with particular names. +@findex rename-uniquely + @kbd{M-x rename-uniquely} renames the current buffer to a similar +name with a numeric suffix added to make it both different and unique. +This command does not need an argument. It is useful for creating +multiple shell buffers: if you rename the @samp{*Shell*} buffer, then +do @kbd{M-x shell} again, it makes a new shell buffer named +@samp{*Shell*}; meanwhile, the old shell buffer continues to exist +under its new name. This method is also good for mail buffers, +compilation buffers, and most Emacs features that create special +buffers with particular names. (With some of these features, such as +@kbd{M-x compile}, @kbd{M-x grep} an @kbd{M-x info}, you need to +switch to some other buffer before using the command, in order for it +to make a different buffer.) @findex view-buffer @kbd{M-x view-buffer} is much like @kbd{M-x view-file} (@pxref{Misc @@ -242,7 +255,6 @@ the buffers you no longer need. On most operating systems, killing a buffer releases its space back to the operating system so that other programs can use it. Here are some commands for killing buffers: -@c WideCommands @table @kbd @item C-x k @var{bufname} @key{RET} Kill buffer @var{bufname} (@code{kill-buffer}). @@ -255,12 +267,13 @@ Offer to kill each buffer, one by one. @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 is selected; one that has been selected -recently but does not appear 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. +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 @@ -309,15 +322,22 @@ them. @table @kbd @item M-x buffer-menu Begin editing a buffer listing all Emacs buffers. +@item M-x buffer-menu-other-window. +Similar, but do it in another window. @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, 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. +@findex buffer-menu-other-window + The command @code{buffer-menu} writes a list of all Emacs +buffers@footnote{Buffers 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 list in the @samp{*Buffer List*} buffer looks exactly as +described in @ref{List Buffers}. 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. @table @kbd @item d @@ -375,9 +395,9 @@ select the window. @item 1 Immediately select this line's buffer in a full-screen window. @item 2 -Immediately set up two windows, with this line's buffer in one, and the -previously selected buffer (aside from the buffer @samp{*Buffer List*}) -in the other. +Immediately set up two windows, with this line's buffer selected in +one, and the previously current buffer (aside from the buffer +@samp{*Buffer List*}) displayed in the other. @item b Bury the buffer listed on this line. @item m @@ -407,12 +427,23 @@ 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. - The buffer @samp{*Buffer List*} is not updated automatically when + 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 to update @samp{*Buffer List*} to show what you have done is to type @kbd{g} (@code{revert-buffer}) or repeat the @code{buffer-menu} command. + The @samp{*Buffer List*} buffer does automatically update every +@code{auto-revert-interval} seconds if you enable Auto Revert mode in +it. (As long as it is not marked modified.) Global Auto Revert mode +does not update the @samp{*Buffer List*} buffer by default, but it +does if @code{global-auto-revert-non-file-buffers} is non-@code{nil}. +@inforef{Autorevert,, emacs-xtra}, for details. + + The command @code{buffer-menu-other-window} works the same as +@code{buffer-menu}, except that it displays the buffers list in +another window. + @node Indirect Buffers @section Indirect Buffers @cindex indirect buffer @@ -452,22 +483,21 @@ buffer, but killing an indirect buffer has no effect on its base buffer. One way to use indirect buffers is to display multiple views of an outline. @xref{Outline Views}. -@cindex multiple @samp{*info*} and @samp{*Help*} buffers 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 argument, it prompts for the name of the indirect buffer; otherwise it defaults to the name of the current buffer, modifying it by adding a -@samp{<@var{n}>} prefix if required. @kbd{C-x 4 c} +@samp{<@var{n}>} suffix if required. @kbd{C-x 4 c} (@code{clone-indirect-buffer-other-window}) works like @kbd{M-x -clone-indirect-buffer}, but it selects the cloned buffer in another -window. These commands come in handy if you want to create new -@samp{*info*} or @samp{*Help*} buffers, for example. +clone-indirect-buffer}, but it selects the new buffer in another +window. - The more general way is with the command @kbd{M-x -make-indirect-buffer}. It creates an indirect buffer from buffer -@var{base-buffer}, under the name @var{indirect-name}. It prompts for -both @var{base-buffer} and @var{indirect-name} using the minibuffer. + 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 +buffer @var{base-buffer}, under the name @var{indirect-name}. It +prompts for both @var{base-buffer} and @var{indirect-name} using the +minibuffer. @node Buffer Convenience @section Convenience Features and Customization of Buffer Handling @@ -478,7 +508,7 @@ convenient to switch between buffers. @menu * Uniquify:: Buffer names can contain directory parts. * Iswitchb:: Switching between buffers with substrings. -* Buffer Menus:: Configurable buffer menu. +* Buffer Menus:: Configurable buffer menu. @end menu @node Uniquify @@ -582,3 +612,7 @@ provides a different and customizable mouse buffer menu which you may prefer. It replaces the bindings of @code{mouse-buffer-menu}, normally on @kbd{C-Down-Mouse-1}, and the menu bar buffer menu. You can customize the menu in the @code{msb} Custom group. + +@ignore + arch-tag: 08c43460-f4f4-4b43-9cb5-1ea9ad991695 +@end ignore