[Emacs-diffs] Changes to emacs/doc/lispref/buffers.texi,v

[Eli Zaretskii]

CVSROOT:        /cvsroot/emacs
Module name:    emacs
Changes by:     Eli Zaretskii <eliz>    08/10/21 10:00:47

Index: buffers.texi
===================================================================
RCS file: /cvsroot/emacs/emacs/doc/lispref/buffers.texi,v
retrieving revision 1.4
retrieving revision 1.5
diff -u -b -r1.4 -r1.5
--- buffers.texi        22 Jan 2008 23:53:45 -0000      1.4
+++ buffers.texi        21 Oct 2008 10:00:47 -0000      1.5
@@ -30,6 +30,7 @@
 * 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
 
@@ -1136,6 +1137,44 @@
 indirect buffer.
 @end defun
 
address@hidden Swapping Text
address@hidden Swapping Text Between Two Buffers
address@hidden swap text between buffers
address@hidden 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.
+
address@hidden buffer-swap-text buffer
+This function swaps text between the current buffer and its argument
address@hidden  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
address@hidden flag (@pxref{Text Representations,
+enable-multibyte-characters}), etc.
address@hidden defun
+
 @node Buffer Gap
 @section The Buffer Gap