bug#12853: 24.2.50; doc of `color-defined-p'

[Eli Zaretskii <eliz@gnu.org>]

> From: "Drew Adams" <drew.adams@oracle.com>
> Cc: <12853@debbugs.gnu.org>
> Date: Sat, 10 Nov 2012 10:12:34 -0800
> 
> However, I do not see either of those names returned by `defined-colors', which
> has the same handling of optional arg FRAME as `color-defined-p'.  Perhaps that
> function does include those two names sometimes, under some circumstances?
> Dunno - you tell me.

defined-colors will also report only the 8 or 16 colors defined
"natively" on a TTY, while color-defined-p will tell that, say,
"DarkSeaGreen" is also "defined".  Here, try this in "emacs -Q -nw":

  M-: (defined-colors) RET
   => ("black" "blue" "green" "cyan" "red" "magenta" "brown" "lightgray" "darkgray" "lightblue" "lightgreen" "lightcyan" "lightred" "lightmagenta" "yellow" "white")

But

  M-: (color-defined-p "DarkSeaGreen") RET
   => t

So these two functions do not support 1-to-1 correspondence of color
names, as you seem to assume.  That's because the purpose of these
functions is different: defined-colors only return the "basic" colors
supported by the current frame, while color-defined-p reports whether
the frame can _display_ a given color.

> If so, then the exceptional treatment of these two pseudo color names
> (recognized as colors sometimes, in some contexts) seems like an ugly kludge.

We need those pseudo-colors to express the unknown fore- and
back-ground colors used by TTY frames on displays that cannot report
what those default colors are.  It is a kludge to some extent, because
these colors obviously can be displayed, but having them return
non-nil from color-defined-p gets in the way.  This the note in the
doc string.

> In that case, please also mention in the doc that "defined color" is determined
> by function `defined-colors'

It isn't, see above.

> On the other hand, if `defined-colors' in fact always DTRT - never returns those
> noncolors, then the doc for `color-defined-p' should say just what I stated
> originally.

That would remove information that's important for someone who writes
code which manipulates color names at a low level where these
distinctions are important.  It was important for me when I did that,
and so I would object to removing this.