GNU bug report logs - #12853
24.2.50; doc of `color-defined-p'

Previous Next

Full log

Message #11 received at 12853 <at> debbugs.gnu.org (full text, mbox):

From: "Drew Adams" <drew.adams <at> oracle.com>
To: "'Eli Zaretskii'" <eliz <at> gnu.org>
Cc: 12853 <at> debbugs.gnu.org
Subject: RE: bug#12853: 24.2.50; doc of `color-defined-p'
Date: Sat, 10 Nov 2012 10:12:34 -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.

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.

Previous Next

GNU bug tracking system
Copyright (C) 1999 Darren O. Benham, 1997,2003 nCipher Corporation Ltd, 1994-97 Ian Jackson.