Re: emacs-25 f708cb2: Clarify doc string of 'transpose-sexps'

[Stephen Berman <stephen.berman@gmx.net>]

On Fri,  4 Nov 2016 09:52:23 +0000 (UTC) eliz@gnu.org (Eli Zaretskii) wrote:

> branch: emacs-25
> commit f708cb22a1608f8a5aea671afebea44d216d9496
> Author: Eli Zaretskii <eliz@gnu.org>
> Commit: Eli Zaretskii <eliz@gnu.org>
>
>     Clarify doc string of 'transpose-sexps'
>     
>     * lisp/simple.el (transpose-sexps): Clarify the conditions for
>     transposing sexps that are lists or strings.  Mention the effect
>     of the prefix argument.  (Bug#24860)
> ---
>  lisp/simple.el |   10 +++++++---
>  1 file changed, 7 insertions(+), 3 deletions(-)
>
> diff --git a/lisp/simple.el b/lisp/simple.el
> index 8f5324f..ff5774e 100644
> --- a/lisp/simple.el
> +++ b/lisp/simple.el
> @@ -6663,9 +6663,13 @@ are interchanged."
>    (transpose-subr 'forward-word arg))
>  
>  (defun transpose-sexps (arg)
> -  "Like \\[transpose-words] but applies to sexps.
> -Does not work on a sexp that point is in the middle of
> -if it is a list or string."
> +  "Like \\[transpose-chars] (`transpose-chars'), but applies to sexps.
> +Unlike `transpose-words', point must be between the two sexps and not
   ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
> +in the middle of a sexp to be transposed.
   ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
> +With non-zero prefix arg ARG, effect is to take the sexp before point
> +and drag it forward past ARG other sexps (backward if ARG is negative).
> +If ARG is zero, the sexps ending at or after point and at or after mark
> +are interchanged."
>    (interactive "*p")
>    (transpose-subr
>     (lambda (arg)

The underlined sentence is not accurate, since transpose-sexps does work
like transpose-words if point is in the middle of a symbol or number.
Here's a more accurate statement: "If point is in the middle of a list
or string, you cannot transpose that sexp with another sexp."

Steve Berman