X-Git-Url: https://code.delx.au/gnu-emacs/blobdiff_plain/6336d8c3d7812815d083de055229ebb840fe6159..b3d50cffbd29d451fab160f691eed135f84a5b4b:/doc/lispref/buffers.texi

diff --git a/doc/lispref/buffers.texi b/doc/lispref/buffers.texi
index 2d7faccf24..4d12185726 100644
--- a/doc/lispref/buffers.texi
+++ b/doc/lispref/buffers.texi
@@ -1,7 +1,7 @@
 @c -*-texinfo-*-
 @c This is part of the GNU Emacs Lisp Reference Manual.
 @c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 1999, 2001, 2002,
-@c   2003, 2004, 2005, 2006, 2007  Free Software Foundation, Inc.
+@c   2003, 2004, 2005, 2006, 2007, 2008  Free Software Foundation, Inc.
 @c See the file elisp.texi for copying conditions.
 @setfilename ../../info/buffers
 @node Buffers, Windows, Backups and Auto-Saving, Top
@@ -30,6 +30,7 @@ not be displayed in any windows.
 * Creating Buffers::    Functions that create buffers.
 * Killing Buffers::     Buffers exist until explicitly killed.
 * Indirect Buffers::    An indirect buffer shares text with some other buffer.
+* Swapping Text::       Swapping text between two buffers.
 * Buffer Gap::          The gap in the buffer.
 @end menu
 
@@ -584,7 +585,7 @@ The counter can wrap around occasionally.
 This function returns @var{buffer}'s character-change modification-count.
 Changes to text properties leave this counter unchanged; however, each
 time text is inserted or removed from the buffer, the counter is reset
-to the value that would be returned @code{buffer-modified-tick}.
+to the value that would be returned by @code{buffer-modified-tick}.
 By comparing the values returned by two @code{buffer-chars-modified-tick}
 calls, you can tell whether a character change occurred in that buffer
 in between the calls.  If @var{buffer} is @code{nil} (or omitted), the
@@ -783,7 +784,7 @@ are selected for display in a window (@pxref{Displaying Buffers}), and
 to the end when they are buried (see @code{bury-buffer}, below).
 There are no functions available to the Lisp programmer which directly
 manipulate the buffer list.
-  
+
   In addition to the fundamental Emacs buffer list, each frame has its
 own version of the buffer list, in which the buffers that have been
 selected in that frame come first, starting with the buffers most
@@ -1136,6 +1137,44 @@ to the current buffer.  If @var{buffer} is not indirect, the value is
 indirect buffer.
 @end defun
 
+@node Swapping Text
+@section Swapping Text Between Two Buffers
+@cindex swap text between buffers
+@cindex virtual buffers
+
+  Specialized modes sometimes need to let the user access from the
+same buffer several vastly different types of text.  For example, you
+may need to display a summary of the buffer text, in addition to
+letting the user access the text itself.
+
+  This could be implemented with multiple buffers (kept in sync when
+the user edits the text), or with narrowing (@pxref{Narrowing}).  But
+these alternatives might sometimes become tedious or prohibitively
+expensive, especially if each type of text requires expensive
+buffer-global operations in order to provide correct display and
+editing commands.
+
+  Emacs provides another facility for such modes: you can quickly swap
+buffer text between two buffers with @code{buffer-swap-text}.  This
+function is very fast because it doesn't move any text, it only
+changes the internal data structures of the buffer object to point to
+a different chunk of text.  Using it, you can pretend that a group of
+two or more buffers are actually a single virtual buffer that holds
+the contents of all the individual buffers together.
+
+@defun buffer-swap-text buffer
+This function swaps text between the current buffer and its argument
+@var{buffer}.  It signals an error if one of the two buffers is an
+indirect buffer (@pxref{Indirect Buffers}) or is a base buffer of an
+indirect buffer.
+
+All the buffer properties that are related to the buffer text are
+swapped as well: the positions of point and mark, all the markers, the
+overlays, the text properties, the undo list, the value of the
+@code{enable-multibyte-characters} flag (@pxref{Text Representations,
+enable-multibyte-characters}), etc.
+@end defun
+
 @node Buffer Gap
 @section The Buffer Gap