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

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

[Stephen Berman]

On Fri,  4 Nov 2016 09:52:23 +0000 (UTC) eliz@gnu.org (Eli Zaretskii) wrote:

> branch: emacs-25
> commit f708cb22a1608f8a5aea671afebea44d216d9496
> Author: Eli Zaretskii <eliz@gnu.org>
> Commit: Eli Zaretskii <eliz@gnu.org>
>
>     Clarify doc string of 'transpose-sexps'
>     
>     * lisp/simple.el (transpose-sexps): Clarify the conditions for
>     transposing sexps that are lists or strings.  Mention the effect
>     of the prefix argument.  (Bug#24860)
> ---
>  lisp/simple.el |   10 +++++++---
>  1 file changed, 7 insertions(+), 3 deletions(-)
>
> diff --git a/lisp/simple.el b/lisp/simple.el
> index 8f5324f..ff5774e 100644
> --- a/lisp/simple.el
> +++ b/lisp/simple.el
> @@ -6663,9 +6663,13 @@ are interchanged."
>    (transpose-subr 'forward-word arg))
>  
>  (defun transpose-sexps (arg)
> -  "Like \\[transpose-words] but applies to sexps.
> -Does not work on a sexp that point is in the middle of
> -if it is a list or string."
> +  "Like \\[transpose-chars] (`transpose-chars'), but applies to sexps.
> +Unlike `transpose-words', point must be between the two sexps and not
   ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
> +in the middle of a sexp to be transposed.
   ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
> +With non-zero prefix arg ARG, effect is to take the sexp before point
> +and drag it forward past ARG other sexps (backward if ARG is negative).
> +If ARG is zero, the sexps ending at or after point and at or after mark
> +are interchanged."
>    (interactive "*p")
>    (transpose-subr
>     (lambda (arg)

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

Steve Berman

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

[Drew Adams]

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

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.

Bug #24860 mentions a few different problems with the doc string.
Some of them were addressed; others apparently not.

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

[Stephen Berman]

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

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

[Drew Adams]

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

What "relevant sexp"?  To say that point is in the middle of a
sexp does not imply that it is in the middle of only one sexp.
There might be any number of such in-the-middle-of, "relevant"
sexps.

> is the one whose start and end are closer to point (counting
> leftwards and rightwards from point, respectively) than those
> of any other sexp.

If that's what is meant then that's what the doc should say:
"the innermost sexp containing point".

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

[Stephen Berman]

On Fri, 4 Nov 2016 09:44:30 -0700 (PDT) Drew Adams <drew.adams@oracle.com> wrote:

>> > 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
>
> What "relevant sexp"?  To say that point is in the middle of a
> sexp does not imply that it is in the middle of only one sexp.
> There might be any number of such in-the-middle-of, "relevant"
> sexps.

>> is the one whose start and end are closer to point (counting
>> leftwards and rightwards from point, respectively) than those
>> of any other sexp.
>
> If that's what is meant then that's what the doc should say:
> "the innermost sexp containing point".

I think that's unnecessary if this is a "reasonable interpretation",
i.e. it's common sense, so making it explicit tends to be pedantic.  Do
you really think this is not the common sense way of understanding it?
If so, I guess you have a function in mind that behaves differently;
which one?

Steve Berman

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

[Drew Adams]

> > If that's what is meant then that's what the doc should say:
> > "the innermost sexp containing point".
> 
> I think that's unnecessary if this is a "reasonable interpretation",
> i.e. it's common sense, so making it explicit tends to be pedantic.
> Do you really think this is not the common sense way of understanding
> it? If so, I guess you have a function in mind that behaves differently;
> which one?

When you know what the code does it is very easy to think
that vague doc is "reasonable" enough and "common sense".
Readers of the doc should not need to depend on what you
might understand of the code.

It is not unreasonable to be clear and brief.  I repeat:
if the doc means "the innermost sexp containing point" then
it should just say that.  That's not being pedantic; it's
being clear.

I stand by the bug #24860 report.  Saying that something
described vaguely "does not work" is not helpful enough.

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

There is no way for users to know what that really means
(except by checking the code).

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

[Stephen Berman]

On Fri, 4 Nov 2016 10:21:36 -0700 (PDT) Drew Adams <drew.adams@oracle.com> wrote:

> It is not unreasonable to be clear and brief.  I repeat:
> if the doc means "the innermost sexp containing point" then
> it should just say that.  That's not being pedantic; it's
> being clear.

So is the following (combining Eli's changes with my correction and your
clarification) then clear enough?

"Like \\[transpose-chars] (`transpose-chars'), but applies to sexps.
If the innermost sexp containing point is a list or string, you cannot
transpose that sexp with another sexp.
With non-zero prefix arg ARG, effect is to take the sexp before point
and drag it forward past ARG other sexps (backward if ARG is negative).
If ARG is zero, the sexps ending at or after point and at or after mark
are interchanged."

Steve Berman

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

[Drew Adams]

> > It is not unreasonable to be clear and brief.  I repeat:
> > if the doc means "the innermost sexp containing point" then
> > it should just say that.  That's not being pedantic; it's
> > being clear.
> 
> So is the following (combining Eli's changes with my correction and
> your clarification) then clear enough?
> 
...
> If the innermost sexp containing point is a list or string, you
> cannot transpose that sexp with another sexp.
...

LGTM.

But as one reader I would still want to know what "cannot"
means here - what happens if you try?  Eli has replied in the
bug thread that there are several possible behaviors (effects),
so I guess we can't usefully say what it means.  Dommage.

Here's a thought: Are any of the behaviors resulting from
trying that useful?  If so, then they should perhaps be
documented.  And if not, why don't we check for that
situation and raise an error if you try?

It is really not great to tell someone they "cannot" or
"must not" etc. do something without raising an error that
really enforces "cannot" etc.

Sure, if you try, the result won't transpose the sexps, so
technically you "cannot" transpose sexps in this case.  But
I'd sooner see a clear error than just some unpredictable
behavior.  (Unpredictable from reading the doc.  There are
multiple possibilities, and we won't be detailing them in
the doc.)

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

[Eli Zaretskii]

> Date: Fri, 4 Nov 2016 11:00:39 -0700 (PDT)
> From: Drew Adams <drew.adams@oracle.com>
> Cc: Eli Zaretskii <eliz@gnu.org>, emacs-devel@gnu.org
> 
> Here's a thought: Are any of the behaviors resulting from
> trying that useful?

No, none of them is.  The only useful behavior is when point is
between the two sexps you want to transpose.

> It is really not great to tell someone they "cannot" or
> "must not" etc. do something without raising an error that
> really enforces "cannot" etc.

If someone comes up with a way to lift that restriction, we could
remove this text from the doc string.  but as long as the command
works as it does, I think we should document that, or else we will
have bug reports about its not meeting expectations.

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

[Eli Zaretskii]

> From: Stephen Berman <stephen.berman@gmx.net>
> Cc: Eli Zaretskii <eliz@gnu.org>,  emacs-devel@gnu.org
> Date: Fri, 04 Nov 2016 18:50:03 +0100
> 
> If the innermost sexp containing point is a list or string, you cannot
> transpose that sexp with another sexp.

IMO, this is not useful.  The doc string should explain this stuff
from the POV of the user who invokes the command.  That user always
knows which sexps she would like to transpose.  That's what I tried to
do with my change, by explicitly alluding to the sexps to be
transposed.

Improvements are welcome, but the above isn't, IMO.

Thanks.

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

[Eli Zaretskii]

> Date: Fri, 4 Nov 2016 10:21:36 -0700 (PDT)
> From: Drew Adams <drew.adams@oracle.com>
> Cc: Eli Zaretskii <eliz@gnu.org>, emacs-devel@gnu.org
> 
>   "Does not work on a sexp that point is in the middle of
>   if it is a list or string."
> 
> There is no way for users to know what that really means
> (except by checking the code).

This sentence is no longer in the doc string.

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

[Eli Zaretskii]

> Date: Fri, 4 Nov 2016 07:31:41 -0700 (PDT)
> From: Drew Adams <drew.adams@oracle.com>
> Cc: Eli Zaretskii <eliz@gnu.org>
> 
> > > +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.

The above commit was the fix for that bug.

> The problem is that "in the middle of a sexp" can mean different
> things.  Which sexp?

As the doc string now says: that which is to be transposed.

IOW, when the user invokes this command, she wants it to transpose two
specific sexps.  These are the sexps the doc string alludes to.

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

[Drew Adams]

> > It is really not great to tell someone they "cannot" or
> > "must not" etc. do something without raising an error that
> > really enforces "cannot" etc.
> 
> If someone comes up with a way to lift that restriction, we could
> remove this text from the doc string.  but as long as the command
> works as it does, I think we should document that, or else we will
> have bug reports about its not meeting expectations.

I did not suggest removing the text from the doc string.

The point is that it is better if the code backs up what
the doc says, by raising an error if you try to do what
it says you cannot do.

If `C-b' at bob did not raise an error, but instead just
moved point to the end of line 42, it would be scant help
to tell users in the doc of `C-b' that you cannot use it
at bob.