From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.io!.POSTED.blaine.gmane.org!not-for-mail From: Eli Zaretskii Newsgroups: gmane.emacs.bugs Subject: bug#57499: Documentation bug in the docstring of set-face-attribute? Date: Thu, 01 Sep 2022 10:04:36 +0300 Message-ID: <837d2nshh7.fsf@gnu.org> References: <534c9018d2adffda3e53@heytings.org> <831qswu0p4.fsf@gnu.org> <534c9018d2f372cd7462@heytings.org> <83tu5ssi35.fsf@gnu.org> <534c9018d222586a161c@heytings.org> <83r10wsgu8.fsf@gnu.org> <534c9018d2952b7a6bd0@heytings.org> <83pmggs89x.fsf@gnu.org> <534c9018d2597d4fd752@heytings.org> <83fshcrzth.fsf@gnu.org> <534c9018d2c911550778@heytings.org> <83czcgry5f.fsf@gnu.org> <534c9018d2f901e88b93@heytings.org> Injection-Info: ciao.gmane.io; posting-host="blaine.gmane.org:116.202.254.214"; logging-data="15254"; mail-complaints-to="usenet@ciao.gmane.io" Cc: 57499@debbugs.gnu.org To: Gregory Heytings Original-X-From: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane-mx.org@gnu.org Thu Sep 01 09:38:47 2022 Return-path: Envelope-to: geb-bug-gnu-emacs@m.gmane-mx.org Original-Received: from lists.gnu.org ([209.51.188.17]) by ciao.gmane.io with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.92) (envelope-from ) id 1oTemk-0003kV-3B for geb-bug-gnu-emacs@m.gmane-mx.org; Thu, 01 Sep 2022 09:38:46 +0200 Original-Received: from localhost ([::1]:35370 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1oTemg-0005dY-Og for geb-bug-gnu-emacs@m.gmane-mx.org; Thu, 01 Sep 2022 03:38:42 -0400 Original-Received: from eggs.gnu.org ([2001:470:142:3::10]:54278) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1oTeG6-00075m-Uf for bug-gnu-emacs@gnu.org; Thu, 01 Sep 2022 03:05:08 -0400 Original-Received: from debbugs.gnu.org ([209.51.188.43]:51255) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_128_GCM_SHA256:128) (Exim 4.90_1) (envelope-from ) id 1oTeG6-0005FD-65 for bug-gnu-emacs@gnu.org; Thu, 01 Sep 2022 03:05:02 -0400 Original-Received: from Debian-debbugs by debbugs.gnu.org with local (Exim 4.84_2) (envelope-from ) id 1oTeG5-0005Hp-Rr for bug-gnu-emacs@gnu.org; Thu, 01 Sep 2022 03:05:01 -0400 X-Loop: help-debbugs@gnu.org Resent-From: Eli Zaretskii Original-Sender: "Debbugs-submit" Resent-CC: bug-gnu-emacs@gnu.org Resent-Date: Thu, 01 Sep 2022 07:05:01 +0000 Resent-Message-ID: Resent-Sender: help-debbugs@gnu.org X-GNU-PR-Message: followup 57499 X-GNU-PR-Package: emacs Original-Received: via spool by 57499-submit@debbugs.gnu.org id=B57499.166201586120263 (code B ref 57499); Thu, 01 Sep 2022 07:05:01 +0000 Original-Received: (at 57499) by debbugs.gnu.org; 1 Sep 2022 07:04:21 +0000 Original-Received: from localhost ([127.0.0.1]:41004 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1oTeFQ-0005Gl-Dy for submit@debbugs.gnu.org; Thu, 01 Sep 2022 03:04:20 -0400 Original-Received: from eggs.gnu.org ([209.51.188.92]:46692) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1oTeFK-0005GU-R8 for 57499@debbugs.gnu.org; Thu, 01 Sep 2022 03:04:19 -0400 Original-Received: from fencepost.gnu.org ([2001:470:142:3::e]:55712) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1oTeFF-00054p-FV; Thu, 01 Sep 2022 03:04:09 -0400 DKIM-Signature: v=1; a=rsa-sha256; q=dns/txt; c=relaxed/relaxed; d=gnu.org; s=fencepost-gnu-org; h=References:Subject:In-Reply-To:To:From:Date: mime-version; bh=omI0w4vpdNlSGkDePuh2yq76jPf5THiJ/UM+UWckdSY=; b=gcbROJCA9pb3 gUccdwyv3a/QN1XXlS7t6nB+Z0ldgsBWJqLsgZioyha550HJAwQRJZ2jcdLXyTOxLAkthUsj0BJHf aIWNW2VopJ2vonwUnQPSozH3bDHP17pg8dPKNUQL7YhsqvZFhMvuYdv4dqPwg48TSfyTO4nBUm8dY QUAR691t8944CdFD7d70dT1wGdA/0VXmOf5m7bauMrBWdHeyklctoTSz4fP4oy36BHGGu9o0CAh5l rksGp7n5hPO7CDyitclnuL3JpAUWwC+8EV94VOgXKl/u134HmrapTK8g8LGEtuGU6WbXBsvXQWyzJ xmkSHO/FnVFiVLtlAttKbA==; Original-Received: from [87.69.77.57] (port=3632 helo=home-c4e4a596f7) by fencepost.gnu.org with esmtpsa (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1oTeFE-0005yD-Pl; Thu, 01 Sep 2022 03:04:09 -0400 In-Reply-To: <534c9018d2f901e88b93@heytings.org> (message from Gregory Heytings on Wed, 31 Aug 2022 21:13:58 +0000) X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list 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-mx.org@gnu.org Original-Sender: "bug-gnu-emacs" Xref: news.gmane.io gmane.emacs.bugs:241233 Archived-At: > Date: Wed, 31 Aug 2022 21:13:58 +0000 > From: Gregory Heytings > cc: 57499@debbugs.gnu.org > > > I don't see the difference between my text and these two variants. Why > > repeat that the value `unspecified' is a symbol `unspecified'? We never > > say such tautological things in doc strings. > > I just want to make it as clear as possible that to get that special value > `unspecified' one should use the symbol 'unspecified. We have gazillions of such situations everywhere in Emacs where symbol values are documented, and we never say anything beyond the name of the symbol with proper quoting. > > Read the discussion in bug#54156 again! That's what it was about. > > > > Or read the code in xfaces which deals with value of unspecified when > > FRAME = t -- it doesn't just store the symbol 'unspecified' in the > > face's attribute, it does something more sneaky. And it interprets nil > > as unspecified in some cases, but not in others. > > > > People stumble on these subtleties all the time, and the advice to use > > an explicit separate call with FRAME = t in the current doc string was > > intended to prevent that. And note that it did work in Joost's case: he > > maybe didn't fully understand _why_ he needs to do it, but he did > > understand _how_ to do what he wanted. Now we want to take that out, > > because it hurts our excessive sense of rigor, and we will get the same > > confusion back... > > Hmmm... Joost's conclusion was that using frame = nil and 'unspecified > solved his problem, and that he would do that. Let me try explaining the issue which that part of the doc string tries to address, one last time. The text mentions 'defface'. Why does it do that? Because a face's 'defface' is relevant when realizing the faces of newly-created frames; it has no effect whatsoever on existing frames. So the issue here is: how do you reset a face's attribute to 'unspecified' in a way that would override what its 'defface' spec says, and set the attribute to 'unspecified' on future frames? The doc string says that if you want to do that (and it is not clear that you do, because faces are frame-local), _then_ you should call set-face-attribute with FRAME = t and the attribute's value set to 'unspecified', and that call does special wizardry to ensure 'defface' is overridden when new frames are created. That is why the doc string mentions 'defface', and that's why it talks specifically about new frames. I thought mentioning both makes the extra set-face-attribute call with FRAME = t natural and easier to remember and apply. So here's one more attempt to clarify the doc string without losing that information: Set attributes of FACE on FRAME from ARGS. This function overrides the face attributes specified by FACE's face spec. It is mostly intended for internal use. If FRAME is a frame, set the FACE's attributes only for that frame. If FRAME is nil, set attribute values for all existing frames, as well as the default for new frames. If FRAME is t, change the default values of attributes for new frames. ARGS must come in pairs ATTRIBUTE VALUE. ATTRIBUTE must be a valid face attribute name and VALUE must be a value that is valid for ATTRIBUTE, as described below for each attribute. In addition to the attribute values listed below, all attributes can also be set to the special value `unspecified', which means the face doesn't by itself specify a value for the attribute. When a new frame is created, attribute values in the FACE's `defspec' normally override the `unspecified' values in the FACE's default attributes. To avoid that, i.e. to cause ATTRIBUTE's value be reset to `unspecified' when creating new frames, disregarding what the FACE's face spec says, call this function with FRAME set to t and the ATTRIBUTE's value set to `unspecified'. > Just to be clear: I certainly do not want to take anything out. I simply > do not understand (neither by testing nor by reading the code) what > > (set-face-attribute 'some-face t :some-attribute 'unspecified) > > does when > > (set-face-attribute 'some-face nil :some-attribute 'unspecified) > > has already been executed. Do you understand what (set-face-attribute 'some-face t :some-attribute 'unspecified) does differently from what (set-face-attribute 'some-face FRAME :some-attribute 'unspecified) does? I mean, besides the difference in FRAME argument value? > And in fact that's how this bug report started: I asked whether > anyone could come up with a scenario that would make the effect of > that call with frame = t apparent. See above: that's not what that part of the doc string attempts to address.