* bug#19682: 25.0.50; `other-window' doc string should say that by default it selects win in same frame [not found] ` <<83iofur7aj.fsf@gnu.org> @ 2015-01-25 23:40 ` Drew Adams 2015-01-26 6:30 ` Eli Zaretskii 0 siblings, 1 reply; 9+ messages in thread From: Drew Adams @ 2015-01-25 23:40 UTC (permalink / raw) To: Eli Zaretskii; +Cc: 19682 > I don't see why this single details matters more than the others. That is apparently, the problem here - you don't see it. The answer to "Why?" is that this information is very useful and yet not obvious. This is the primary use case for the command - hence the chosen default behavior. A user looking for a command that cycles among all windows in the same frame will not necessarily understand, immediately upon reading `C-h f other-window', that that is what this command does. The only way for a user to discover that this is the case, by default, is to read through the relatively esoteric and much rarer use-case descriptions involving all of the following: 1. The `other-window' _window parameter_, something that is not even mentioned in the Emacs manual (and rightfully so). (It is of course mentioned in the Elisp manual, though you will find that even there (node `Window Parameters') nothing is really said about what that parameter is (!), what its possible values are, or how it is used - another doc bug, IMO. Nothing is really said in node `Window Parameters' about what window parameters are, AFAICT. The example of parameter `other-window' is typical here: All that is said about it in `Window Parameters' is that it "affects the execution of `other-window'" (really? how?). The xref'd node (`Cyclic Window Ordering') and this node just pass the ball back and forth without, either of them, actually explaining anything.) 2. The (even rarer) possibility that window parameter `other-window' can be a function. (Again, nothing is said here or in the Elisp manual about where or how that function is used.) 3. Non-option variable `ignore-window-parameters' (again, something (rightfully) not even mentioned in the Emacs manual). 4. Window parameter `no-other-window'. (Again,...) After trying to understand all of that, our poor reader finally gets to a reference to function `next-window' and its possible arguments. And after following that cross-reference and reading all about parameters ALL-FRAMES and MINIBUF she will (hopefully) finally grasp that command `other-window', by default, cycles among the windows of the selected frame. FWIW, the doc string from Emacs 20 was not deficient in this regard, so this but is in fact a (minor) regression. In Emacs 20, `C-h f other-window' tells you this: ,---- | other-window is an interactive built-in function. | | Select the ARG'th different window on this frame. ^^^^^^^^^^^^^ | All windows on current frame are arranged in a cyclic order. ^^^^^^^^^^^^^^^^ | This command selects the window ARG steps away in that order. | A negative ARG moves in the opposite order. If the optional | second argument ALL_FRAMES is non-nil, cycle through all frames. | | (other-window ARG &optional ALL-FRAMES) `---- That follows the usual (traditional) approach in Emacs: The first line tells you about the default behavior. It does not try to provide an overview of all possible behavior. And it is fine if later sentences then qualify that initial description, even contradicting it to some extent where it might oversimplify. Contrast that with the first sentence for Emacs 25: "Select another window in cyclic ordering of windows." That suggests that someone wanted the sentence to cover all, or nearly all, possible behaviors. The result is that, at least without some further statement about the default behavior, users learn less than they should about the most important thing to learn: the default behavior. --- But it seems clear that there is little sense in continuing the dialog. I don't think I can say anything more than I have to persuade you, and you have apparently made up your mind not to see further. Thank you for anyway taking the time to think about it. I know that you, too, are busy with other, and more important, things. ^ permalink raw reply [flat|nested] 9+ messages in thread
* bug#19682: 25.0.50; `other-window' doc string should say that by default it selects win in same frame 2015-01-25 23:40 ` bug#19682: 25.0.50; `other-window' doc string should say that by default it selects win in same frame Drew Adams @ 2015-01-26 6:30 ` Eli Zaretskii 0 siblings, 0 replies; 9+ messages in thread From: Eli Zaretskii @ 2015-01-26 6:30 UTC (permalink / raw) To: Drew Adams; +Cc: 19682 > Date: Sun, 25 Jan 2015 15:40:08 -0800 (PST) > From: Drew Adams <drew.adams@oracle.com> > Cc: 19682@debbugs.gnu.org > > > I don't see why this single details matters more than the others. > > That is apparently, the problem here - you don't see it. > > The answer to "Why?" is that this information is very useful and > yet not obvious. It's not obvious, I agree. But I don't think it's very useful, except in very specific and IMO quite rare situations. > A user looking for a command that cycles among all windows in > the same frame will not necessarily understand, immediately upon > reading `C-h f other-window', that that is what this command does. If she doesn't care, she doesn't need to understand. If she does, there are enough hints in the doc string to suggest that reading the doc string of next-window will explain those details. > After trying to understand all of that, our poor reader finally > gets to a reference to function `next-window' and its possible > arguments. Nothing wrong with that. And possibly, an inquisitive enough reader will discover that even earlier, perhaps much earlier. ^ permalink raw reply [flat|nested] 9+ messages in thread
[parent not found: <<c78c5328-c0eb-4b91-afa1-2dbae2d03280@default>]
[parent not found: <<83ppa2rbta.fsf@gnu.org>]
* bug#19682: 25.0.50; `other-window' doc string should say that by default it selects win in same frame [not found] ` <<83ppa2rbta.fsf@gnu.org> @ 2015-01-25 19:05 ` Drew Adams 2015-01-25 19:26 ` Eli Zaretskii 0 siblings, 1 reply; 9+ messages in thread From: Drew Adams @ 2015-01-25 19:05 UTC (permalink / raw) To: Eli Zaretskii, Drew Adams; +Cc: 19682 > > But the first thing that needs to be said, very clearly, and > > preferably without any reference to arguments or other doc > > strings, is what the default behavior is. > > It already does. It just doesn't divulge _all_ the details about the > selection of the "other" window. No, it does not say what the default behavior is. It does not tell you that, by default, it switches to another window in the same frame. That's all that is missing. If you don't want to say that, so be it. I am not asking for a description of "_all_ the details about the selection of the "other" window." I am asking that you say what the other window is by default. Just the information that it is in the same frame is sufficient here. Beyond that, referring to `next-window' for details (including, e.g., which window in the same frame) is fine. ^ permalink raw reply [flat|nested] 9+ messages in thread
* bug#19682: 25.0.50; `other-window' doc string should say that by default it selects win in same frame 2015-01-25 19:05 ` Drew Adams @ 2015-01-25 19:26 ` Eli Zaretskii 0 siblings, 0 replies; 9+ messages in thread From: Eli Zaretskii @ 2015-01-25 19:26 UTC (permalink / raw) To: Drew Adams; +Cc: 19682 > Date: Sun, 25 Jan 2015 11:05:00 -0800 (PST) > From: Drew Adams <drew.adams@oracle.com> > Cc: 19682@debbugs.gnu.org > > > > But the first thing that needs to be said, very clearly, and > > > preferably without any reference to arguments or other doc > > > strings, is what the default behavior is. > > > > It already does. It just doesn't divulge _all_ the details about the > > selection of the "other" window. > > No, it does not say what the default behavior is. It does not > tell you that, by default, it switches to another window in > the same frame. It also doesn't say how that window gets selected, out of all the other windows on that frame. Readers who need those details are invited to read about 'next-window', because that's the window they will get. > I am not asking for a description of "_all_ the details about the > selection of the "other" window." > > I am asking that you say what the other window is by default. I don't see why this single details matters more than the others. ^ permalink raw reply [flat|nested] 9+ messages in thread
[parent not found: <<733fcda9-19ad-4096-aa8a-7f0f47062ac2@default>]
[parent not found: <<83y4oqrgkv.fsf@gnu.org>]
* bug#19682: 25.0.50; `other-window' doc string should say that by default it selects win in same frame [not found] ` <<83y4oqrgkv.fsf@gnu.org> @ 2015-01-25 17:12 ` Drew Adams 2015-01-25 17:48 ` Eli Zaretskii 0 siblings, 1 reply; 9+ messages in thread From: Drew Adams @ 2015-01-25 17:12 UTC (permalink / raw) To: Eli Zaretskii; +Cc: 19682 > > The doc string does not describe the default behavior: select another > > window in the same frame, if there is one. > > > > The doc string refers to the doc for `next-window', for the reader to > > find out what ALL-FRAMES does - even for the default, nil, case. > > > > It is fine to refer to `next-window' for ALL-FRAMES (e.g. for full > > understanding and for non-interactive use). But surely the default > > interactive behavior should be described. > > The doc string says: > > This function uses `next-window' for finding the window to > select. The argument ALL-FRAMES has the same meaning as in > `next-window', but the MINIBUF argument of `next-window' is > always effectively nil. > > This is a very clear invitation to read the documentation of > 'next-window', if the reader cares about which window will be > selected. If the reader indeed goes there, she will find there the > details of what you wanted her to know. > > OTOH, many uses of 'other-window' don't really care about the order > and the candidates, in which case that argument is of no importance > for them. > > So I see no reason to think this doc strings lacks something > important. The default interactive behavior should be described clearly, as the first thing in the doc string. Users, especially Lisp users, can read further to discover more information about possible argument values and behavior. But the first thing that needs to be said, very clearly, and preferably without any reference to arguments or other doc strings, is what the default behavior is. It is simple to make this immediately clear to users, and we should do so. ^ permalink raw reply [flat|nested] 9+ messages in thread
* bug#19682: 25.0.50; `other-window' doc string should say that by default it selects win in same frame 2015-01-25 17:12 ` Drew Adams @ 2015-01-25 17:48 ` Eli Zaretskii 2016-04-30 16:44 ` Lars Ingebrigtsen 0 siblings, 1 reply; 9+ messages in thread From: Eli Zaretskii @ 2015-01-25 17:48 UTC (permalink / raw) To: Drew Adams; +Cc: 19682 > Date: Sun, 25 Jan 2015 09:12:23 -0800 (PST) > From: Drew Adams <drew.adams@oracle.com> > Cc: 19682@debbugs.gnu.org > > > The doc string says: > > > > This function uses `next-window' for finding the window to > > select. The argument ALL-FRAMES has the same meaning as in > > `next-window', but the MINIBUF argument of `next-window' is > > always effectively nil. > > > > This is a very clear invitation to read the documentation of > > 'next-window', if the reader cares about which window will be > > selected. If the reader indeed goes there, she will find there the > > details of what you wanted her to know. > > > > OTOH, many uses of 'other-window' don't really care about the order > > and the candidates, in which case that argument is of no importance > > for them. > > > > So I see no reason to think this doc strings lacks something > > important. > > The default interactive behavior should be described clearly, > as the first thing in the doc string. Users, especially Lisp > users, can read further to discover more information about > possible argument values and behavior. We are in violent agreement about this. It's just that I think the current doc string does precisely that. > But the first thing that needs to be said, very clearly, and > preferably without any reference to arguments or other doc > strings, is what the default behavior is. It already does. It just doesn't divulge _all_ the details about the selection of the "other" window. ^ permalink raw reply [flat|nested] 9+ messages in thread
* bug#19682: 25.0.50; `other-window' doc string should say that by default it selects win in same frame 2015-01-25 17:48 ` Eli Zaretskii @ 2016-04-30 16:44 ` Lars Ingebrigtsen 0 siblings, 0 replies; 9+ messages in thread From: Lars Ingebrigtsen @ 2016-04-30 16:44 UTC (permalink / raw) To: Eli Zaretskii; +Cc: 19682 Eli Zaretskii <eliz@gnu.org> writes: >> The default interactive behavior should be described clearly, >> as the first thing in the doc string. Users, especially Lisp >> users, can read further to discover more information about >> possible argument values and behavior. > > We are in violent agreement about this. It's just that I think the > current doc string does precisely that. Me too. Closing. -- (domestic pets only, the antidote for overdose, milk.) bloggy blog: http://lars.ingebrigtsen.no ^ permalink raw reply [flat|nested] 9+ messages in thread
* bug#19682: 25.0.50; `other-window' doc string should say that by default it selects win in same frame @ 2015-01-25 3:33 Drew Adams 2015-01-25 16:05 ` Eli Zaretskii 0 siblings, 1 reply; 9+ messages in thread From: Drew Adams @ 2015-01-25 3:33 UTC (permalink / raw) To: 19682 The doc string does not describe the default behavior: select another window in the same frame, if there is one. The doc string refers to the doc for `next-window', for the reader to find out what ALL-FRAMES does - even for the default, nil, case. It is fine to refer to `next-window' for ALL-FRAMES (e.g. for full understanding and for non-interactive use). But surely the default interactive behavior should be described. In GNU Emacs 25.0.50.1 (i686-pc-mingw32) of 2014-10-20 on LEG570 Bzr revision: 118168 rgm@gnu.org-20141020195941-icp42t8ttcnud09g Windowing system distributor `Microsoft Corp.', version 6.1.7601 Configured using: `configure --enable-checking=yes,glyphs CPPFLAGS=-DGLYPH_DEBUG=1' ^ permalink raw reply [flat|nested] 9+ messages in thread
* bug#19682: 25.0.50; `other-window' doc string should say that by default it selects win in same frame 2015-01-25 3:33 Drew Adams @ 2015-01-25 16:05 ` Eli Zaretskii 0 siblings, 0 replies; 9+ messages in thread From: Eli Zaretskii @ 2015-01-25 16:05 UTC (permalink / raw) To: Drew Adams; +Cc: 19682 > Date: Sat, 24 Jan 2015 19:33:46 -0800 (PST) > From: Drew Adams <drew.adams@oracle.com> > > The doc string does not describe the default behavior: select another > window in the same frame, if there is one. > > The doc string refers to the doc for `next-window', for the reader to > find out what ALL-FRAMES does - even for the default, nil, case. > > It is fine to refer to `next-window' for ALL-FRAMES (e.g. for full > understanding and for non-interactive use). But surely the default > interactive behavior should be described. The doc string says: This function uses `next-window' for finding the window to select. The argument ALL-FRAMES has the same meaning as in `next-window', but the MINIBUF argument of `next-window' is always effectively nil. This is a very clear invitation to read the documentation of 'next-window', if the reader cares about which window will be selected. If the reader indeed goes there, she will find there the details of what you wanted her to know. OTOH, many uses of 'other-window' don't really care about the order and the candidates, in which case that argument is of no importance for them. So I see no reason to think this doc strings lacks something important. ^ permalink raw reply [flat|nested] 9+ messages in thread
end of thread, other threads:[~2016-04-30 16:44 UTC | newest] Thread overview: 9+ messages (download: mbox.gz follow: Atom feed -- links below jump to the message on this page -- [not found] <<b0accd37-8912-4873-ad3c-2816b55cdaaa@default> [not found] ` <<83iofur7aj.fsf@gnu.org> 2015-01-25 23:40 ` bug#19682: 25.0.50; `other-window' doc string should say that by default it selects win in same frame Drew Adams 2015-01-26 6:30 ` Eli Zaretskii [not found] <<c78c5328-c0eb-4b91-afa1-2dbae2d03280@default> [not found] ` <<83ppa2rbta.fsf@gnu.org> 2015-01-25 19:05 ` Drew Adams 2015-01-25 19:26 ` Eli Zaretskii [not found] <<733fcda9-19ad-4096-aa8a-7f0f47062ac2@default> [not found] ` <<83y4oqrgkv.fsf@gnu.org> 2015-01-25 17:12 ` Drew Adams 2015-01-25 17:48 ` Eli Zaretskii 2016-04-30 16:44 ` Lars Ingebrigtsen 2015-01-25 3:33 Drew Adams 2015-01-25 16:05 ` 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).