Subject: bug#24860: closed (Re: bug#24860: 24.5; doc string of `transpose-sexps')

From: [email-masked] (GNU bug Tracking System)
Date: Fri, 04 Nov 2016 09:58:02 +0000

Your bug report

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

which was filed against the emacs package, has been closed.

The explanation is attached below, along with your original report.
If you require more details, please reply to [email-masked].

-- 
24860: http://debbugs.gnu.org/cgi/bugreport.cgi?bug=24860
GNU Bug Tracking System
Contact [email-masked] with problems

Subject: Re: bug#24860: 24.5; doc string of `transpose-sexps'
From: Eli Zaretskii <[email-masked]>
To: Drew Adams <[email-masked]>
Cc: [email-masked]
Date: Fri, 04 Nov 2016 11:58:11 +0200
List-Id: <debbugs-submit.debbugs.gnu.org>

> Date: Wed, 2 Nov 2016 11:08:54 -0700 (PDT)
> From: Drew Adams <[email-masked]>
> 
> 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.

Subject: 24.5; doc string of `transpose-sexps'
From: Drew Adams <[email-masked]>
To: [email-masked]
Date: Wed, 2 Nov 2016 11:08:54 -0700 (PDT)
List-Id: <debbugs-submit.debbugs.gnu.org>

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'