From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.org!.POSTED!not-for-mail From: Eli Zaretskii Newsgroups: gmane.emacs.bugs Subject: bug#27246: 24.5; doc of `face-spec-set' Date: Sat, 10 Jun 2017 12:18:49 +0300 Message-ID: <838tl06w06.fsf@gnu.org> References: Reply-To: Eli Zaretskii NNTP-Posting-Host: blaine.gmane.org X-Trace: blaine.gmane.org 1497086413 32726 195.159.176.226 (10 Jun 2017 09:20:13 GMT) X-Complaints-To: usenet@blaine.gmane.org NNTP-Posting-Date: Sat, 10 Jun 2017 09:20:13 +0000 (UTC) Cc: 27246-done@debbugs.gnu.org To: Drew Adams Original-X-From: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane.org@gnu.org Sat Jun 10 11:20:09 2017 Return-path: Envelope-to: geb-bug-gnu-emacs@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 1dJcYz-0008JG-C1 for geb-bug-gnu-emacs@m.gmane.org; Sat, 10 Jun 2017 11:20:09 +0200 Original-Received: from localhost ([::1]:57748 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1dJcZ4-0008WO-F6 for geb-bug-gnu-emacs@m.gmane.org; Sat, 10 Jun 2017 05:20:14 -0400 Original-Received: from eggs.gnu.org ([2001:4830:134:3::10]:39484) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1dJcYv-0008Ue-TJ for bug-gnu-emacs@gnu.org; Sat, 10 Jun 2017 05:20:06 -0400 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1dJcYs-0004mq-OX for bug-gnu-emacs@gnu.org; Sat, 10 Jun 2017 05:20:05 -0400 Original-Received: from debbugs.gnu.org ([208.118.235.43]:35127) by eggs.gnu.org with esmtps (TLS1.0:RSA_AES_128_CBC_SHA1:16) (Exim 4.71) (envelope-from ) id 1dJcYs-0004mk-LM for bug-gnu-emacs@gnu.org; Sat, 10 Jun 2017 05:20:02 -0400 Original-Received: from Debian-debbugs by debbugs.gnu.org with local (Exim 4.84_2) (envelope-from ) id 1dJcYs-0002wT-Do for bug-gnu-emacs@gnu.org; Sat, 10 Jun 2017 05:20:02 -0400 Resent-From: Eli Zaretskii Original-Sender: "Debbugs-submit" Resent-To: bug-gnu-emacs@gnu.org Resent-Date: Sat, 10 Jun 2017 09:20:02 +0000 Resent-Message-ID: Resent-Sender: help-debbugs@gnu.org X-GNU-PR-Message: cc-closed 27246 X-GNU-PR-Package: emacs X-GNU-PR-Keywords: Mail-Followup-To: 27246@debbugs.gnu.org, eliz@gnu.org, drew.adams@oracle.com Original-Received: via spool by 27246-done@debbugs.gnu.org id=D27246.149708635711250 (code D ref 27246); Sat, 10 Jun 2017 09:20:02 +0000 Original-Received: (at 27246-done) by debbugs.gnu.org; 10 Jun 2017 09:19:17 +0000 Original-Received: from localhost ([127.0.0.1]:37803 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1dJcY9-0002vO-2q for submit@debbugs.gnu.org; Sat, 10 Jun 2017 05:19:17 -0400 Original-Received: from eggs.gnu.org ([208.118.235.92]:48434) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1dJcY7-0002vC-PO for 27246-done@debbugs.gnu.org; Sat, 10 Jun 2017 05:19:16 -0400 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1dJcXx-0004el-PN for 27246-done@debbugs.gnu.org; Sat, 10 Jun 2017 05:19:10 -0400 Original-Received: from fencepost.gnu.org ([2001:4830:134:3::e]:47430) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1dJcXx-0004eh-L5; Sat, 10 Jun 2017 05:19:05 -0400 Original-Received: from 84.94.185.246.cable.012.net.il ([84.94.185.246]:4253 helo=home-c4e4a596f7) by fencepost.gnu.org with esmtpsa (TLS1.2:RSA_AES_256_CBC_SHA1:256) (Exim 4.82) (envelope-from ) id 1dJcXx-0003oO-1Q; Sat, 10 Jun 2017 05:19:05 -0400 In-reply-to: (message from Drew Adams on Sun, 4 Jun 2017 22:43:34 -0700 (PDT)) X-detected-operating-system: by eggs.gnu.org: GNU/Linux 2.2.x-3.x [generic] X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list X-detected-operating-system: by eggs.gnu.org: GNU/Linux 2.2.x-3.x [generic] X-Received-From: 208.118.235.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" Xref: news.gmane.org gmane.emacs.bugs:133434 Archived-At: > Date: Sun, 4 Jun 2017 22:43:34 -0700 (PDT) > From: Drew Adams > > 1. The doc string and (elisp ) `Defining Faces' do not agree about > argument SPEC-TYPE when its value is not one of the special values > documented. > > The doc string says: > > Any other value means not to set any spec, but to run the > function for its other effects. > > Huh? What "other effects"? Not clear, but we can guess (and looking at > the code confirms) that what is hinted at is perhaps this: > > This function also defines FACE as a valid face name if it is not > already one, and (re)calculates its attributes on existing frames. > > But the Elisp manual says instead: > > Any other value of SPEC-TYPE is reserved for internal use. I've now clarified what "other effects" means (your guess is correct). > IOW, the doc string tells us to use another SPEC-TYPE value to get the > effect of defining a face and (re)calculating its attributes on existing > frames. But the Elisp manual tells us NOT to use any other SPEC-TYPE > value, because other values are reserved for internal use. I've clarified in the manual that FACE's definition and recalculation of its attributes are done for any other value of SPEC-TYPE. As for the rest, I think it's quite allright for the manual to say "reserved", while the doc string describes the current behavior (and will presumably be changed if that behavior ever changes). I don't see how this is a request NOT to use other values, just to keep in mind that their effect might change in the future. And the sources are really there to tell the full story. > 2. I also find this part unclear: > > Doc string: > > nil or `face-override-spec' means the override spec (which is usually > what you want if calling this function outside of Custom code); > > Manual: > > If [SPEC-TYPE] is nil or `face-override-spec', this function sets > the "override spec", which overrides over all other face specs on > FACE. > > "if calling this function outside of Custom code"? What does that > mean for users? It means nothing for users. For Lisp programmers, it means what it says: when this function is called from Lisp outside Custom, use this value of SPEC-TYPE. (I've made both places be more consistent.) > ("other face specs on FACE"? Does that mean the default (`defface') > spec plus the customized spec plus the saved custom spec? Yes. I've made the text more explicit about this. > And it's not clear here what those are, either.) They are described right there, so I don't see what could be unclear about them, if you write code that sets face attributes. Thanks.