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

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

[Drew Adams]

The doc string is missing the most basic information: What data type
parameter COLOR is.  It should say that COLOR must be a string or the
symbol `unspecified' (an error is raised otherwise).
 
It should say that the string can be any string, and that the function
returns non-nil for #1 or #2, and nil otherwise:
 
1. a defined (recognized) color name
2. a color RGB code, with prefix `#'
 
The doc should not say anything about the particular strings
"unspecified-fg" or "unspecified-bg": there is nothing special about
them.  The function returns nil for ANY string other than #1 or #2.
 
Consider adding to the doc string the "Note..." that is in the Elisp
manual and that refers to `color-supported-p'.
 
For the Elisp manual doc of `color-defined-p': change "X" to "X Window".  If the
same bug occurs elsewhere in the manual, please fix those occurrences too.

In GNU Emacs 24.2.50.1 (i386-mingw-nt5.1.2600)
 of 2012-10-22 on DANI-PC
Bzr revision: 110618 monnier@iro.umontreal.ca-20121022132928-232zm0fecassmhfb
Windowing system distributor `Microsoft Corp.', version 5.1.2600
Configured using:
 `configure --with-gcc (4.7) --no-opt --enable-checking --cflags
 -I../../libs/libxpm-3.5.8/include -I../../libs/libxpm-3.5.8/src
 -I../../libs/libpng-1.4.10 -I../../libs/zlib-1.2.6
 -I../../libs/giflib-4.1.4-1/include -I../../libs/jpeg-6b-4/include
 -I../../libs/tiff-3.8.2-1/include
 -I../../libs/libxml2-2.7.8-w32-bin/include/libxml2
 -I../../libs/gnutls-3.0.16/include
 -I../../libs/libiconv-1.14-2-mingw32-dev/include'
 

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

[Eli Zaretskii]

> From: "Drew Adams" <drew.adams@oracle.com>
> Date: Sat, 10 Nov 2012 08:46:24 -0800
> 
> It should say that the string can be any string, and that the function
> returns non-nil for #1 or #2, and nil otherwise:
>  
> 1. a defined (recognized) color name
> 2. a color RGB code, with prefix `#'
>  
> The doc should not say anything about the particular strings
> "unspecified-fg" or "unspecified-bg": there is nothing special about
> them.  The function returns nil for ANY string other than #1 or #2.

They _are_ special, because they are recognized color names.

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

[Drew Adams]

> > It should say that the string can be any string, and that 
> > the function returns non-nil for #1 or #2, and nil otherwise:
> >  
> > 1. a defined (recognized) color name
> > 2. a color RGB code, with prefix `#'
> >  
> > The doc should not say anything about the particular strings
> > "unspecified-fg" or "unspecified-bg": there is nothing special about
> > them.  The function returns nil for ANY string other than #1 or #2.
> 
> They _are_ special, because they are recognized color names.

Fine, then change #1 to "a defined color name other than `unspecified-fg' and
`unspecified-bg'".

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.

If so, then the exceptional treatment of these two pseudo color names
(recognized as colors sometimes, in some contexts) seems like an ugly kludge.
If so, and if the kludge is kept, then, by all means, feel free to make the
minor correction cited above.

In that case, please also mention in the doc that "defined color" is determined
by function `defined-colors', i.e., if it is the case that `defined-colors' can
in fact sometimes include these pseudocolors in its return value.  Mentioning
that might help users navigate the messy exceptionalism.

In that case, too, the doc of `defined-colors' should be corrected to mention
these weird exceptions.  Perhaps it can call out the circumstances under which
these noncolors are included in its return value.

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.  You can simply add that "defined color" here is per
`defined-colors'.  IOW, in this case, there is no need to mention these
noncolors, because they do not fit #1 or #2.

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

[Eli Zaretskii]

> 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.

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

[Drew Adams]

> So these two functions do not support 1-to-1 correspondence of color
> names, as you seem to assume.

I do not assume anything about these functions.

> 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.

I'm not asking you to remove anything.  I'm asking that the doc be corrected and
made more clear and complete.

If you feel it is important to mention those two noncolors here, please do so.
And consider mentioning also why that is important: why this function deals with
such exceptions.

If it is not appropriate to mention `defined-colors' here then, by all means, do
not do so.  I was hunting for some definition of "defined color" that might be
pertinent here, but apparently that was a false route.

In any case, please make clear here just what is meant by a "defined color" in
this context, and how that definition relates to those particular noncolor
defined-color exceptions.

This is all the more important if, as seems to be the case, "defined color" here
is something not at all obvious, with kludgy exceptions.

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).

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

[Eli Zaretskii]

> From: "Drew Adams" <drew.adams@oracle.com>
> Cc: <12853@debbugs.gnu.org>
> Date: Sat, 10 Nov 2012 10:56:04 -0800
> 
> I'm asking that the doc be corrected and made more clear and
> complete.

Fine with me.  I didn't want to imply that the doc string should not
be corrected.  I just wanted to explain why unspecified-* "colors" are
exceptions, and why they are mentioned in the doc string.

> 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.
                          ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

"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.

> 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.

> 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, 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.

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

[Drew Adams]

> > 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.

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

[Eli Zaretskii]

> From: "Drew Adams" <drew.adams@oracle.com>
> Cc: <12853@debbugs.gnu.org>
> Date: Sat, 10 Nov 2012 11:51:34 -0800
> 
> I can hardly believe we're having this conversation.

Me too.  I wanted to help you understand something better, and look
where this got me.  Should have known better and shut up.

> Feel free to ignore or close the bug, if it doesn't help.

I didn't object to the bug report, nor to the request to make the doc
strings more clear and informative.  So there's no reason for me to
close the bug.

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

[Chong Yidong]

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

> The doc string is missing the most basic information: What data type
> parameter COLOR is.  It should say that COLOR must be a string or the
> symbol `unspecified' (an error is raised otherwise).

Fixed, thanks.