bug#24860: 24.5; doc string of `transpose-sexps'

bug#24860: 24.5; doc string of `transpose-sexps'

[Drew Adams]

1. This part of the doc string is unclear.  I have no idea what it is
really trying to say.

  Does not work on a sexp that point is in the middle of
  if it is a list or string.

What does "does not work" mean?  Raises an error?  Does something that
we cannot describe?  Does nothing?

When point is in the middle of a list it can also be between two sexps,
which themselves could be lists: ((foo)|(bar)), with point at |.  What
"does not work" in that case, with an ARG of 1?

This part of the doc is completely unclear.  What's more, it is not
mentioned in the Emacs manual (node `Expressions').

2. The doc string needs to say, as does the manual (node `Expressions'),
that a zero ARG has particular behavior (and describe it) - it is not a
no-op.

3. I think it would help for the manual (node `Expressions') to give a
simple example showing the usefulness of the zero ARG case.  It's not
too clear from the description why this behavior is provided.


In GNU Emacs 24.5.1 (i686-pc-mingw32)
 of 2015-04-11 on LEG570
Windowing system distributor `Microsoft Corp.', version 6.1.7601
Configured using:
 `configure --prefix=/c/usr --host=i686-pc-mingw32'

bug#24860: 24.5; doc string of `transpose-sexps'

[Eli Zaretskii]

> Date: Wed, 2 Nov 2016 11:08:54 -0700 (PDT)
> From: Drew Adams <drew.adams@oracle.com>
> 
> 1. This part of the doc string is unclear.  I have no idea what it is
> really trying to say.
> 
>   Does not work on a sexp that point is in the middle of
>   if it is a list or string.
> 
> What does "does not work" mean?  Raises an error?  Does something that
> we cannot describe?  Does nothing?

Depending on what are the surrounding sexps and where point is, it
could do any of the above.

> When point is in the middle of a list it can also be between two sexps,
> which themselves could be lists: ((foo)|(bar)), with point at |.  What
> "does not work" in that case, with an ARG of 1?
> 
> This part of the doc is completely unclear.

Since the doc string starts by saying "Like M-t", its intent was to
contrast the behavior against that of transpose-words, where point
could be both between the words and in the middle of a word, in order
to have that word transposed with the next one.  That doesn't work
with sexps.

> What's more, it is not mentioned in the Emacs manual (node
> `Expressions').

It is mentioned, in a way, because the manual says C-M-t is analogous
to C-t, i.e. it doesn't start from M-t.

I clarified this aspect in the doc string.

> 2. The doc string needs to say, as does the manual (node `Expressions'),
> that a zero ARG has particular behavior (and describe it) - it is not a
> no-op.

Added.

> 3. I think it would help for the manual (node `Expressions') to give a
> simple example showing the usefulness of the zero ARG case.  It's not
> too clear from the description why this behavior is provided.

Volunteers are welcome to come up with useful examples, but I think
the bug report can now be closed, as the zero argument case doesn't
have examples in other similar commands as well.

Thanks.