bug#14305: 23.4; doc string of `frame-visible-p'

bug#14305: 23.4; doc string of `frame-visible-p'

[Drew Adams]

This makes it sound like "iconified" is something different from
"minimized":
 
  Return the symbol `icon' if FRAME is iconified or "minimized".
 
To imply that minimized means the same thing as iconified, you need a
comma after "iconified" (or put "'minimized'" in parens):
 
  Return the symbol `icon' if FRAME is iconified, or minimized.
 
  Return the symbol `icon' if FRAME is iconified (minimized).
 
The second is clearer, not requiring readers to notice the comma and
recognize how it changes parsing of the sentence.
 
And you can remove the quotes around "visible", "minimized", and
"taskbar".

In GNU Emacs 23.4.1 (i386-mingw-nt5.1.2600)
 of 2012-02-04 on MARVIN
Windowing system distributor `Microsoft Corp.', version 5.1.2600
Configured using:
 `configure --with-gcc (4.4) --cflags
 -ID:/devel/emacs/libs/libXpm-3.5.8/include
 -ID:/devel/emacs/libs/libXpm-3.5.8/src
 -ID:/devel/emacs/libs/libpng-dev_1.4.3-1/include
 -ID:/devel/emacs/libs/zlib-dev_1.2.5-2/include
 -ID:/devel/emacs/libs/giflib-4.1.4-1/include
 -ID:/devel/emacs/libs/jpeg-6b-4/include
 -ID:/devel/emacs/libs/tiff-3.8.2-1/include'
 

bug#14305: 23.4; doc string of `frame-visible-p'

[Lars Ingebrigtsen]

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

> This makes it sound like "iconified" is something different from
> "minimized":
>
>   Return the symbol `icon' if FRAME is iconified or "minimized".
>
> To imply that minimized means the same thing as iconified, you need a
> comma after "iconified" (or put "'minimized'" in parens):
>
>   Return the symbol `icon' if FRAME is iconified, or minimized.
>
>   Return the symbol `icon' if FRAME is iconified (minimized).

Well, are they the same thing?  

> The second is clearer, not requiring readers to notice the comma and
> recognize how it changes parsing of the sentence.
>
> And you can remove the quotes around "visible", "minimized", and
> "taskbar".

Even if a frame is obscured by other frames (and is therefore not
visible), I think this function will still say that it is "visible".  So
I think the sneer quotes are correct here.  Closing.

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

bug#14305: 23.4; doc string of `frame-visible-p'

[Drew Adams]

> Well, are they the same thing?

You tell me.  What's the content of the message to users here?
If they are the same, then add commas or otherwise make that clear.
If not, and if it is important to mention both, then it becomes
important to say what each is (what the difference is).

> > The second is clearer, not requiring readers to notice the comma
> > and recognize how it changes parsing of the sentence.
> >
> > And you can remove the quotes around "visible", "minimized", and
> > "taskbar".
> 
> Even if a frame is obscured by other frames (and is therefore not
> visible), I think this function will still say that it is "visible".
> So I think the sneer quotes are correct here. 

You might have a point there for "visible", but not for the other
two, AFAICT.  On some platforms a frame might be iconified on the
desktop, and the icon thus hidden by another frame.  But on other
platforms the icons are in a task bar or whatever, not covered by
another frame.  And I see no reason whatsover for quotes, sneer
or otherwise, around "taskbar".

> Closing.

Fixing is what should be done.