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

[Drew Adams <drew.adams@oracle.com>]

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