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 22:49:48 +0300 Message-ID: <83czcgry5f.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> Injection-Info: ciao.gmane.io; posting-host="blaine.gmane.org:116.202.254.214"; logging-data="17436"; 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 21:51:56 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 1oTTkh-0004OG-Fr for geb-bug-gnu-emacs@m.gmane-mx.org; Wed, 31 Aug 2022 21:51:55 +0200 Original-Received: from localhost ([::1]:60014 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1oTTkg-0002cJ-6w for geb-bug-gnu-emacs@m.gmane-mx.org; Wed, 31 Aug 2022 15:51:54 -0400 Original-Received: from eggs.gnu.org ([2001:470:142:3::10]:42374) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1oTTis-0000Tj-64 for bug-gnu-emacs@gnu.org; Wed, 31 Aug 2022 15:50:08 -0400 Original-Received: from debbugs.gnu.org ([209.51.188.43]:50789) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_128_GCM_SHA256:128) (Exim 4.90_1) (envelope-from ) id 1oTTir-0008AP-OW for bug-gnu-emacs@gnu.org; Wed, 31 Aug 2022 15:50:01 -0400 Original-Received: from Debian-debbugs by debbugs.gnu.org with local (Exim 4.84_2) (envelope-from ) id 1oTTir-0006cG-KE for bug-gnu-emacs@gnu.org; Wed, 31 Aug 2022 15:50: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: Wed, 31 Aug 2022 19:50: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.166197537125389 (code B ref 57499); Wed, 31 Aug 2022 19:50:01 +0000 Original-Received: (at 57499) by debbugs.gnu.org; 31 Aug 2022 19:49:31 +0000 Original-Received: from localhost ([127.0.0.1]:40538 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1oTTiN-0006bR-1v for submit@debbugs.gnu.org; Wed, 31 Aug 2022 15:49:31 -0400 Original-Received: from eggs.gnu.org ([209.51.188.92]:33136) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1oTTiL-0006bD-3Z for 57499@debbugs.gnu.org; Wed, 31 Aug 2022 15:49:30 -0400 Original-Received: from fencepost.gnu.org ([2001:470:142:3::e]:33470) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1oTTiF-00087K-L4; Wed, 31 Aug 2022 15:49:23 -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=3opBZmFtt+BuYbeR7D2BAEQaGMwtWKpNoiHlQm5kXzU=; b=VTgauMiSVUGP xM2gSXkXdqlZhn4ox0TleAbbuovLXR8Bncij+Igz23l9cxLP9LgpngJ5Y8nnhquHyfgV98OW7czeI cZGgdjfVkSND4EUemkE0jofK7uEkpwRSZJBbW4moc7PivTiMKKMBSvrq6YdisqpW598wwhrgtvTkd FbwYcCbGv0tyzi3MQ9huGd/Gd/w+hk9h4VUzvx86b8/ci3mKr47njl4deFqKgBVa9/b4+/fP7r/rD /r99nspzAN4wSpp46CYz4Sy/l1AR9L7HMbLvRb4UBrhHiamZ1fNvHZVx64JZXYgr9nMg3vdSWOKAt SgewKXR9mhb2/EBwrwwbYA==; Original-Received: from [87.69.77.57] (port=2184 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 1oTTiE-0007EV-Ut; Wed, 31 Aug 2022 15:49:23 -0400 In-Reply-To: <534c9018d2c911550778@heytings.org> (message from Gregory Heytings on Wed, 31 Aug 2022 19:33:53 +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:241218 Archived-At: > Date: Wed, 31 Aug 2022 19:33:53 +0000 > From: Gregory Heytings > cc: 57499@debbugs.gnu.org > > This is better indeed, but I'd add "by using the symbol 'unspecified for > VALUE" after "the special value `unspecified'". Or perhaps use "the > special VALUE `unspecified' with the explicit symbol 'unspecified". 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. > > (Of course, after making such a change, we will again need to answer > > questions how come using value of nil and FRAME = nil doesn't reset the > > attribute, something that the current doc string avoids. Oh well.) > > > > I'm not sure I understand what you mean. If the docstring says one should > use the symbol 'unspecified, it should be clear to everyone that nil > shouldn't be used, no? What am I missing? 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...