*** empty log message ***

1 files changed, 43 insertions, 0 deletions

diff --git a/lispref/text.texi b/lispref/text.texi
index 54ba73353ab..7d33a1c5d14 100644
--- a/lispref/text.texi
+++ b/lispref/text.texi
@@ -48,6 +48,7 @@ buffer.
 * Case Changes::     Case conversion of parts of the buffer.
 * Text Properties::  Assigning Lisp property lists to text characters.
 * Substitution::     Replacing a given character wherever it appears.
+* Transposition::    Swapping two portions of a buffer.
 * Registers::        How registers are implemented.  Accessing the text or
                        position stored in a register.
 * Change Hooks::     Supplying functions to be run when text is changed.
@@ -520,17 +521,21 @@ In the example below, point is located on the line starting
 in the preceding line.
 
 @smallexample
+@group
 ---------- Buffer: foo ----------
 When in the course of human
 @point{}    events, it becomes necessary
 ---------- Buffer: foo ----------
+@end group
 
 (delete-indentation)
      @result{} nil
 
+@group
 ---------- Buffer: foo ----------
 When in the course of human@point{} events, it becomes necessary
 ---------- Buffer: foo ----------
+@end group
 @end smallexample
 
 After the lines are joined, the function @code{fixup-whitespace} is
@@ -2615,6 +2620,25 @@ This function stores the current frame configuration in register
 @end deffn
 @end ignore
 
+@node Transposition
+@section Transposition of Text
+
+  This subroutine is used by the transposition commands.
+
+@defun transpose-regions start1 end1 start2 end2 &optional leave-markers
+This function exchanges two nonoverlapping portions of the buffer.
+Arguments @var{start1} and @var{end1} specify the bounds of one portion
+and arguments @var{start2} and @var{end2} specify the bounds of the
+other portion.
+
+Normally, @code{transpose-regions} relocates markers with the transposed
+text; a marker previously positioned within one of the two transposed
+portions moves along with that portion, thus remaining between the same
+two characters in their new position.  However, if @var{leave-markers}
+is non-@code{nil}, @code{transpose-regions} does not do this---it leaves
+all markers unrelocated.
+@end defun
+
 @node Change Hooks
 @section Change Hooks
 @cindex change hooks
@@ -2665,6 +2689,25 @@ functions.  If you do want a hook function to make changes that run
 these functions, make it bind these variables back to their usual
 values.
 
+One inconvenient result of this protective feature is that you cannot
+have a function in @code{after-change-functions} or
+@code{before-change-functions} which changes the value of that variable.
+But that's not a real limitation.  If you want those functions to change
+the list of functions to run, simply add one fixed function to the hook,
+and code that function to look in another variable for other functions
+to call.  Here is an example:
+
+@example
+(setq my-own-after-change-functions nil)
+(defun indirect-after-change-function (beg end len)
+  (let ((list my-own-after-change-functions))
+    (while list
+      (funcall (car list) beg end len)
+      (setq list (cdr list)))))
+(add-hooks 'after-change-functions
+           'indirect-after-change-function)
+@end example
+
 @defvar first-change-hook
 This variable is a normal hook that is run whenever a buffer is changed
 that was previously in the unmodified state.