[Emacs-diffs] feature/gnus-select 5276bca 052/218: Make transpose-regions interactive (Bug#30343)

[Andrew G Cohen]

branch: feature/gnus-select
commit 5276bca8f2170122a95848fa3b59324c553de5f4
Author: Charles A. Roelli <address@hidden>
Commit: Andrew G Cohen <address@hidden>

    Make transpose-regions interactive (Bug#30343)
    
    * doc/emacs/fixit.texi (Transpose): Mention and explain the new
    command.
    * editfns.c (Ftranspose_regions): Add an interactive calling
    specification, and add documentation for it.
---
 doc/emacs/fixit.texi | 11 +++++++++++
 src/editfns.c        | 20 ++++++++++++++++++--
 2 files changed, 29 insertions(+), 2 deletions(-)

diff --git a/doc/emacs/fixit.texi b/doc/emacs/fixit.texi
index 7cacac4..eb783d1 100644
--- a/doc/emacs/fixit.texi
+++ b/doc/emacs/fixit.texi
@@ -149,6 +149,8 @@ Transpose two words (@code{transpose-words}).
 Transpose two balanced expressions (@code{transpose-sexps}).
 @item C-x C-t
 Transpose two lines (@code{transpose-lines}).
address@hidden M-x transpose-regions
+Transpose two regions.
 @end table
 
 @kindex C-t
@@ -204,6 +206,15 @@ otherwise a command with a repeat count of zero would do 
nothing): to
 transpose the character (or word or expression or line) ending after
 point with the one ending after the mark.
 
address@hidden transpose-regions
+  @kbd{M-x transpose-regions} transposes the text between point and
+mark with the text between the last two marks pushed to the mark ring
+(@pxref{Setting Mark}).  With a numeric prefix argument, it transposes
+the text between point and mark with the text between two successive
+marks that many entries back in the mark ring.  This command is best
+used for transposing multiple characters (or words or sentences or
+paragraphs) in one go.
+
 @node Fixing Case
 @section Case Conversion
 
diff --git a/src/editfns.c b/src/editfns.c
index debe105..6ecc83f 100644
--- a/src/editfns.c
+++ b/src/editfns.c
@@ -5100,7 +5100,16 @@ transpose_markers (ptrdiff_t start1, ptrdiff_t end1,
     }
 }
 
-DEFUN ("transpose-regions", Ftranspose_regions, Stranspose_regions, 4, 5, 0,
+DEFUN ("transpose-regions", Ftranspose_regions, Stranspose_regions, 4, 5,
+       "(if (< (length mark-ring) 2)\
+           (error \"Other region must be marked before transposing two 
regions\")\
+         (let* ((num (if current-prefix-arg\
+                        (prefix-numeric-value current-prefix-arg)\
+                       0))\
+                (ring-length (length mark-ring))\
+                (eltnum (mod num ring-length))\
+                (eltnum2 (mod (1+ num) ring-length)))\
+           (list (point) (mark) (elt mark-ring eltnum) (elt mark-ring 
eltnum2))))",
        doc: /* Transpose region STARTR1 to ENDR1 with STARTR2 to ENDR2.
 The regions should not be overlapping, because the size of the buffer is
 never changed in a transposition.
@@ -5108,7 +5117,14 @@ never changed in a transposition.
 Optional fifth arg LEAVE-MARKERS, if non-nil, means don't update
 any markers that happen to be located in the regions.
 
-Transposing beyond buffer boundaries is an error.  */)
+Transposing beyond buffer boundaries is an error.
+
+Interactively, STARTR1 and ENDR1 are point and mark; STARTR2 and ENDR2
+are the last two marks pushed to the mark ring; LEAVE-MARKERS is nil.
+If a prefix argument N is given, STARTR2 and ENDR2 are the two
+successive marks N entries back in the mark ring.  A negative prefix
+argument instead counts forward from the oldest mark in the mark
+ring.  */)
   (Lisp_Object startr1, Lisp_Object endr1, Lisp_Object startr2, Lisp_Object 
endr2, Lisp_Object leave_markers)
 {
   register ptrdiff_t start1, end1, start2, end2;