GNU bug report logs - #24860
24.5; doc string of `transpose-sexps'

Previous Next

To add a comment to this bug, you must first unarchive it, by sending
a message to control AT debbugs.gnu.org, with unarchive 24860 in the body.
You can then email your comments to 24860 AT debbugs.gnu.org in the normal way.

Toggle the display of automated, internal messages from the tracker.

Message #5 received at submit <at> debbugs.gnu.org (full text, mbox):

From: Drew Adams <drew.adams <at> oracle.com>
To: bug-gnu-emacs <at> gnu.org
Subject: 24.5; doc string of `transpose-sexps'
Date: Wed, 2 Nov 2016 11:08:54 -0700 (PDT)

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'

Message #10 received at 24860-done <at> debbugs.gnu.org (full text, mbox):

From: Eli Zaretskii <eliz <at> gnu.org>
To: Drew Adams <drew.adams <at> oracle.com>
Cc: 24860-done <at> debbugs.gnu.org
Subject: Re: bug#24860: 24.5; doc string of `transpose-sexps'
Date: Fri, 04 Nov 2016 11:58:11 +0200

> Date: Wed, 2 Nov 2016 11:08:54 -0700 (PDT)
> From: Drew Adams <drew.adams <at> 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.

Previous Next

GNU bug tracking system
Copyright (C) 1999 Darren O. Benham, 1997,2003 nCipher Corporation Ltd, 1994-97 Ian Jackson.