From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.org!.POSTED!not-for-mail From: Mark Oteiza Newsgroups: gmane.emacs.devel Subject: Re: Doc string and operation of color-distance Date: Fri, 15 Sep 2017 12:45:43 -0400 Message-ID: <20170915164543.GA19268@holos.localdomain> References: <83mv5xm84m.fsf@gnu.org> <20170914191226.GA30876@holos.localdomain> <83377om6n6.fsf@gnu.org> NNTP-Posting-Host: blaine.gmane.org Mime-Version: 1.0 Content-Type: text/plain; charset=us-ascii X-Trace: blaine.gmane.org 1505493982 18191 195.159.176.226 (15 Sep 2017 16:46:22 GMT) X-Complaints-To: usenet@blaine.gmane.org NNTP-Posting-Date: Fri, 15 Sep 2017 16:46:22 +0000 (UTC) User-Agent: Mutt/1.9.0 (2017-09-02) Cc: emacs-devel@gnu.org To: Eli Zaretskii Original-X-From: emacs-devel-bounces+ged-emacs-devel=m.gmane.org@gnu.org Fri Sep 15 18:46:18 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 1dstkv-0004ah-Pe for ged-emacs-devel@m.gmane.org; Fri, 15 Sep 2017 18:46:17 +0200 Original-Received: from localhost ([::1]:54240 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1dstl3-00085y-AL for ged-emacs-devel@m.gmane.org; Fri, 15 Sep 2017 12:46:25 -0400 Original-Received: from eggs.gnu.org ([2001:4830:134:3::10]:46225) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1dstkT-00085X-Bb for emacs-devel@gnu.org; Fri, 15 Sep 2017 12:45:50 -0400 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1dstkQ-0003IG-OS for emacs-devel@gnu.org; Fri, 15 Sep 2017 12:45:49 -0400 Original-Received: from mail-qk0-x234.google.com ([2607:f8b0:400d:c09::234]:48251) by eggs.gnu.org with esmtps (TLS1.0:RSA_AES_128_CBC_SHA1:16) (Exim 4.71) (envelope-from ) id 1dstkQ-0003Hf-BP for emacs-devel@gnu.org; Fri, 15 Sep 2017 12:45:46 -0400 Original-Received: by mail-qk0-x234.google.com with SMTP id a128so2600150qkc.5 for ; Fri, 15 Sep 2017 09:45:46 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=udel-edu.20150623.gappssmtp.com; s=20150623; h=date:from:to:cc:subject:message-id:references:mime-version :content-disposition:in-reply-to:user-agent; bh=wDsy6qyUbb4pznCENpWDJLBSHHywOjhYMbG68eGucFY=; b=j2qRg6fA6DTtO0UjrTN4wbqV5lOdsjo1gU1NZXA+7tkFk4VGLtbOgAch4iO/TE+7Qz VX/IHZAO8UyxsnA+c4FDUDndSTSPUTN4R9Mjq3liZbHZkQkHJkRSstJaASar8WrfUmqJ 6TphaAcILA36HWWNiStxS6NSyzDQdnKBHlWFjDyupb5wxTxS6hQTPT2ThI7YJcSAlmfc VIEw5pkrfJ07btAjOL5Yygqo5Co1rC+6abuxSP/3bEhCY9fJklaLhq0pGRsorHPXYrkH IR/jtQoUVykkg0X/Xa8aMTUGCg7OPP0TRZ2y50cSCUy7IkK8si5v9doYUWErV+Nx09nd SGjQ== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20161025; h=x-gm-message-state:date:from:to:cc:subject:message-id:references :mime-version:content-disposition:in-reply-to:user-agent; bh=wDsy6qyUbb4pznCENpWDJLBSHHywOjhYMbG68eGucFY=; b=WOR89Cve5d4a83IAdj7AXY7tpqSAfZRLpwsx2zmfxBfzSnR8/NUwaDUnU9QIbVNXzW VYnkD3/fYC+fsnlbayazrwdhRgE/FyGPYGccwuHlSenHgbmGAQyo0kzxyAePDBzH53oO 91X2SF80k20GCUxcOuHx7obMAgSD4qYWon6QaZ9pPsZ0HVcT796fhDKoJu6X+XMZ0b21 X8HgGXBpDp4G2pDqY4T59+KmPP8MOPKB8ssZyMhuKoeYUN8Uj/A36E540Ox3+zI4BUs5 MC93b56d3CpFGgGnCembDbdN2kBnp19/ngBID2WK8tOV2WbuKyG6lwj7eB0i+HyZzEvU p1AA== X-Gm-Message-State: AHPjjUghaJ+h4656tn06KX+6NeYTZSBIVAVK2sAjWmumrbmiLdlnelkC riH2IUJhgtbWRhsj X-Google-Smtp-Source: AOwi7QCXB2mrTAYuN3i3+d1p9QJh33yHEC+W1pjdwpgaoN2aYMANyXyOd70fgKl5NcTHKATmJa5HYA== X-Received: by 10.55.27.66 with SMTP id b63mr8110099qkb.338.1505493945418; Fri, 15 Sep 2017 09:45:45 -0700 (PDT) Original-Received: from holos.localdomain (pool-173-67-36-61.bltmmd.fios.verizon.net. [173.67.36.61]) by smtp.gmail.com with ESMTPSA id d5sm823882qtd.43.2017.09.15.09.45.44 (version=TLS1_2 cipher=ECDHE-RSA-CHACHA20-POLY1305 bits=256/256); Fri, 15 Sep 2017 09:45:44 -0700 (PDT) Original-Received: by holos.localdomain (Postfix, from userid 1000) id B73AB69FB7; Fri, 15 Sep 2017 12:45:43 -0400 (EDT) Content-Disposition: inline In-Reply-To: <83377om6n6.fsf@gnu.org> X-detected-operating-system: by eggs.gnu.org: Genre and OS details not recognized. X-Received-From: 2607:f8b0:400d:c09::234 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:218329 Archived-At: On 15/09/17 at 04:30pm, Eli Zaretskii wrote: > > 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. OK, I agree. How about the following? diff --git a/src/xfaces.c b/src/xfaces.c index 012de4e7af..b309c16127 100644 --- a/src/xfaces.c +++ b/src/xfaces.c @@ -4093,7 +4093,8 @@ DEFUN ("color-distance", Fcolor_distance, Scolor_distance, 2, 4, 0, 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. */) +If METRIC is specified, it should be a function that accepts +two lists of the form (RED GREEN BLUE) aforementioned. */) (Lisp_Object color1, Lisp_Object color2, Lisp_Object frame, Lisp_Object metric) { @@ -4112,7 +4113,13 @@ If METRIC is unspecified or nil, a modified L*u*v* metric is used. */) if (NILP (metric)) return make_number (color_distance (&cdef1, &cdef2)); else - return call2 (metric, color1, color2); + return call2 (metric, + list3 (make_number (cdef1.red), + make_number (cdef1.green), + make_number (cdef1.blue)), + list3 (make_number (cdef2.red), + make_number (cdef2.green), + make_number (cdef2.blue))); }