* RE: emacs-25 f708cb2: Clarify doc string of 'transpose-sexps' [not found] ` <<83oa1vjdrx.fsf@gnu.org> @ 2016-11-04 19:36 ` Drew Adams 0 siblings, 0 replies; 13+ messages in thread From: Drew Adams @ 2016-11-04 19:36 UTC (permalink / raw) To: Eli Zaretskii; +Cc: stephen.berman, emacs-devel > > 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. ^ permalink raw reply [flat|nested] 13+ messages in thread
[parent not found: <20161104095223.23249.72530@vcs.savannah.gnu.org>]
[parent not found: <20161104095223.631AB22012D@vcs.savannah.gnu.org>]
* Re: emacs-25 f708cb2: Clarify doc string of 'transpose-sexps' [not found] ` <20161104095223.631AB22012D@vcs.savannah.gnu.org> @ 2016-11-04 14:09 ` Stephen Berman 2016-11-04 14:31 ` Drew Adams 0 siblings, 1 reply; 13+ messages in thread From: Stephen Berman @ 2016-11-04 14:09 UTC (permalink / raw) To: emacs-devel; +Cc: Eli Zaretskii 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 ^ permalink raw reply [flat|nested] 13+ messages in thread
* RE: emacs-25 f708cb2: Clarify doc string of 'transpose-sexps' 2016-11-04 14:09 ` Stephen Berman @ 2016-11-04 14:31 ` Drew Adams 2016-11-04 15:47 ` Stephen Berman 2016-11-04 18:14 ` Eli Zaretskii 0 siblings, 2 replies; 13+ messages in thread From: Drew Adams @ 2016-11-04 14:31 UTC (permalink / raw) To: Stephen Berman, emacs-devel; +Cc: Eli Zaretskii > > +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. ^ permalink raw reply [flat|nested] 13+ messages in thread
* Re: emacs-25 f708cb2: Clarify doc string of 'transpose-sexps' 2016-11-04 14:31 ` Drew Adams @ 2016-11-04 15:47 ` Stephen Berman 2016-11-04 16:44 ` Drew Adams 2016-11-04 18:14 ` Eli Zaretskii 1 sibling, 1 reply; 13+ messages in thread From: Stephen Berman @ 2016-11-04 15:47 UTC (permalink / raw) To: Drew Adams; +Cc: Eli Zaretskii, emacs-devel 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 ^ permalink raw reply [flat|nested] 13+ messages in thread
* RE: emacs-25 f708cb2: Clarify doc string of 'transpose-sexps' 2016-11-04 15:47 ` Stephen Berman @ 2016-11-04 16:44 ` Drew Adams 2016-11-04 17:08 ` Stephen Berman 0 siblings, 1 reply; 13+ messages in thread From: Drew Adams @ 2016-11-04 16:44 UTC (permalink / raw) To: Stephen Berman; +Cc: Eli Zaretskii, emacs-devel > > 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". ^ permalink raw reply [flat|nested] 13+ messages in thread
* Re: emacs-25 f708cb2: Clarify doc string of 'transpose-sexps' 2016-11-04 16:44 ` Drew Adams @ 2016-11-04 17:08 ` Stephen Berman 2016-11-04 17:21 ` Drew Adams 0 siblings, 1 reply; 13+ messages in thread From: Stephen Berman @ 2016-11-04 17:08 UTC (permalink / raw) To: Drew Adams; +Cc: Eli Zaretskii, emacs-devel 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 ^ permalink raw reply [flat|nested] 13+ messages in thread
* RE: emacs-25 f708cb2: Clarify doc string of 'transpose-sexps' 2016-11-04 17:08 ` Stephen Berman @ 2016-11-04 17:21 ` Drew Adams 2016-11-04 17:50 ` Stephen Berman 2016-11-04 18:26 ` Eli Zaretskii 0 siblings, 2 replies; 13+ messages in thread From: Drew Adams @ 2016-11-04 17:21 UTC (permalink / raw) To: Stephen Berman; +Cc: Eli Zaretskii, emacs-devel > > 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). ^ permalink raw reply [flat|nested] 13+ messages in thread
* Re: emacs-25 f708cb2: Clarify doc string of 'transpose-sexps' 2016-11-04 17:21 ` Drew Adams @ 2016-11-04 17:50 ` Stephen Berman 2016-11-04 18:00 ` Drew Adams 2016-11-04 18:30 ` Eli Zaretskii 2016-11-04 18:26 ` Eli Zaretskii 1 sibling, 2 replies; 13+ messages in thread From: Stephen Berman @ 2016-11-04 17:50 UTC (permalink / raw) To: Drew Adams; +Cc: Eli Zaretskii, emacs-devel 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 ^ permalink raw reply [flat|nested] 13+ messages in thread
* RE: emacs-25 f708cb2: Clarify doc string of 'transpose-sexps' 2016-11-04 17:50 ` Stephen Berman @ 2016-11-04 18:00 ` Drew Adams 2016-11-04 18:33 ` Eli Zaretskii 2016-11-04 18:30 ` Eli Zaretskii 1 sibling, 1 reply; 13+ messages in thread From: Drew Adams @ 2016-11-04 18:00 UTC (permalink / raw) To: Stephen Berman; +Cc: Eli Zaretskii, emacs-devel > > 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.) ^ permalink raw reply [flat|nested] 13+ messages in thread
* Re: emacs-25 f708cb2: Clarify doc string of 'transpose-sexps' 2016-11-04 18:00 ` Drew Adams @ 2016-11-04 18:33 ` Eli Zaretskii 0 siblings, 0 replies; 13+ messages in thread From: Eli Zaretskii @ 2016-11-04 18:33 UTC (permalink / raw) To: Drew Adams; +Cc: stephen.berman, emacs-devel > 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. ^ permalink raw reply [flat|nested] 13+ messages in thread
* Re: emacs-25 f708cb2: Clarify doc string of 'transpose-sexps' 2016-11-04 17:50 ` Stephen Berman 2016-11-04 18:00 ` Drew Adams @ 2016-11-04 18:30 ` Eli Zaretskii 1 sibling, 0 replies; 13+ messages in thread From: Eli Zaretskii @ 2016-11-04 18:30 UTC (permalink / raw) To: Stephen Berman; +Cc: drew.adams, emacs-devel > 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. ^ permalink raw reply [flat|nested] 13+ messages in thread
* Re: emacs-25 f708cb2: Clarify doc string of 'transpose-sexps' 2016-11-04 17:21 ` Drew Adams 2016-11-04 17:50 ` Stephen Berman @ 2016-11-04 18:26 ` Eli Zaretskii 1 sibling, 0 replies; 13+ messages in thread From: Eli Zaretskii @ 2016-11-04 18:26 UTC (permalink / raw) To: Drew Adams; +Cc: stephen.berman, emacs-devel > 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. ^ permalink raw reply [flat|nested] 13+ messages in thread
* Re: emacs-25 f708cb2: Clarify doc string of 'transpose-sexps' 2016-11-04 14:31 ` Drew Adams 2016-11-04 15:47 ` Stephen Berman @ 2016-11-04 18:14 ` Eli Zaretskii 1 sibling, 0 replies; 13+ messages in thread From: Eli Zaretskii @ 2016-11-04 18:14 UTC (permalink / raw) To: Drew Adams; +Cc: stephen.berman, emacs-devel > 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. ^ permalink raw reply [flat|nested] 13+ messages in thread
end of thread, other threads:[~2016-11-04 19:36 UTC | newest] Thread overview: 13+ messages (download: mbox.gz follow: Atom feed -- links below jump to the message on this page -- [not found] <<20161104095223.23249.72530@vcs.savannah.gnu.org> [not found] ` <<20161104095223.631AB22012D@vcs.savannah.gnu.org> [not found] ` <<8737j7e3r5.fsf@gmx.net> [not found] ` <<ba4a000f-c63d-4fde-94b9-d493e895b7c7@default> [not found] ` <<87y40zckn9.fsf@gmx.net> [not found] ` <<977b7eaa-1c5f-4d8b-be5d-33ec73f5a962@default> [not found] ` <<87twbncgve.fsf@gmx.net> [not found] ` <<3687e9ab-658b-49b9-b766-8658d5c48374@default> [not found] ` <<87pombceyc.fsf@gmx.net> [not found] ` <<83cd67b5-cb42-4fea-b6be-21e9ec8075a7@default> [not found] ` <<83oa1vjdrx.fsf@gnu.org> 2016-11-04 19:36 ` emacs-25 f708cb2: Clarify doc string of 'transpose-sexps' Drew Adams [not found] <20161104095223.23249.72530@vcs.savannah.gnu.org> [not found] ` <20161104095223.631AB22012D@vcs.savannah.gnu.org> 2016-11-04 14:09 ` Stephen Berman 2016-11-04 14:31 ` Drew Adams 2016-11-04 15:47 ` Stephen Berman 2016-11-04 16:44 ` Drew Adams 2016-11-04 17:08 ` Stephen Berman 2016-11-04 17:21 ` Drew Adams 2016-11-04 17:50 ` Stephen Berman 2016-11-04 18:00 ` Drew Adams 2016-11-04 18:33 ` Eli Zaretskii 2016-11-04 18:30 ` Eli Zaretskii 2016-11-04 18:26 ` Eli Zaretskii 2016-11-04 18:14 ` Eli Zaretskii
Code repositories for project(s) associated with this public inbox https://git.savannah.gnu.org/cgit/emacs.git This is a public inbox, see mirroring instructions for how to clone and mirror all data and code used for this inbox; as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).