From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.org!.POSTED!not-for-mail From: Eli Zaretskii Newsgroups: gmane.emacs.devel Subject: Re: Doc string and operation of color-distance Date: Fri, 15 Sep 2017 16:30:05 +0300 Message-ID: <83377om6n6.fsf@gnu.org> References: <83mv5xm84m.fsf@gnu.org> <20170914191226.GA30876@holos.localdomain> Reply-To: Eli Zaretskii NNTP-Posting-Host: blaine.gmane.org X-Trace: blaine.gmane.org 1505482271 7593 195.159.176.226 (15 Sep 2017 13:31:11 GMT) X-Complaints-To: usenet@blaine.gmane.org NNTP-Posting-Date: Fri, 15 Sep 2017 13:31:11 +0000 (UTC) Cc: emacs-devel@gnu.org To: Mark Oteiza Original-X-From: emacs-devel-bounces+ged-emacs-devel=m.gmane.org@gnu.org Fri Sep 15 15:31:03 2017 Return-path: Envelope-to: ged-emacs-devel@m.gmane.org Original-Received: from lists.gnu.org ([208.118.235.17]) by blaine.gmane.org with esmtp (Exim 4.84_2) (envelope-from ) id 1dsqhy-0001ed-Fd for ged-emacs-devel@m.gmane.org; Fri, 15 Sep 2017 15:31:02 +0200 Original-Received: from localhost ([::1]:53414 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1dsqi4-0004eo-46 for ged-emacs-devel@m.gmane.org; Fri, 15 Sep 2017 09:31:08 -0400 Original-Received: from eggs.gnu.org ([2001:4830:134:3::10]:46107) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1dsqhW-0004ed-53 for emacs-devel@gnu.org; Fri, 15 Sep 2017 09:30:35 -0400 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1dsqhQ-0003pB-E5 for emacs-devel@gnu.org; Fri, 15 Sep 2017 09:30:34 -0400 Original-Received: from fencepost.gnu.org ([2001:4830:134:3::e]:60902) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1dsqhQ-0003p2-Ao; Fri, 15 Sep 2017 09:30:28 -0400 Original-Received: from 84.94.185.246.cable.012.net.il ([84.94.185.246]:3377 helo=home-c4e4a596f7) by fencepost.gnu.org with esmtpsa (TLS1.2:RSA_AES_256_CBC_SHA1:256) (Exim 4.82) (envelope-from ) id 1dsqhN-0004NI-NY; Fri, 15 Sep 2017 09:30:28 -0400 In-reply-to: <20170914191226.GA30876@holos.localdomain> (message from Mark Oteiza on Thu, 14 Sep 2017 15:12:26 -0400) X-detected-operating-system: by eggs.gnu.org: GNU/Linux 2.2.x-3.x [generic] X-Received-From: 2001:4830:134:3::e X-BeenThere: emacs-devel@gnu.org X-Mailman-Version: 2.1.21 Precedence: list List-Id: "Emacs development discussions." List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: emacs-devel-bounces+ged-emacs-devel=m.gmane.org@gnu.org Original-Sender: "Emacs-devel" Xref: news.gmane.org gmane.emacs.devel:218321 Archived-At: > Date: Thu, 14 Sep 2017 15:12:26 -0400 > From: Mark Oteiza > Cc: emacs-devel@gnu.org > > On 14/09/17 at 09:45pm, Eli Zaretskii wrote: > > Mark, the new color-distance says something strange in its doc string: > > > > (color-distance COLOR1 COLOR2 &optional FRAME METRIC) > > > > Return an integer distance between COLOR1 and COLOR2 on FRAME. > > COLOR1 and COLOR2 may be either strings containing the color name, > > or lists of the form (RED GREEN BLUE), each in the range 0 to 65535 inclusive. > > If FRAME is unspecified or nil, the current frame is used. > > If METRIC is unspecified or nil, a modified L*u*v* metric is used. > > > > The last sentence should say "non-nil", I think > > No, the 'nil' is correct--if no metric is given as an argument, > color_distance is used which, as the comments say, is a modified L*u*v* > metric. Yes, but the comments also reference the article which describes the metric, whereas the doc string doesn't. I think we should either leave the nil case alone -- it wasn't documented before in such detail -- or add more explanations and perhaps the reference. What's important is to describe the non-nil case.