From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.org!not-for-mail From: "Drew Adams" Newsgroups: gmane.emacs.bugs Subject: bug#12853: 24.2.50; doc of `color-defined-p' Date: Sat, 10 Nov 2012 11:51:34 -0800 Message-ID: <7CA6F6AC77DD43628A282DCB8936E7B7@us.oracle.com> References: <10495ABA26F14041A1E374AC3B820F6E@us.oracle.com> <83d2zlxs8g.fsf@gnu.org> <7DA4A38C21E342A8A4061EC7D8257556@us.oracle.com> <83bof5xq8m.fsf@gnu.org> <83625dxo67.fsf@gnu.org> NNTP-Posting-Host: plane.gmane.org Mime-Version: 1.0 Content-Type: text/plain; charset="us-ascii" Content-Transfer-Encoding: 7bit X-Trace: ger.gmane.org 1352577176 15056 80.91.229.3 (10 Nov 2012 19:52:56 GMT) X-Complaints-To: usenet@ger.gmane.org NNTP-Posting-Date: Sat, 10 Nov 2012 19:52:56 +0000 (UTC) Cc: 12853@debbugs.gnu.org To: "'Eli Zaretskii'" Original-X-From: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane.org@gnu.org Sat Nov 10 20:53:06 2012 Return-path: Envelope-to: geb-bug-gnu-emacs@m.gmane.org Original-Received: from lists.gnu.org ([208.118.235.17]) by plane.gmane.org with esmtp (Exim 4.69) (envelope-from ) id 1TXH73-0006j9-Sc for geb-bug-gnu-emacs@m.gmane.org; Sat, 10 Nov 2012 20:53:06 +0100 Original-Received: from localhost ([::1]:54757 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1TXH6u-00083E-33 for geb-bug-gnu-emacs@m.gmane.org; Sat, 10 Nov 2012 14:52:56 -0500 Original-Received: from eggs.gnu.org ([208.118.235.92]:56430) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1TXH6p-00082v-Da for bug-gnu-emacs@gnu.org; Sat, 10 Nov 2012 14:52:54 -0500 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1TXH6m-0004aE-Ag for bug-gnu-emacs@gnu.org; Sat, 10 Nov 2012 14:52:51 -0500 Original-Received: from debbugs.gnu.org ([140.186.70.43]:49768) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1TXH6m-0004aA-7J for bug-gnu-emacs@gnu.org; Sat, 10 Nov 2012 14:52:48 -0500 Original-Received: from Debian-debbugs by debbugs.gnu.org with local (Exim 4.72) (envelope-from ) id 1TXH70-0006l7-7D for bug-gnu-emacs@gnu.org; Sat, 10 Nov 2012 14:53:02 -0500 X-Loop: help-debbugs@gnu.org Resent-From: "Drew Adams" Original-Sender: debbugs-submit-bounces@debbugs.gnu.org Resent-CC: bug-gnu-emacs@gnu.org Resent-Date: Sat, 10 Nov 2012 19:53:02 +0000 Resent-Message-ID: Resent-Sender: help-debbugs@gnu.org X-GNU-PR-Message: followup 12853 X-GNU-PR-Package: emacs X-GNU-PR-Keywords: Original-Received: via spool by 12853-submit@debbugs.gnu.org id=B12853.135257712325914 (code B ref 12853); Sat, 10 Nov 2012 19:53:02 +0000 Original-Received: (at 12853) by debbugs.gnu.org; 10 Nov 2012 19:52:03 +0000 Original-Received: from localhost ([127.0.0.1]:60019 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.72) (envelope-from ) id 1TXH62-0006jk-Cu for submit@debbugs.gnu.org; Sat, 10 Nov 2012 14:52:02 -0500 Original-Received: from aserp1040.oracle.com ([141.146.126.69]:28349) by debbugs.gnu.org with esmtp (Exim 4.72) (envelope-from ) id 1TXH5y-0006jV-T4 for 12853@debbugs.gnu.org; Sat, 10 Nov 2012 14:52:00 -0500 Original-Received: from ucsinet21.oracle.com (ucsinet21.oracle.com [156.151.31.93]) by aserp1040.oracle.com (Sentrion-MTA-4.2.2/Sentrion-MTA-4.2.2) with ESMTP id qAAJpgps001874 (version=TLSv1/SSLv3 cipher=DHE-RSA-AES256-SHA bits=256 verify=OK); Sat, 10 Nov 2012 19:51:43 GMT Original-Received: from acsmt358.oracle.com (acsmt358.oracle.com [141.146.40.158]) by ucsinet21.oracle.com (8.14.4+Sun/8.14.4) with ESMTP id qAAJpfdL005756 (version=TLSv1/SSLv3 cipher=DHE-RSA-AES256-SHA bits=256 verify=NO); Sat, 10 Nov 2012 19:51:42 GMT Original-Received: from abhmt104.oracle.com (abhmt104.oracle.com [141.146.116.56]) by acsmt358.oracle.com (8.12.11.20060308/8.12.11) with ESMTP id qAAJpf9I024564; Sat, 10 Nov 2012 13:51:41 -0600 Original-Received: from dradamslap1 (/71.202.147.44) by default (Oracle Beehive Gateway v4.0) with ESMTP ; Sat, 10 Nov 2012 11:51:41 -0800 X-Mailer: Microsoft Office Outlook 11 In-reply-to: <83625dxo67.fsf@gnu.org> Thread-Index: Ac2/eCrhseiIU+KPTwuFXGTB3TFpTwAAJacQ X-MimeOLE: Produced By Microsoft MimeOLE V6.00.2900.6157 X-Source-IP: ucsinet21.oracle.com [156.151.31.93] X-Spam-Score: 0.4 (/) X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.13 Precedence: list X-Spam-Score: 0.4 (/) X-detected-operating-system: by eggs.gnu.org: GNU/Linux 2.6.x X-Received-From: 140.186.70.43 X-BeenThere: bug-gnu-emacs@gnu.org List-Id: "Bug reports for GNU Emacs, the Swiss army knife of text editors" List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane.org@gnu.org Original-Sender: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane.org@gnu.org Xref: news.gmane.org gmane.emacs.bugs:66742 Archived-At: > > 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.