GNU bug report logs - #13339
24.3.50; doc of `next-frame'

Previous Next

To add a comment to this bug, you must first unarchive it, by sending
a message to control AT debbugs.gnu.org, with unarchive 13339 in the body.
You can then email your comments to 13339 AT debbugs.gnu.org in the normal way.

Toggle the display of automated, internal messages from the tracker.

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

From: "Drew Adams" <drew.adams <at> oracle.com>
To: <bug-gnu-emacs <at> gnu.org>
Subject: 24.3.50; doc of `next-frame'
Date: Wed, 2 Jan 2013 10:56:41 -0800

The doc (both doc string and Elisp manual) is unclear for the default
case where argument MINIFRAME/MINIBUF is nil.  (BTW, the same parameter
name should be used here for the doc string and the manual.)
 
What is unclear is which frames are _included_ in this case.  The only
thing we are told is that minibuffer-only frames are _excluded_.  Does
that mean that all other frames are included?  Or only visible frames?
Or only visible or iconified frames?
 
Other values of this argument make clear which frames are included, but
the doc for a nil value of the argument is incomplete.
 
In GNU Emacs 24.3.50.1 (i386-mingw-nt5.1.2600)
 of 2012-12-31 on ODIEONE
Bzr revision: 111388 rudalics <at> gmx.at-20121231113513-subz2dazg6yjukzh
Windowing system distributor `Microsoft Corp.', version 5.1.2600
Configured using:
 `configure --with-gcc (4.7) --no-opt --enable-checking --cflags
 -IC:/Devel/emacs/build/include --ldflags -LC:/Devel/emacs/build/lib'
 

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

From: "Drew Adams" <drew.adams <at> oracle.com>
To: <13339 <at> debbugs.gnu.org>
Subject: RE: bug#13339: 24.3.50; doc of `next-frame'
Date: Wed, 2 Jan 2013 11:02:06 -0800

BTW, the doc of `other-frame' says that it includes _visible_ frames.  And its
code calls `next-frame' with a nil value for argument MINIFRAME.  So if the doc
of `other-frame' is correct then the `next-frame' with nil MINIFRAME must
include only visible frames, not all frames except minibuffer-only frames and
not all visible or iconified frames except minibuffer-only frames.

If that is not correct then there is thus also a doc bug for `other-frame'.  If
it is correct then that should help you correct the doc for `next-frame'.

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

From: Lars Ingebrigtsen <larsi <at> gnus.org>
To: "Drew Adams" <drew.adams <at> oracle.com>
Cc: 13339 <at> debbugs.gnu.org
Subject: Re: bug#13339: 24.3.50; doc of `next-frame'
Date: Sat, 08 Feb 2014 05:20:05 -0800

"Drew Adams" <drew.adams <at> oracle.com> writes:

> The doc (both doc string and Elisp manual) is unclear for the default
> case where argument MINIFRAME/MINIBUF is nil.  (BTW, the same parameter
> name should be used here for the doc string and the manual.)
>
> What is unclear is which frames are _included_ in this case.  The only
> thing we are told is that minibuffer-only frames are _excluded_.  Does
> that mean that all other frames are included?  Or only visible frames?
> Or only visible or iconified frames?
>
> Other values of this argument make clear which frames are included, but
> the doc for a nil value of the argument is incomplete.

Uhm...  yeah...  clear.  >"?

Do you have a suggestion as to what the nil case should say?

-- 
(domestic pets only, the antidote for overdose, milk.)
  bloggy blog http://lars.ingebrigtsen.no/

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

From: Drew Adams <drew.adams <at> oracle.com>
To: Lars Ingebrigtsen <larsi <at> gnus.org>
Cc: 13339 <at> debbugs.gnu.org
Subject: RE: bug#13339: 24.3.50; doc of `next-frame'
Date: Mon, 10 Feb 2014 15:54:24 -0800 (PST)

> Do you have a suggestion as to what the nil case should say?

It seems like the frames included then would be all frames on the
same terminal, other than FRAME and any minibuffer-only frames.

But see my followup message, which points out that the doc of
`other-frame' seems to suggest something quite different: only
_visible_ frames (on the same terminal...).

Probably someone more knowledgable should check the behavior
and make the fix.

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

From: Lars Ingebrigtsen <larsi <at> gnus.org>
To: "Drew Adams" <drew.adams <at> oracle.com>
Cc: 13339 <at> debbugs.gnu.org
Subject: Re: bug#13339: 24.3.50; doc of `next-frame'
Date: Mon, 23 Aug 2021 16:32:03 +0200

"Drew Adams" <drew.adams <at> oracle.com> writes:

> What is unclear is which frames are _included_ in this case.  The only
> thing we are told is that minibuffer-only frames are _excluded_.  Does
> that mean that all other frames are included?  Or only visible frames?
> Or only visible or iconified frames?

Looking at the code, it's absolutely all frames on that terminal.  I've
now adjusted the doc string and the manual.

"Drew Adams" <drew.adams <at> oracle.com> writes:

> BTW, the doc of `other-frame' says that it includes _visible_ frames.
> And its code calls `next-frame' with a nil value for argument
> MINIFRAME.  So if the doc of `other-frame' is correct then the
> `next-frame' with nil MINIFRAME must include only visible frames, not
> all frames except minibuffer-only frames and not all visible or
> iconified frames except minibuffer-only frames.

I haven't dug into the code history here, but the code today says:

    (while (> arg 0)
      (setq frame (next-frame frame))
      (while (and (not (eq frame sframe))
                  (not (eq (frame-visible-p frame) t)))
	(setq frame (next-frame frame)))
      (setq arg (1- arg)))

So the doc string of `other-frame' is correct.

-- 
(domestic pets only, the antidote for overdose, milk.)
   bloggy blog: http://lars.ingebrigtsen.no

Previous Next

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