Subject: bug#4827 closed by Chong Yidong <[email-masked]> (Re: 23.1.50; frame-visible-p documentation)

From: [email-masked] (Emacs bug Tracking System)
Date: Sat, 31 Oct 2009 17:25:06 +0000

This is an automatic notification regarding your bug report
which was filed against the emacs package:

#4827: 23.1.50; frame-visible-p documentation

It has been closed by Chong Yidong <[email-masked]>.

Their explanation is attached below along with your original report.
If this explanation is unsatisfactory and you have not received a
better one in a separate message then please contact Chong Yidong <[email-masked]> by
replying to this email.

-- 
4827: http://debbugs.gnu.org/cgi/bugreport.cgi?bug=4827
Emacs Bug Tracking System
Contact [email-masked] with problems

Subject: Re: 23.1.50; frame-visible-p documentation
From: Chong Yidong <[email-masked]>
To: [email-masked]
Cc: [email-masked]
Date: Sat, 31 Oct 2009 13:15:17 -0400

I've updated the docstring of frame-visible-p to make it clearer.

> 3. What does being visible only as an icon mean?

Minimized.  This is Emacs terminology dating from long along.

Subject: 23.1.50; frame-visible-p documentation
From: [email-masked]
To: [email-masked]
Date: Thu, 29 Oct 2009 14:41:00 +0100

[In GNU Emacs 23.1.50.1 (i686-pc-linux-gnu, GTK+ Version 2.12.9)
 of 2009-10-28]

C-h f frame-visible-p:
"""
(frame-visible-p FRAME)

Return t if FRAME is now "visible" (actually in use for display).
A frame that is not "visible" is not updated and, if it works through
a window system, it may not show at all.
Return the symbol `icon' if frame is visible only as an icon.

On a text-only terminal, all frames are considered visible, whether
they are currently being displayed or not, and this function returns t
for all frames.

"""

Could please someone explain a few points mentioned below, and if
possible, fix the docstring to make them clear without further
explanation?

1. What does "if it works through a window system" mean? I assume "it"
means "frame", but is "a frame works through a window system" a good
formulation?

2. Why say "if it works through a window system, it may not show at all"?
If I understand correctly, on a text-only terminal, i.e. without "a
window system", there can be only one frame really visible at a time
(i.e. not "visible", but visible); and according to the second
paragraph, all frames are "visible", i.e. considered visible -- so why
"if ..., it may not show at all"?

3. What does being visible only as an icon mean?

The second paragraph is quite clear, although I really would like to
know why is there no distinction regarding "visibility" in a terminal or
what is the motivation for such behaviour (i.e. returning t for all
frames).

As a suggestion, wouldn't it at least make more sense to start the first
paragraph with 'Under a window system...' and get rid of that unclear
conditional mentioned under 1. and 2. above?

Regards

Štěpán Němec