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

[Eli Zaretskii <eliz@gnu.org>]

> 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.