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

["Drew Adams" <drew.adams@oracle.com>]

> > In any case, please make clear here just what is meant by a 
> > "defined color" in this context
> 
> This is already part of the doc string:
>   Return non-nil if color COLOR is supported on frame FRAME.
>                           ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Now we're going around in circles.  That was precisely why I (mistakenly)
mentioned function `defined-colors'.  It says exactly the same thing for
parameter FRAME.  Yet the meanings of color support for FRAME are apparently
quite different for these two functions.  It is not obvious what a defined color
is in each case.

The explanation/definition cannot be circular or lead to contradictions or
ambiguity like that.  Please say what it means for a color to be defined for
`color-defined-p', without making a vague reference to the colors that are
"supported" on FRAME.

It is precisely what "support" means here that is in question.  And that support
differs, apparently, for different color-distinguishing functions.  So please
explain what color "support" means for this function - and separately for
function `defined-colors'.

The object is to bring MORE light, not less, on the matter.  Just what IS a
defined color for each of these functions?  Saying that it is whatever the
implementation sees is supported by FRAME is a complete copout, AFAICT.

> "Supported" means you can use COLOR in any context where a color is
> expected, and the display will show that color without signaling an
> error.

Does the display show COLOR even when it is `unspecified-bg'?  It's not at all
clear to me what these exceptions are about, or why & how "supported" for FRAME
differs between these two functions, each of whose name suggests that it
distinguishes defined colors from undefined colors and noncolor junk.

> > and how that definition relates to those particular noncolor
> > defined-color exceptions.
> 
> This would require to delve too deep into the internals, which might
> not be appropriate for a doc string.

In that case, something is wrong.  If we cannot tell programmers, in a
straightforward way, which strings are defined as colors for `color-defined-p'
and for `defined-colors', then we might as well call these functions `mystery-1'
and `mystery-2'.

Dunno what else to say about that.  You seem to be saying that we cannot say
what these functions do because their implementations are so complex that doing
so would send readers into the bowels of the code and its meaning.  That is
typically a good sign that something might be amiss.

> > IOW, if the meaning of "defined color" here were 
> > straightforward and we could simply point to some other
> > function (e.g. `defined-colors'), then doing that
> > would be appropriate and sufficient to make clear what that 
> > term means here.  Since the meaning is NOT obvious or
> > straightforward, it needs to be provided (explained).
> 
> I don't understand why you are looking for a definition,

Is this a joke?  Suppose I say, "Here is a predicate `foo-p'.  It returns
non-nil for a legitimate foo, and nil otherwise."  Do you have any idea what
`foo-p' does for the argument "abcde"?

Apparently, what a defined color is, which is exactly what this predicate
presumably tests/distinguishes (likewise `defined-colors', though apparently
with a different meaning), is a mystery and something quite out of the ordinary.

So yes, especially in that case it is important to say what we mean: just what
does each of these functions think a "defined color" is?

> beyond the simple one stated in the doc string, when the function
> we are talking about, color-defined-p, provides that definition:
>
> a "defined color" for the purposes of this function is something
> for which this function returns a non-nil value.

Well, I'm sorry to say that if that isn't a useless explanation then I don't
know what is.

Function `foo-p' distinguishes foos from non-foos.  What's a foo?  Whatever
`foo-p' returns non-nil for.  Well, sure, OK, but can't you give users an idea,
beyond that?  How could they possibly make use of `foo-p', without first testing
it on all possible inputs, to see what it really does?

I can hardly believe we're having this conversation.  Feel free to ignore or
close the bug, if it doesn't help.