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: Wed, 31 Aug 2022 16:06:07 +0300 Message-ID: <83r10wsgu8.fsf@gnu.org> References: <534c9018d2adffda3e53@heytings.org> <831qswu0p4.fsf@gnu.org> <534c9018d2f372cd7462@heytings.org> <83tu5ssi35.fsf@gnu.org> <534c9018d222586a161c@heytings.org> Injection-Info: ciao.gmane.io; posting-host="blaine.gmane.org:116.202.254.214"; logging-data="6302"; 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 Wed Aug 31 15:07:32 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 1oTNRL-0001SV-Le for geb-bug-gnu-emacs@m.gmane-mx.org; Wed, 31 Aug 2022 15:07:31 +0200 Original-Received: from localhost ([::1]:59188 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1oTNRK-00045D-Ed for geb-bug-gnu-emacs@m.gmane-mx.org; Wed, 31 Aug 2022 09:07:30 -0400 Original-Received: from eggs.gnu.org ([2001:470:142:3::10]:60024) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1oTNPv-00035Q-EU for bug-gnu-emacs@gnu.org; Wed, 31 Aug 2022 09:06:03 -0400 Original-Received: from debbugs.gnu.org ([209.51.188.43]:48763) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_128_GCM_SHA256:128) (Exim 4.90_1) (envelope-from ) id 1oTNPv-0003xs-4y for bug-gnu-emacs@gnu.org; Wed, 31 Aug 2022 09:06:03 -0400 Original-Received: from Debian-debbugs by debbugs.gnu.org with local (Exim 4.84_2) (envelope-from ) id 1oTNPu-00023d-FW for bug-gnu-emacs@gnu.org; Wed, 31 Aug 2022 09:06:02 -0400 X-Loop: help-debbugs@gnu.org Resent-From: Eli Zaretskii Original-Sender: "Debbugs-submit" Resent-CC: bug-gnu-emacs@gnu.org Resent-Date: Wed, 31 Aug 2022 13:06:02 +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.16619511537894 (code B ref 57499); Wed, 31 Aug 2022 13:06:02 +0000 Original-Received: (at 57499) by debbugs.gnu.org; 31 Aug 2022 13:05:53 +0000 Original-Received: from localhost ([127.0.0.1]:38512 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1oTNPl-00023F-1W for submit@debbugs.gnu.org; Wed, 31 Aug 2022 09:05:53 -0400 Original-Received: from eggs.gnu.org ([209.51.188.92]:56126) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1oTNPi-000231-5N for 57499@debbugs.gnu.org; Wed, 31 Aug 2022 09:05:51 -0400 Original-Received: from fencepost.gnu.org ([2001:470:142:3::e]:34624) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1oTNPc-0003vk-IA; Wed, 31 Aug 2022 09:05:44 -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=eEjKkeicpwWvEBRk09tA67v29fJjAxCqYBt18hQV6+o=; b=CZ3VBNBGY0VY 1eb61ji2W+bk/4i5Nek/O7191/EpdORU0KBP3HknMAq49uaAdzBt/mFzXJy8Z4QaNAdlWyNSyCM2d XmeH2CITNNP/geOzdzo5+R9fD2V4FQ+lTTJvPbISuN/F/tI6omipY0B8V5VeUmotiWco5XW9ZkqQN HgllhaD9JwTRQ3zLcwYC1IlZcmfo3/BFKgPud0chCg5ZcqGPMG9TQ+f+UL6RcBGVDOJvfEuUOFXfi hBKCupAG+lQSuEIK0997zRwxd8naqlcZt/4vdzLuxeJkI2FCJllxifaKMkb7/rqL22R7pcQut6c/f NMpYBGi+pt+PY9MwNfzY7g==; Original-Received: from [87.69.77.57] (port=4993 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 1oTNPa-0003cx-ME; Wed, 31 Aug 2022 09:05:43 -0400 In-Reply-To: <534c9018d222586a161c@heytings.org> (message from Gregory Heytings on Wed, 31 Aug 2022 12:53:26 +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:241195 Archived-At: > Date: Wed, 31 Aug 2022 12:53:26 +0000 > From: Gregory Heytings > cc: 57499@debbugs.gnu.org > > I see that this issue is repeatedly confusing users, so I would suggest > something like: > > If FRAME is nil, set the attributes for all existing frames, as well as > the default for new frames. If FRAME is t, change the default for new > frames only. > > To reset the value of some attribute to `unspecified', you must use > 'unspecified, not nil. You consider this an improvement and clarification? How many Lisp programmers even know about unspecified, let alone understand how it differs from nil? > This seems both much clearer than what we have now, and more correct, > given that as far as I can tell > > (set-face-attribute 'some-face nil :some-attribute 'unspecified) > > changes the face attribute to "unspecified" on existing and future frame, > and > > (set-face-attribute 'some-face t :some-attribute 'unspecified) > > changes the face attribute to "unspecified" on future frames only. It is clear to you because you've read bug#54156 and the recent discussion on help-gnu-emacs. The challenge is to make it clear to others, who haven't. This issue goes to the very intimate levels of the implementation details of face handling, and of how we merge their attributes so as to keep them independent on each frame. At the time, I thought that simplifying the issue, albeit at the price of telling half-lies, is the best we could do, so that users have a cookbook-type recipe that always works. It's quite possible that better ways of documenting this tricky aspect exist, but rest assured that just saying "unspecified, not nil" is not such a better way, because it leaves too many questions that beg answers. Not for you and me, perhaps, but for many others.