#

1 files changed, 413 insertions, 0 deletions

diff --git a/man/buffers.texi b/man/buffers.texi
new file mode 100644
index 00000000000..f333f9ae1b1
--- /dev/null
+++ b/man/buffers.texi
@@ -0,0 +1,413 @@
+@c This is part of the Emacs manual.
+@c Copyright (C) 1985, 86, 87, 93, 94, 95, 1997 Free Software Foundation, Inc.
+@c See file emacs.texi for copying conditions.
+@node Buffers, Windows, Files, Top
+@chapter Using Multiple Buffers
+
+@cindex buffers
+  The text you are editing in Emacs resides in an object called a
+@dfn{buffer}.  Each time you visit a file, a buffer is created to hold the
+file's text.  Each time you invoke Dired, a buffer is created 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, 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
+``the buffer'' as if there were only one; but really this means that the
+command operates on the selected buffer (most commands do).
+
+  When Emacs has 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 that the window is displaying (@pxref{Windows}).
+
+  Each buffer has a name, which can be of any length, and you can select
+any buffer by giving its name.  Most buffers are made by visiting files,
+and their names are derived from the files' names.  But you can also create
+an empty buffer with any name you want.  A newly started Emacs has a buffer
+named @samp{*scratch*} which can be used for evaluating Lisp expressions in
+Emacs.  The distinction between upper and lower case matters in buffer
+names.
+
+  Each buffer records individually 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-onlyness; 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.
+* Indirect Buffers::    An indirect buffer shares the text of another buffer. 
+@end menu
+
+@node Select Buffer
+@section Creating and Selecting Buffers
+@cindex change buffers
+@cindex switch 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 @var{buffer} in another window
+(@code{switch-to-buffer-other-window}).
+@item C-x 5 b @var{buffer} @key{RET}
+Similar, but select @var{buffer} in a separate frame
+(@code{switch-to-buffer-other-frame}).
+@end table
+
+@kindex C-x 4 b
+@findex switch-to-buffer-other-window
+@kindex C-x 5 b
+@findex switch-to-buffer-other-frame
+@kindex C-x b
+@findex switch-to-buffer
+  To select the buffer named @var{bufname}, type @kbd{C-x b @var{bufname}
+@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
+
+  Most buffers are created by visiting files, or by Emacs commands that
+want to display some text, but you can also create a buffer explicitly
+by typing @kbd{C-x b @var{bufname} @key{RET}}.  This makes a new, empty
+buffer that is not visiting any file, and selects it for editing.  Such
+buffers are used for making notes to yourself.  If you try to save one,
+you are asked for the file name to use.  The new buffer's major mode is
+determined by the value of @code{default-major-mode} (@pxref{Major
+Modes}).
+
+  Note that @kbd{C-x C-f}, and any other command for visiting a file,
+can also be used to switch to an existing file-visiting buffer.
+@xref{Visiting}.
+
+  Emacs uses buffer names that start with a space for internal purposes.
+It treats these buffers specially in minor ways---for example, by
+default they do not record undo information.  It is best to avoid using
+such buffer names yourself.
+
+@node List Buffers
+@section Listing Existing Buffers
+
+@table @kbd
+@item C-x C-b
+List the existing buffers (@code{list-buffers}).
+@end table
+
+@cindex listing current buffers
+@kindex C-x C-b
+@findex list-buffers
+  To display a list of all the buffers that exist, type @kbd{C-x C-b}.
+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.''
+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
+
+@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/}.
+
+@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}).
+@item M-x rename-buffer @key{RET} @var{name} @key{RET}
+Change the name of the current buffer.
+@item M-x rename-uniquely
+Rename the current buffer by adding @samp{<@var{number}>} to the end.
+@item M-x view-buffer @key{RET} @var{buffer} @key{RET}
+Scroll through buffer @var{buffer}.
+@end table
+
+@kindex C-x C-q
+@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
+its contents are not allowed.  The mode line indicates read-only buffers
+with @samp{%%} or @samp{%*} near the left margin.  Read-only 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.
+
+  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
+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
+Control}.
+
+@findex rename-buffer
+  @kbd{M-x rename-buffer} changes the name of the current buffer.  Specify
+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 view-buffer
+  @kbd{M-x view-buffer} is much like @kbd{M-x view-file} (@pxref{Misc
+File Ops}) except that it examines an already existing Emacs buffer.
+View mode provides commands for scrolling through the buffer
+conveniently but not for changing it.  When you exit View mode with
+@kbd{q}, that switches back to the buffer (and the position) which was
+previously displayed in the window.  Alternatively, if you exit View
+mode with @kbd{e}, the buffer and the value of point that resulted from
+your perusal remain in effect.
+
+  The commands @kbd{M-x append-to-buffer} and @kbd{M-x insert-buffer}
+can be used to copy text from one buffer to another.  @xref{Accumulating
+Text}.@refill
+
+@node Kill Buffer
+@section Killing Buffers
+
+@cindex killing buffers
+  If you continue an Emacs session for a while, you may accumulate a
+large number of buffers.  You may then find it convenient to @dfn{kill}
+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}).
+@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.  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.
+
+  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}.
+
+  The buffer menu feature (@pxref{Several Buffers}) is also convenient
+for killing various buffers.
+
+@vindex kill-buffer-hook
+  If you want to do something special every time a buffer is killed, you
+can add hook functions to the hook @code{kill-buffer-hook} (@pxref{Hooks}).
+
+@findex clean-buffer-list
+  If you run one Emacs session for a period of days, as many people do,
+it can fill up with buffers that you used several days ago.  The command
+@kbd{M-x clean-buffer-list} is a convenient way to purge them; it kills
+all the unmodified buffers that you have not used for a long time.  An
+ordinary buffer is killed if it has not been displayed for three days;
+however, you can specify certain buffers that should never be killed
+automatically, and others that should be killed if they have been unused
+for a mere hour.
+
+@cindex Midnight mode
+@vindex midnight-mode
+@vindex midnight-hook
+  You can also have this buffer purging done for you, every day at
+midnight, by enabling Midnight mode.  Midnight mode operates each day at
+midnight; at that time, it runs @code{clean-buffer-list}, or whichever
+functions you have placed in the normal hook @code{midnight-hook}
+(@pxref{Hooks}).
+
+  To enable Midnight mode, use the Customization buffer to set the
+variable @code{midnight-mode} to @code{t}.  @xref{Easy Customization}.
+
+@node Several 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 an Emacs
+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, 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
+Request to delete (kill) the buffer, then move down.  The request
+shows as a @samp{D} on the line, before the buffer name.  Requested
+deletions take place when you type the @kbd{x} command.
+@item C-d
+Like @kbd{d} but move up afterwards instead of down.
+@item s
+Request to save the buffer.  The request shows as an @samp{S} on the
+line.  Requested saves take place when you type the @kbd{x} command.
+You may request both saving and deletion for the same buffer.
+@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
+
+  The @kbd{d}, @kbd{C-d}, @kbd{s} and @kbd{u} commands to add or remove
+flags also move down (or up) one line.  They accept a numeric argument
+as a repeat count.
+
+  These commands operate immediately on the buffer listed on the current
+line:
+
+@table @kbd
+@item ~
+Mark the buffer ``unmodified.''  The command @kbd{~} does this
+immediately when you type it.
+@item %
+Toggle the buffer's read-only flag.  The command @kbd{%} does
+this immediately when you type it.
+@item t
+Visit the buffer as a tags table.  @xref{Select Tags Table}.
+@end table
+
+  There are also commands to select another buffer or buffers:
+
+@table @kbd
+@item q
+Quit the buffer menu---immediately display the most recent formerly
+visible buffer in its place.
+@item @key{RET}
+@itemx f
+Immediately select this line's buffer in place of the @samp{*Buffer
+List*} buffer.
+@item o
+Immediately select this line's buffer in another window as if by
+@kbd{C-x 4 b}, leaving @samp{*Buffer List*} visible.
+@item C-o
+Immediately display this line's buffer in another window, but don't
+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.
+@item b
+Bury the buffer listed on this line.
+@item m
+Mark this line's buffer to be displayed in another window if you exit
+with the @kbd{v} command.  The request shows as a @samp{>} at the
+beginning of the line.  (A single buffer may not have both a delete
+request and a display request.)
+@item v
+Immediately select this line's buffer, and also display in other windows
+any buffers previously marked with the @kbd{m} command.  If you have not
+marked any buffers, this command is equivalent to @kbd{1}.
+@end table
+
+  All that @code{buffer-menu} does directly is create and switch to a
+suitable buffer, and turn on Buffer Menu mode.  Everything else
+described above is implemented by the special commands provided in
+Buffer Menu mode.  One consequence of this is that you can switch from
+the @samp{*Buffer List*} buffer to another Emacs buffer, and edit there.
+You can reselect the @samp{*Buffer List*} buffer later, to perform the
+operations already requested, or you can kill it, or pay no further
+attention to it.
+
+  The only difference between @code{buffer-menu} and @code{list-buffers}
+is that @code{buffer-menu} switches to the @samp{*Buffer List*} buffer
+in the selected window; @code{list-buffers} displays it in another
+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
+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.
+
+@node Indirect Buffers
+@section Indirect Buffers
+@cindex indirect buffer
+@cindex base buffer
+
+  An @dfn{indirect buffer} shares the text of some other buffer, which
+is called the @dfn{base buffer} of the indirect buffer.  In some ways it
+is the analogue, for buffers, of a symbolic link between files.
+
+@table @kbd
+@findex make-indirect-buffer
+@item M-x make-indirect-buffer @var{base-buffer} @key{RET} @var{indirect-name} @key{RET}
+Create an indirect buffer named @var{indirect-name} whose base buffer
+is @var{base-buffer}.
+@end table
+
+  The text of the indirect buffer is always identical to the text of its
+base buffer; changes made by editing either one are visible immediately
+in the other.  But in all other respects, the indirect buffer and its
+base buffer are completely separate.  They have different names,
+different values of point, different narrowing, different markers,
+different major modes, and different local variables.
+
+  An indirect buffer cannot visit a file, but its base buffer can.  If
+you try to save the indirect buffer, that actually works by saving the
+base buffer.  Killing the base buffer effectively kills the indirect
+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}.