bug#19682: 25.0.50; `other-window' doc string should say that by default it selects win in same frame

bug#19682: 25.0.50; `other-window' doc string should say that by default it selects win in same frame

[Drew Adams]

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'

bug#19682: 25.0.50; `other-window' doc string should say that by default it selects win in same frame

[Eli Zaretskii]

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

bug#19682: 25.0.50; `other-window' doc string should say that by default it selects win in same frame

[Drew Adams]

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

bug#19682: 25.0.50; `other-window' doc string should say that by default it selects win in same frame

[Eli Zaretskii]

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

bug#19682: 25.0.50; `other-window' doc string should say that by default it selects win in same frame

[Lars Ingebrigtsen]

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

bug#19682: 25.0.50; `other-window' doc string should say that by default it selects win in same frame

[Drew Adams]

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

bug#19682: 25.0.50; `other-window' doc string should say that by default it selects win in same frame

[Eli Zaretskii]

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

bug#19682: 25.0.50; `other-window' doc string should say that by default it selects win in same frame

[Drew Adams]

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

bug#19682: 25.0.50; `other-window' doc string should say that by default it selects win in same frame

[Eli Zaretskii]

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