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

[stepnem@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