bug#30343: make transpose-regions interactive

[Eli Zaretskii <eliz@gnu.org>]

> Date: Sun, 04 Feb 2018 10:45:45 +0100
> From: charles@aurox.ch (Charles A. Roelli)
> 
> What follows is a patch to make transpose-regions interactive.
> 
> I also noticed that transpose-sentences/paragraphs are not documented,
> so I'll add those in another commit.

Thanks.

> @@ -183,7 +185,7 @@ Transpose
>  (@code{transpose-lines}) exchanges lines.  They work like @kbd{M-t}
>  except as regards what units of text they transpose.
>  
> -  A numeric argument to a transpose command serves as a repeat count: it
> +  A numeric argument to most transpose commands serves as a repeat count: it
> [...]
> +@findex transpose-regions
> +  @kbd{M-x transpose-regions} transposes the text between point and
> +mark with the text between the first two elements of the mark ring.

I would say "... with the text between the last two marks pushed to
the mark ring."  I would also add a cross-reference here to where
set-mark-command is described.

> +Unlike the other transpose commands, it does not behave differently
> +when given a prefix argument.  This command is best used for
> +transposing multiple units of text (words, sentences, paragraphs) in
> +one go.

Would it make sense to make the new command interpret the prefix
argument the same way as the other transpose commands?  E.g., why not
use pairs of marks further back in the mark ring?

> -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 \"Mark ring must contain at least two elements\")\
> +          (list (point) (mark) (car mark-ring) (cadr mark-ring)))",

The error message could be made more clear, e.g. by saying that the
other region should be marked first.  Talking about the size of the
mark ring is too technical, IMO.

> +Interactively, STARTR1 and ENDR1 are point and mark.  STARTR2 and
> +ENDR2 are the first and second markers in the mark ring.
> +LEAVE-MARKERS is nil.  */)

"First and second" is ambiguous, since you don't tell from which end
they are counted.  Also, these 3 sentences all talk about interactive
invocation, so they should probably be a single sentence separated
with semi-colons instead.