* bug#41727: 26.3; Doc of `define-minor-mode' and minor-mode commands [not found] ` <<838sh081lt.fsf@gnu.org> @ 2020-06-06 20:39 ` Drew Adams 0 siblings, 0 replies; 25+ messages in thread From: Drew Adams @ 2020-06-06 20:39 UTC (permalink / raw) To: Eli Zaretskii, Drew Adams; +Cc: 41727 > My point was that you take the text out of its context, and that > context spells out what you say is missing. No, it does not. It does not at all say what I say is missing from the description of the Lisp-call behavior. > This is not the first time you raise this issue, and the argument > always goes the same way. I wish you'd stopped these repeated > complaints about the same thing. I've never made such a "complaint" before. Please point to one such, if you think doing so really adds value here. Or is your effort only to argue ad hominem, as if I'm doing something bad, and have done it "repeated"ly? How about addressing the actual bug report? You tell me how the existing text (cited by both you and me) correctly and completely describes the Lisp behavior. Passing symbol `-' isn't passing an integer, and so on. Now, if you just don't want to fix the text, that's another story. But I think you'll find it hard to argue that the report is mistaken and the text is accurate and complete. And I hope you realize that the handling of the arg to `define-minor-mode' has been the subject of a fair amount of confusion. There have been several attempts to improve the doc. But it's still not as clear and helpful as it should be. And the fix is simple: say the missing bits wrt the Lisp case. > > > Are you reading obsolete docs? > > > > I'm reading the 26.3 docs, as suggested by the report: > > The latest sources seem to be different. Different from what? I stated that what you wrote is exactly the text I was referring to, verbatim. You simply added the text about the interactive case. AFAICT, we're talking about exactly the same text, in the same release, 26.3. I wonder if you're actually reading what I wrote. The text you quote is exactly the text that suffers from the problem I raised. The text about the interactive case in no way helps describe the missing parts of the case for the Lisp behavior. ^ permalink raw reply [flat|nested] 25+ messages in thread
* bug#41727: 26.3; Doc of `define-minor-mode' and minor-mode commands @ 2020-06-05 20:39 Drew Adams 2020-06-06 0:01 ` Drew Adams 2020-06-06 6:13 ` Eli Zaretskii 0 siblings, 2 replies; 25+ messages in thread From: Drew Adams @ 2020-06-05 20:39 UTC (permalink / raw) To: 41727 The doc needs improvement when describing calling the mode from Lisp. 1. The doc string of `define-minor-mode' says this: When called from Lisp, the mode command toggles the mode if the argument is `toggle', disables the mode if the argument is a non-positive integer, and enables the mode otherwise (including if the argument is omitted or nil or a positive integer). This is wrong (incomplete). It disables the mode if the `prefix-numeric-value' of ARG <= 0, not if ARG is a non-positive integer. The code does this: (prefix-numeric-value arg). So if you pass the symbol `-' as ARG then the mode is disabled. 1. The (default) doc string produced by `define-minor-mode' says this: If called from Lisp, enable the mode if ARG is omitted or nil, and toggle it if ARG is `toggle'. Again, this is wrong (incomplete). It doesn't say that if ARG is non-nil other than `toggle' then disable the mode if the `prefix-numeric-value' of ARG <= 0, and enable it if the `prefix-numeric-value' of ARG > 0. 3. The Elisp manual doc says this (node `Defining Minor Modes'): From Lisp, an argument of 'toggle' toggles the mode, whereas an omitted or 'nil' argument enables the mode. Again, this is wrong (incomplete). * It says nothing about how the mode is disabled when called from Lisp. It should say that an ARG whose `prefix-numeric-value' is non-positive disables the mode. * It should say that an ARG whose `prefix-numeric-value' is non-positive enables the mode. In GNU Emacs 26.3 (build 1, x86_64-w64-mingw32) of 2019-08-29 Repository revision: 96dd0196c28bc36779584e47fffcca433c9309cd Windowing system distributor `Microsoft Corp.', version 10.0.18362 Configured using: `configure --without-dbus --host=x86_64-w64-mingw32 --without-compress-install 'CFLAGS=-O2 -static -g3'' ^ permalink raw reply [flat|nested] 25+ messages in thread
* bug#41727: 26.3; Doc of `define-minor-mode' and minor-mode commands 2020-06-05 20:39 Drew Adams @ 2020-06-06 0:01 ` Drew Adams 2020-06-07 10:04 ` Michael Heerdegen 2020-06-06 6:13 ` Eli Zaretskii 1 sibling, 1 reply; 25+ messages in thread From: Drew Adams @ 2020-06-06 0:01 UTC (permalink / raw) To: 41727 For the (default) doc string of a minor mode, I think something like this should take care of it. Interactively, toggle the mode. But with a prefix arg, enable the mode if the numeric value is positive, and disable it otherwise. If called from Lisp, toggle the mode if the optional arg is 'toggle'. Otherwise, handle it as the prefix arg: disable the mode if `prefix-numeric-value' of the arg is non-positive, and enable it otherwise. This implies that if the arg is nil or absent then enable the mode. ___ Ideally, we would have a way to provide a custom doc string that also included this info somehow. Maybe the doc string of `define-minor-mode' could show the default doc string and suggest that if you provide your own doc string you include the same or similar information, if appropriate. (And it might generally be good if the Lisp info were at the end of the doc string.) ^ permalink raw reply [flat|nested] 25+ messages in thread
* bug#41727: 26.3; Doc of `define-minor-mode' and minor-mode commands 2020-06-06 0:01 ` Drew Adams @ 2020-06-07 10:04 ` Michael Heerdegen 2020-06-07 16:06 ` Drew Adams 0 siblings, 1 reply; 25+ messages in thread From: Michael Heerdegen @ 2020-06-07 10:04 UTC (permalink / raw) To: Drew Adams; +Cc: 41727 Drew Adams <drew.adams@oracle.com> writes: > Ideally, we would have a way to provide a custom doc > string that also included this info somehow. Are you aware of `easy-mmode--arg-docstring'? Michael. ^ permalink raw reply [flat|nested] 25+ messages in thread
* bug#41727: 26.3; Doc of `define-minor-mode' and minor-mode commands 2020-06-07 10:04 ` Michael Heerdegen @ 2020-06-07 16:06 ` Drew Adams 2020-06-07 16:19 ` Michael Heerdegen 0 siblings, 1 reply; 25+ messages in thread From: Drew Adams @ 2020-06-07 16:06 UTC (permalink / raw) To: Michael Heerdegen; +Cc: 41727 > > Ideally, we would have a way to provide a custom doc > > string that also included this info somehow. > > Are you aware of `easy-mmode--arg-docstring'? No. I've never looked at (or heard of) `easy-mmode'. Thanks. But now that I look at it, in Emacs 26.3, I see no `easy-mmode--arg-docstring'. What am I missing? (BTW, easy-mmode.el uses both "docstring" and "doc-string" as a noun in its doc. Emacs should pick one or the other. IMHO, it should really probably pick "doc string", whatever it picks it should use pretty much everywhere.) ^ permalink raw reply [flat|nested] 25+ messages in thread
* bug#41727: 26.3; Doc of `define-minor-mode' and minor-mode commands 2020-06-07 16:06 ` Drew Adams @ 2020-06-07 16:19 ` Michael Heerdegen 2020-06-07 16:30 ` Drew Adams 0 siblings, 1 reply; 25+ messages in thread From: Michael Heerdegen @ 2020-06-07 16:19 UTC (permalink / raw) To: Drew Adams; +Cc: 41727 Drew Adams <drew.adams@oracle.com> writes: > > Are you aware of `easy-mmode--arg-docstring'? > > No. I've never looked at (or heard of) `easy-mmode'. Isn't `define-minor-mode' defined in "easy-mmode.el"? > But now that I look at it, in Emacs 26.3, I see > no `easy-mmode--arg-docstring'. What am I missing? I guess that's one version to small. It had been introduced when discussing Bug#10754. I can send you current master's version of the file offlist if you want. AFAIU it's the variable you asked for. Michael. ^ permalink raw reply [flat|nested] 25+ messages in thread
* bug#41727: 26.3; Doc of `define-minor-mode' and minor-mode commands 2020-06-07 16:19 ` Michael Heerdegen @ 2020-06-07 16:30 ` Drew Adams 0 siblings, 0 replies; 25+ messages in thread From: Drew Adams @ 2020-06-07 16:30 UTC (permalink / raw) To: Michael Heerdegen; +Cc: 41727 > > > Are you aware of `easy-mmode--arg-docstring'? > > > > No. I've never looked at (or heard of) `easy-mmode'. > > Isn't `define-minor-mode' defined in "easy-mmode.el"? Yes. I guess I meant that I haven't looked at much in that file. > > But now that I look at it, in Emacs 26.3, I see > > no `easy-mmode--arg-docstring'. What am I missing? > > I guess that's one version to small. It had been introduced when > discussing Bug#10754. I can send you current master's version of the > file offlist if you want. AFAIU it's the variable you asked for. I have the 27 pretest, so I have (at least some version) of `easy-mmode--arg-docstring'; thx. Yes, that's presumably what I suggest should be changed. And I guess where that Lisp info gets inserted could be reconsidered. This bug report suggests maybe putting it at the end of the doc string. Most calls of a minor-mode command will be interactive. And I'm arguing in favor of making the Lisp description of ARG more correct/complete. Perhaps, especially if that's done, it makes sense to relegate such info to the end. ^ permalink raw reply [flat|nested] 25+ messages in thread
* bug#41727: 26.3; Doc of `define-minor-mode' and minor-mode commands 2020-06-05 20:39 Drew Adams 2020-06-06 0:01 ` Drew Adams @ 2020-06-06 6:13 ` Eli Zaretskii 2020-06-06 16:45 ` Drew Adams 1 sibling, 1 reply; 25+ messages in thread From: Eli Zaretskii @ 2020-06-06 6:13 UTC (permalink / raw) To: Drew Adams; +Cc: 41727 > Date: Fri, 5 Jun 2020 13:39:27 -0700 (PDT) > From: Drew Adams <drew.adams@oracle.com> > > The doc needs improvement when describing calling the mode from Lisp. > > 1. The doc string of `define-minor-mode' says this: > > When called from Lisp, the mode command toggles the mode if the > argument is `toggle', disables the mode if the argument is a > non-positive integer, and enables the mode otherwise (including if > the argument is omitted or nil or a positive integer). It actually says this: Interactively with no prefix argument, it toggles the mode. A prefix argument enables the mode if the argument is positive, and disables it otherwise. When called from Lisp, the mode command toggles the mode if the argument is ‘toggle’, disables the mode if the argument is a non-positive integer, and enables the mode otherwise (including if the argument is omitted or nil or a positive integer). > 3. The Elisp manual doc says this (node `Defining Minor Modes'): > > From Lisp, an argument of 'toggle' toggles the mode, whereas an > omitted or 'nil' argument enables the mode. It actually says this: The toggle command takes one optional (prefix) argument. If called interactively with no argument it toggles the mode on or off. A positive prefix argument enables the mode, any other prefix argument disables it. From Lisp, an argument of ‘toggle’ toggles the mode, whereas an omitted or ‘nil’ argument enables the mode. Are you reading obsolete docs? ^ permalink raw reply [flat|nested] 25+ messages in thread
* bug#41727: 26.3; Doc of `define-minor-mode' and minor-mode commands 2020-06-06 6:13 ` Eli Zaretskii @ 2020-06-06 16:45 ` Drew Adams 2020-06-06 18:56 ` Eli Zaretskii 0 siblings, 1 reply; 25+ messages in thread From: Drew Adams @ 2020-06-06 16:45 UTC (permalink / raw) To: Eli Zaretskii; +Cc: 41727 > > The doc needs improvement when describing calling the mode from Lisp. > > > > 1. The doc string of `define-minor-mode' says this: > > > > When called from Lisp, the mode command toggles the mode if the > > argument is `toggle', disables the mode if the argument is a > > non-positive integer, and enables the mode otherwise (including if > > the argument is omitted or nil or a positive integer). > > It actually says this: > Interactively with no prefix argument, it toggles the mode. > A prefix argument enables the mode if the argument is positive, > and disables it otherwise. > > <snipped: verbatim quote of the text I cited about Lisp call> Yes, and? The point was about what the doc says about a call from Lisp. > > 3. The Elisp manual doc says this (node `Defining Minor Modes'): > > > > From Lisp, an argument of 'toggle' toggles the mode, whereas an > > omitted or 'nil' argument enables the mode. > > It actually says this: > The toggle command takes one optional (prefix) argument. If called > interactively with no argument it toggles the mode on or off. A > positive prefix argument enables the mode, any other prefix > argument disables it. > > <snipped: verbatim quote of the text I cited about Lisp call> Yes, and? The point was about what the doc says about a call from Lisp. The bug report doesn't find fault with the description of the interactive behavior. And my follow-up message suggests text for the doc string that I think is accurate and complete, and it improves the description of the interactive handling as well. The bug report is about the content/message/info, though, not the wording. If you don't like the wording of my suggestion, some other wording that provides as accurate and complete a description will be fine. Thx. > Are you reading obsolete docs? I'm reading the 26.3 docs, as suggested by the report: In GNU Emacs 26.3 (build 1, x86_64-w64-mingw32) of 2019-08-29 Repository revision: 96dd0196c28bc36779584e47fffcca433c9309cd Windowing system distributor `Microsoft Corp.', version 10.0.18362 Configured using: `configure --without-dbus --host=x86_64-w64-mingw32 --without-compress-install 'CFLAGS=-O2 -static -g3'' ^ permalink raw reply [flat|nested] 25+ messages in thread
* bug#41727: 26.3; Doc of `define-minor-mode' and minor-mode commands 2020-06-06 16:45 ` Drew Adams @ 2020-06-06 18:56 ` Eli Zaretskii 2020-06-07 10:08 ` Michael Heerdegen ` (2 more replies) 0 siblings, 3 replies; 25+ messages in thread From: Eli Zaretskii @ 2020-06-06 18:56 UTC (permalink / raw) To: Drew Adams; +Cc: 41727 > Date: Sat, 6 Jun 2020 09:45:46 -0700 (PDT) > From: Drew Adams <drew.adams@oracle.com> > Cc: 41727@debbugs.gnu.org > > > > The doc needs improvement when describing calling the mode from Lisp. > > > > > > 1. The doc string of `define-minor-mode' says this: > > > > > > When called from Lisp, the mode command toggles the mode if the > > > argument is `toggle', disables the mode if the argument is a > > > non-positive integer, and enables the mode otherwise (including if > > > the argument is omitted or nil or a positive integer). > > > > It actually says this: > > Interactively with no prefix argument, it toggles the mode. > > A prefix argument enables the mode if the argument is positive, > > and disables it otherwise. > > > > <snipped: verbatim quote of the text I cited about Lisp call> > > Yes, and? The point was about what the doc says about > a call from Lisp. My point was that you take the text out of its context, and that context spells out what you say is missing. This is not the first time you raise this issue, and the argument always goes the same way. I wish you'd stopped these repeated complaints about the same thing. > > Are you reading obsolete docs? > > I'm reading the 26.3 docs, as suggested by the report: The latest sources seem to be different. ^ permalink raw reply [flat|nested] 25+ messages in thread
* bug#41727: 26.3; Doc of `define-minor-mode' and minor-mode commands 2020-06-06 18:56 ` Eli Zaretskii @ 2020-06-07 10:08 ` Michael Heerdegen 2020-06-07 14:31 ` Eli Zaretskii 2020-06-07 16:08 ` Drew Adams [not found] ` <<87wo4jb33s.fsf@web.de> 2021-09-25 15:41 ` Stefan Kangas 2 siblings, 2 replies; 25+ messages in thread From: Michael Heerdegen @ 2020-06-07 10:08 UTC (permalink / raw) To: Eli Zaretskii; +Cc: 41727 Eli Zaretskii <eliz@gnu.org> writes: > My point was that you take the text out of its context, and that > context spells out what you say is missing. Just to be sure: you both speak about the sign of the ARG (current text) vs. the sign of (prefix-numeric-value ARG) (as Drew wants)? AFAIU Drew wants to mention that even in the noninteractive case `prefix-numeric-value' is called on the ARG before testing it. Michael. ^ permalink raw reply [flat|nested] 25+ messages in thread
* bug#41727: 26.3; Doc of `define-minor-mode' and minor-mode commands 2020-06-07 10:08 ` Michael Heerdegen @ 2020-06-07 14:31 ` Eli Zaretskii 2020-06-07 14:45 ` Michael Heerdegen 2020-06-07 16:08 ` Drew Adams 1 sibling, 1 reply; 25+ messages in thread From: Eli Zaretskii @ 2020-06-07 14:31 UTC (permalink / raw) To: Michael Heerdegen; +Cc: 41727 > From: Michael Heerdegen <michael_heerdegen@web.de> > Cc: Drew Adams <drew.adams@oracle.com>, 41727@debbugs.gnu.org > Date: Sun, 07 Jun 2020 12:08:07 +0200 > > AFAIU Drew wants to mention that even in the noninteractive case > `prefix-numeric-value' is called on the ARG before testing it. If that's the essence of the bug report (and I indeed didn't realize that), then I don't think it's a good idea to document this quirk. It looks like an implementation detail to me, if not an outright bug that should be fixed. ^ permalink raw reply [flat|nested] 25+ messages in thread
* bug#41727: 26.3; Doc of `define-minor-mode' and minor-mode commands 2020-06-07 14:31 ` Eli Zaretskii @ 2020-06-07 14:45 ` Michael Heerdegen 0 siblings, 0 replies; 25+ messages in thread From: Michael Heerdegen @ 2020-06-07 14:45 UTC (permalink / raw) To: Eli Zaretskii; +Cc: 41727 Eli Zaretskii <eliz@gnu.org> writes: > If that's the essence of the bug report (and I indeed didn't realize > that), then I don't think it's a good idea to document this quirk. It > looks like an implementation detail to me, if not an outright bug that > should be fixed. I'm undecided. It means at least that passing an unevaluated prefix arg to the function "works", which may matter in some cases. Michael. ^ permalink raw reply [flat|nested] 25+ messages in thread
* bug#41727: 26.3; Doc of `define-minor-mode' and minor-mode commands 2020-06-07 10:08 ` Michael Heerdegen 2020-06-07 14:31 ` Eli Zaretskii @ 2020-06-07 16:08 ` Drew Adams 1 sibling, 0 replies; 25+ messages in thread From: Drew Adams @ 2020-06-07 16:08 UTC (permalink / raw) To: Michael Heerdegen, Eli Zaretskii; +Cc: 41727 > > My point was that you take the text out of its context, and that > > context spells out what you say is missing. > > Just to be sure: you both speak about the sign of the ARG (current text) > vs. the sign of (prefix-numeric-value ARG) (as Drew wants)? AFAIU Drew > wants to mention that even in the noninteractive case > `prefix-numeric-value' is called on the ARG before testing it. Yes, it's the raw prefix arg (or equivalent) that's used, in all cases. And that's not necessarily an integer. And `prefix-numeric-value' is applied to that, to get the effective arg that's used. ^ permalink raw reply [flat|nested] 25+ messages in thread
[parent not found: <<87wo4jb33s.fsf@web.de>]
[parent not found: <<83y2oz6j6x.fsf@gnu.org>]
* bug#41727: 26.3; Doc of `define-minor-mode' and minor-mode commands [not found] ` <<83y2oz6j6x.fsf@gnu.org> @ 2020-06-07 16:16 ` Drew Adams 2020-06-08 17:16 ` Michael Heerdegen 0 siblings, 1 reply; 25+ messages in thread From: Drew Adams @ 2020-06-07 16:16 UTC (permalink / raw) To: Eli Zaretskii, Michael Heerdegen; +Cc: 41727 > > AFAIU Drew wants to mention that even in the noninteractive case > > `prefix-numeric-value' is called on the ARG before testing it. > > If that's the essence of the bug report (and I indeed didn't realize > that), then I don't think it's a good idea to document this quirk. It > looks like an implementation detail to me, if not an outright bug that > should be fixed. If you don't document it then users won't know how to use it correctly from Lisp (at least not without studying the code). That's misleading enough to make me wonder whether, in that case, it might be better to say nothing at all about the call-from-Lisp case, forcing Lisp users to consult the code. My preference is (obviously) to have the doc tell the whole story: accurate & complete. ^ permalink raw reply [flat|nested] 25+ messages in thread
* bug#41727: 26.3; Doc of `define-minor-mode' and minor-mode commands 2020-06-07 16:16 ` Drew Adams @ 2020-06-08 17:16 ` Michael Heerdegen 2020-06-08 17:38 ` Drew Adams 0 siblings, 1 reply; 25+ messages in thread From: Michael Heerdegen @ 2020-06-08 17:16 UTC (permalink / raw) To: Drew Adams; +Cc: 41727 Drew Adams <drew.adams@oracle.com> writes: > That's misleading enough to make me wonder whether, > in that case, it might be better to say nothing at > all about the call-from-Lisp case, forcing Lisp > users to consult the code. How about leaving only cases like ARG -> '- undocumented? When called from Lisp, the mode command toggles the mode if the argument is `toggle', disables the mode if the argument is a non-positive integer, and enables the mode if the argument is a positive integer or omitted or nil. Good enough for daily business. And we are lucky: since an additional `prefix-numeric-value' doesn't harm (it's idempotent), it's not a problem if it's called on the arg before passing it to the mode function and by the mode function again. Michael. ^ permalink raw reply [flat|nested] 25+ messages in thread
* bug#41727: 26.3; Doc of `define-minor-mode' and minor-mode commands 2020-06-08 17:16 ` Michael Heerdegen @ 2020-06-08 17:38 ` Drew Adams 2020-06-09 7:58 ` Michael Heerdegen [not found] ` <<87h7vkbrh3.fsf@web.de> 0 siblings, 2 replies; 25+ messages in thread From: Drew Adams @ 2020-06-08 17:38 UTC (permalink / raw) To: Michael Heerdegen; +Cc: 41727 > > That's misleading enough to make me wonder whether, > > in that case, it might be better to say nothing at > > all about the call-from-Lisp case, forcing Lisp > > users to consult the code. > > How about leaving only cases like ARG -> '- undocumented? > > When called from Lisp, the mode command toggles the mode if the argument > is `toggle', disables the mode if the argument is a non-positive > integer, and enables the mode if the argument is a positive integer or > omitted or nil. That's what we say now, and the reason I filed the bug. > Good enough for daily business. ... Not good enough for me. ;-) Consider a case where some command A invokes a minor-mode command B, to turn B on or off for some purpose/extent. Consider the case where A's prefix arg is passed to B, to do that. The programmer writing the Lisp code to define A should know that s?he can just pass the raw prefix arg. The resulting code will be simpler, easier to read, etc. I see no reason at all why we wouldn't provide an accurate (complete) description of what ARG is for Lisp use. What do we gain by not doing this right? ^ permalink raw reply [flat|nested] 25+ messages in thread
* bug#41727: 26.3; Doc of `define-minor-mode' and minor-mode commands 2020-06-08 17:38 ` Drew Adams @ 2020-06-09 7:58 ` Michael Heerdegen 2020-06-09 14:39 ` Eli Zaretskii 2020-06-09 15:40 ` Drew Adams [not found] ` <<87h7vkbrh3.fsf@web.de> 1 sibling, 2 replies; 25+ messages in thread From: Michael Heerdegen @ 2020-06-09 7:58 UTC (permalink / raw) To: Drew Adams; +Cc: 41727 Drew Adams <drew.adams@oracle.com> writes: > > How about leaving only cases like ARG -> '- undocumented? > > > > When called from Lisp, the mode command toggles the mode if the argument > > is `toggle', disables the mode if the argument is a non-positive > > integer, and enables the mode if the argument is a positive integer or > > omitted or nil. > > That's what we say now, and the reason I filed the bug. No, it's not, it doesn't contradict the implementation. Did you read carefully? > Consider a case where some command A invokes a minor-mode > command B, to turn B on or off for some purpose/extent. > Consider the case where A's prefix arg is passed to B, to > do that. > > The programmer writing the Lisp code to define A should > know that s?he can just pass the raw prefix arg. The > resulting code will be simpler, easier to read, etc. We don't know if the original author intended the semantics of the documentation or of the implementation. If we are sure the current implementation is what was intended I would be ok with documenting it, but it's really far from important IMHO. I leave it to Eli to decide. Michael. ^ permalink raw reply [flat|nested] 25+ messages in thread
* bug#41727: 26.3; Doc of `define-minor-mode' and minor-mode commands 2020-06-09 7:58 ` Michael Heerdegen @ 2020-06-09 14:39 ` Eli Zaretskii 2020-06-09 15:21 ` Michael Heerdegen 2020-06-09 15:40 ` Drew Adams 1 sibling, 1 reply; 25+ messages in thread From: Eli Zaretskii @ 2020-06-09 14:39 UTC (permalink / raw) To: Michael Heerdegen; +Cc: 41727 > From: Michael Heerdegen <michael_heerdegen@web.de> > Cc: Eli Zaretskii <eliz@gnu.org>, 41727@debbugs.gnu.org > Date: Tue, 09 Jun 2020 09:58:32 +0200 > > We don't know if the original author intended the semantics of the > documentation or of the implementation. If we are sure the current > implementation is what was intended I would be ok with documenting it, > but it's really far from important IMHO. > > I leave it to Eli to decide. I stated my opinion. Do we have other places where a function called from Lisp uses the prefix arg in any similar way? It seems bad practice to me: non-interactive calls shouldn't use interactive features. ^ permalink raw reply [flat|nested] 25+ messages in thread
* bug#41727: 26.3; Doc of `define-minor-mode' and minor-mode commands 2020-06-09 14:39 ` Eli Zaretskii @ 2020-06-09 15:21 ` Michael Heerdegen 0 siblings, 0 replies; 25+ messages in thread From: Michael Heerdegen @ 2020-06-09 15:21 UTC (permalink / raw) To: Eli Zaretskii; +Cc: 41727 Eli Zaretskii <eliz@gnu.org> writes: > Do we have other places where a function called from Lisp uses the > prefix arg in any similar way? Seems so, e.g. allout-kill-line, allout-yank-pop, dired-do-kill-lines, doc-view-scroll-up-or-next-page, doc-view-scroll-down-or-previous-page, follow-scroll-up-arg, .... there are lots of more examples. The feature we are discussing in this report is also already used, see `toggle-menu-bar-mode-from-frame' for an example. > It seems bad practice to me: non-interactive calls shouldn't use > interactive features. Dunno. OTOH, most commands using the prefix arg don't distinguish between interactive and noninteractive calls. Why should `define-minor-mode' describe the two cases separately? Michael. ^ permalink raw reply [flat|nested] 25+ messages in thread
* bug#41727: 26.3; Doc of `define-minor-mode' and minor-mode commands 2020-06-09 7:58 ` Michael Heerdegen 2020-06-09 14:39 ` Eli Zaretskii @ 2020-06-09 15:40 ` Drew Adams 1 sibling, 0 replies; 25+ messages in thread From: Drew Adams @ 2020-06-09 15:40 UTC (permalink / raw) To: Michael Heerdegen; +Cc: 41727 > > > How about leaving only cases like ARG -> '- undocumented? > > > > > > When called from Lisp, the mode command toggles the mode if the > > > argument is `toggle', disables the mode if the argument is a > > > non-positive integer, and enables the mode if the argument is a > > > positive integer or omitted or nil. > > > > That's what we say now, and the reason I filed the bug. > > No, it's not, it doesn't contradict the implementation. Did you read > carefully? I think I did. We don't use exactly the same words, but I think we do say just that. When called from Lisp, the mode command toggles the mode if the argument is `toggle', Verbatim the same. disables the mode if the argument is a non-positive integer, Verbatim the same. and enables the mode otherwise (including if the argument is omitted or nil or a positive integer). OK, your text doesn't say "otherwise". Your text is less exact, since the "otherwise" is correct - omitted/nil and positive integer constitute a subset of what's true. Is that really your suggestion, to not document that something other than omitted, nil and a positive integer enables the mode? To me, that would be a step backward, not forward. That doesn't correspond to what the code does. > > Consider a case where some command A invokes a minor-mode > > command B, to turn B on or off for some purpose/extent. > > Consider the case where A's prefix arg is passed to B, to > > do that. > > > > The programmer writing the Lisp code to define A should > > know that s?he can just pass the raw prefix arg. The > > resulting code will be simpler, easier to read, etc. > > We don't know if the original author intended the semantics of the > documentation or of the implementation. If we are sure the current > implementation is what was intended I would be ok with documenting it, > but it's really far from important IMHO. Until the code is changed, e.g. because someone thinks the behavior is wrong, the doc should reflect it. I, for one, think the behavior is OK as is. The use case I just gave (cited above) is one argument for it. Many commands have the `interactive' form massage the prefix arg, to present something a bit different to the body. E.g., a change from raw to numeric prefix value is done in the `interactive' form, for whatever reason. This command doesn't work that way. Instead, what is passed to Lisp is the raw prefix arg, and it is the body (which also corresponds to a non-interactive call) that converts that to a numeric value. Someone (and `d-m-mode' has been worked over more than once wrt its interactive-vs-Lisp behavior, I believe) presumably deliberately decided that this command should act differently. Many commands (most, I think) make it so that the body gets just what it needs, and any compensation for interactivity is taken care of only in the `interactive' spec. Someone presumably thought this command should be an exception in that regard. Until someone decides otherwise, and changes the behavior (which I doubt will happen, in particular because of backward incompatibility), IMO it's the doc that needs to be changed to fit the behavior, not the other way around. I don't understand the hesitation to make the doc say just what the truth is. It doesn't take any more text. I already suggested wording, and I made clear that other wording that says the same thing (describes the behavior accurately) would be fine instead. What's the pushback, here? Why shouldn't we make the doc tell the real story wrt the ARG that Lisp expects? ^ permalink raw reply [flat|nested] 25+ messages in thread
[parent not found: <<87h7vkbrh3.fsf@web.de>]
[parent not found: <<835zc0717e.fsf@gnu.org>]
* bug#41727: 26.3; Doc of `define-minor-mode' and minor-mode commands [not found] ` <<835zc0717e.fsf@gnu.org> @ 2020-06-09 15:51 ` Drew Adams 0 siblings, 0 replies; 25+ messages in thread From: Drew Adams @ 2020-06-09 15:51 UTC (permalink / raw) To: Eli Zaretskii, Michael Heerdegen; +Cc: 41727 > Do we have other places where a function called from Lisp uses the > prefix arg in any similar way? It seems bad practice to me: > non-interactive calls shouldn't use interactive features. I actually agree with what you say there. I don't know why this was designed as an exception. But I think it was. There has been discussion over the years about the interactive vs Lisp behavior of `d-m-mode' and the confusion of users, and I think the behavior may even have changed over time. I think Stefan might know why this does what it does. I don't know why it does - but it does. Do you see the behavior changing to fit the more common model, as you suggest? If so, OK (but that will break some existing code out there). If you don't expect to fix the behavior, to no longer have the "bad practice" you cite, then, until we do fix it, (IMO) we should fix the doc to fit the behavior. ^ permalink raw reply [flat|nested] 25+ messages in thread
* bug#41727: 26.3; Doc of `define-minor-mode' and minor-mode commands 2020-06-06 18:56 ` Eli Zaretskii 2020-06-07 10:08 ` Michael Heerdegen [not found] ` <<87wo4jb33s.fsf@web.de> @ 2021-09-25 15:41 ` Stefan Kangas 2021-09-25 16:58 ` bug#41727: [External] : " Drew Adams 2 siblings, 1 reply; 25+ messages in thread From: Stefan Kangas @ 2021-09-25 15:41 UTC (permalink / raw) To: Eli Zaretskii; +Cc: 41727-done Eli Zaretskii <eliz@gnu.org> writes: >> Date: Sat, 6 Jun 2020 09:45:46 -0700 (PDT) >> From: Drew Adams <drew.adams@oracle.com> >> Cc: 41727@debbugs.gnu.org >> >> > > The doc needs improvement when describing calling the mode from Lisp. >> > > >> > > 1. The doc string of `define-minor-mode' says this: >> > > >> > > When called from Lisp, the mode command toggles the mode if the >> > > argument is `toggle', disables the mode if the argument is a >> > > non-positive integer, and enables the mode otherwise (including if >> > > the argument is omitted or nil or a positive integer). >> > >> > It actually says this: >> > Interactively with no prefix argument, it toggles the mode. >> > A prefix argument enables the mode if the argument is positive, >> > and disables it otherwise. >> > >> > <snipped: verbatim quote of the text I cited about Lisp call> >> >> Yes, and? The point was about what the doc says about >> a call from Lisp. > > My point was that you take the text out of its context, and that > context spells out what you say is missing. > > This is not the first time you raise this issue, and the argument > always goes the same way. I wish you'd stopped these repeated > complaints about the same thing. > >> > Are you reading obsolete docs? >> >> I'm reading the 26.3 docs, as suggested by the report: > > The latest sources seem to be different. This bug report is sprawling, and it is very hard to make heads or tails of what is being discussed. One initial issue is that the bug report was made against the text in 26.3, which has changed significantly on current master. In any case, Eli seems to be of the opinion that no further change is needed here. I tend to agree, and I'm therefore closing this bug report. If there are still any outstanding issues, please carefully review the text that we currently have on master and report any issues separately based on that. Otherwise, it will be very hard to make any progress. Thanks in advance. ^ permalink raw reply [flat|nested] 25+ messages in thread
* bug#41727: [External] : Re: bug#41727: 26.3; Doc of `define-minor-mode' and minor-mode commands 2021-09-25 15:41 ` Stefan Kangas @ 2021-09-25 16:58 ` Drew Adams 2021-09-25 17:18 ` Eli Zaretskii 0 siblings, 1 reply; 25+ messages in thread From: Drew Adams @ 2021-09-25 16:58 UTC (permalink / raw) To: Stefan Kangas, Eli Zaretskii; +Cc: 41727-done@debbugs.gnu.org > This bug report is sprawling, and it is very hard to make heads or > tails of what is being discussed. I don't think that's the case. Of course it takes time to read and understand a bug thread. > In any case, Eli seems to be of the opinion that > no further change is needed here. Eli was the one who said (and I agreed): Do we have other places where a function called from Lisp uses the prefix arg in any similar way? It seems bad practice to me: non-interactive calls shouldn't use interactive features. That's about the code behavior, not about the doc string. But especially given that unusual (per Eli) behavior, I think the doc string should make clear what the behavior is (for Lisp use). It's not the usual behavior for Lisp use. ^ permalink raw reply [flat|nested] 25+ messages in thread
* bug#41727: [External] : Re: bug#41727: 26.3; Doc of `define-minor-mode' and minor-mode commands 2021-09-25 16:58 ` bug#41727: [External] : " Drew Adams @ 2021-09-25 17:18 ` Eli Zaretskii 0 siblings, 0 replies; 25+ messages in thread From: Eli Zaretskii @ 2021-09-25 17:18 UTC (permalink / raw) To: Drew Adams; +Cc: stefan, 41727 > From: Drew Adams <drew.adams@oracle.com> > CC: "41727-done@debbugs.gnu.org" <41727-done@debbugs.gnu.org> > Date: Sat, 25 Sep 2021 16:58:33 +0000 > Accept-Language: en-US > > > This bug report is sprawling, and it is very hard to make heads or > > tails of what is being discussed. > > I don't think that's the case. Of course it takes > time to read and understand a bug thread. > > > In any case, Eli seems to be of the opinion that > > no further change is needed here. > > Eli was the one who said (and I agreed): > > Do we have other places where a function called > from Lisp uses the prefix arg in any similar way? > > It seems bad practice to me: non-interactive calls > shouldn't use interactive features. > > That's about the code behavior, not about the doc > string. Exactly. > But especially given that unusual (per Eli) > behavior, I think the doc string should make clear > what the behavior is (for Lisp use). No, that doesn't follow. Stefan is right: this bug should be closed. ^ permalink raw reply [flat|nested] 25+ messages in thread
end of thread, other threads:[~2021-09-25 17:18 UTC | newest] Thread overview: 25+ messages (download: mbox.gz follow: Atom feed -- links below jump to the message on this page -- [not found] <<963d4189-17dc-4f4e-9993-0335fa271e50@default> [not found] ` <<83k10kafha.fsf@gnu.org> [not found] ` <<9d7f8447-1c0b-46db-a40c-c1ed2a398c46@default> [not found] ` <<838sh081lt.fsf@gnu.org> 2020-06-06 20:39 ` bug#41727: 26.3; Doc of `define-minor-mode' and minor-mode commands Drew Adams 2020-06-05 20:39 Drew Adams 2020-06-06 0:01 ` Drew Adams 2020-06-07 10:04 ` Michael Heerdegen 2020-06-07 16:06 ` Drew Adams 2020-06-07 16:19 ` Michael Heerdegen 2020-06-07 16:30 ` Drew Adams 2020-06-06 6:13 ` Eli Zaretskii 2020-06-06 16:45 ` Drew Adams 2020-06-06 18:56 ` Eli Zaretskii 2020-06-07 10:08 ` Michael Heerdegen 2020-06-07 14:31 ` Eli Zaretskii 2020-06-07 14:45 ` Michael Heerdegen 2020-06-07 16:08 ` Drew Adams [not found] ` <<87wo4jb33s.fsf@web.de> [not found] ` <<83y2oz6j6x.fsf@gnu.org> 2020-06-07 16:16 ` Drew Adams 2020-06-08 17:16 ` Michael Heerdegen 2020-06-08 17:38 ` Drew Adams 2020-06-09 7:58 ` Michael Heerdegen 2020-06-09 14:39 ` Eli Zaretskii 2020-06-09 15:21 ` Michael Heerdegen 2020-06-09 15:40 ` Drew Adams [not found] ` <<87h7vkbrh3.fsf@web.de> [not found] ` <<835zc0717e.fsf@gnu.org> 2020-06-09 15:51 ` Drew Adams 2021-09-25 15:41 ` Stefan Kangas 2021-09-25 16:58 ` bug#41727: [External] : " Drew Adams 2021-09-25 17:18 ` Eli Zaretskii
Code repositories for project(s) associated with this external index https://git.savannah.gnu.org/cgit/emacs.git https://git.savannah.gnu.org/cgit/emacs/org-mode.git This is an external index of several public inboxes, see mirroring instructions on how to clone and mirror all data and code used by this external index.