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

From: Eli Zaretskii <[email-masked]>
Date: Mon, 26 Jan 2015 08:30:18 +0200

> Date: Sun, 25 Jan 2015 15:40:08 -0800 (PST)
> From: Drew Adams <[email-masked]>
> Cc: [email-masked]
> 
> > 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.