bug#13339: 24.3.50; doc of `next-frame'

bug#13339: 24.3.50; doc of `next-frame'

[Drew Adams]

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@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'
 

bug#13339: 24.3.50; doc of `next-frame'

[Drew Adams]

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

bug#13339: 24.3.50; doc of `next-frame'

[Lars Ingebrigtsen]

"Drew Adams" <drew.adams@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/

bug#13339: 24.3.50; doc of `next-frame'

[Drew Adams]

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

bug#13339: 24.3.50; doc of `next-frame'

[Lars Ingebrigtsen]

"Drew Adams" <drew.adams@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@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