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

Previous Next

Full log

Message #26 received at 19682 <at> debbugs.gnu.org (full text, mbox):

From: Eli Zaretskii <eliz <at> gnu.org>
To: Drew Adams <drew.adams <at> oracle.com>
Cc: 19682 <at> debbugs.gnu.org
Subject: Re: bug#19682: 25.0.50;
 `other-window' doc string should say that by default it selects
 win	in same frame
Date: Mon, 26 Jan 2015 08:30:18 +0200

> Date: Sun, 25 Jan 2015 15:40:08 -0800 (PST)
> From: Drew Adams <drew.adams <at> oracle.com>
> Cc: 19682 <at> 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.

Previous Next

GNU bug tracking system
Copyright (C) 1999 Darren O. Benham, 1997,2003 nCipher Corporation Ltd, 1994-97 Ian Jackson.