bug#4827: 23.1.50; frame-visible-p documentation

bug#4827: 23.1.50; frame-visible-p documentation

[stepnem]

[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 

bug#4827: marked as done (23.1.50; frame-visible-p documentation)

[Emacs bug Tracking System]

[-- Attachment #1: Type: text/plain, Size: 866 bytes --]

Your message dated Sat, 31 Oct 2009 13:15:17 -0400
with message-id <87vdhvfpsq.fsf@stupidchicken.com>
and subject line Re: 23.1.50; frame-visible-p documentation
has caused the Emacs bug report #4827,
regarding 23.1.50; frame-visible-p documentation
to be marked as done.

This means that you claim that the problem has been dealt with.
If this is not the case it is now your responsibility to reopen the
bug report if necessary, and/or fix the problem forthwith.

(NB: If you are a system administrator and have no idea what this
message is talking about, this may indicate a serious mail system
misconfiguration somewhere. Please contact owner@emacsbugs.donarmstrong.com
immediately.)


-- 
4827: http://emacsbugs.donarmstrong.com/cgi-bin/bugreport.cgi?bug=4827
Emacs Bug Tracking System
Contact owner@emacsbugs.donarmstrong.com with problems

[-- Attachment #2: Type: message/rfc822, Size: 4753 bytes --]

From: stepnem@gmail.com
To: bug-gnu-emacs@gnu.org
Subject: 23.1.50; frame-visible-p documentation
Date: Thu, 29 Oct 2009 14:41:00 +0100
Message-ID: <87639y2u8j.fsf@gmail.com>


[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 



[-- Attachment #3: Type: message/rfc822, Size: 1609 bytes --]

From: Chong Yidong <cyd@stupidchicken.com>
To: stepnem@gmail.com
Cc: 4827-done@emacsbugs.donarmstrong.com
Subject: Re: 23.1.50; frame-visible-p documentation
Date: Sat, 31 Oct 2009 13:15:17 -0400
Message-ID: <87vdhvfpsq.fsf@stupidchicken.com>

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.