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

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

On Fri, 4 Nov 2016 07:31:41 -0700 (PDT) Drew Adams <drew.adams@oracle.com> wrote:

>> > +Unlike `transpose-words', point must be between the two sexps and not 
>>   ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
>> > +in the middle of a sexp to be transposed.
>>   ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
>> 
>> 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."
>
> See bug #24860 (https://debbugs.gnu.org/cgi/bugreport.cgi?bug=24860).
>
> That bug points out that the doc statement is incorrect/incomplete.
> But your statement is also incorrect/incomplete, IMO.

Perhaps it's incomplete in not explicitly stating that transposing
succeeds when point is in the middle of a symbol or number, but how is
it incorrect?

> The problem is that "in the middle of a sexp" can mean different
> things.  Which sexp?  In (foo "ab|c" 42), with point at |, is point
> in the middle of a string sexp?  Yes.  Is it in the middle of a list
> sexp?  Yes.  Is it between sexps `foo' and `42'?  Yes.
>
> What does it mean to be in the middle of a list, for example?
> A case mentioned in the bug report is this:
>
>>> 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 |.
>
> Point here is in the middle of the outer list, but it is between the
> two inner lists.  Any text description needs to be more careful and
> explicit, if it really wants to make the point clear.

I think a reasonable interpretation of "in the middle of a sexp" is that
the relevant sexp is the one whose start and end are closer to point
(counting leftwards and rightwards from point, respectively) than those
of any other sexp.  Is there an Emacs function that doesn't respect this
interpretation?

Steve Berman