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:13:46 +0300 Message-ID: <83fshcrzth.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> Injection-Info: ciao.gmane.io; posting-host="blaine.gmane.org:116.202.254.214"; logging-data="9144"; 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:42:15 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 1oTTbK-0002Dd-W4 for geb-bug-gnu-emacs@m.gmane-mx.org; Wed, 31 Aug 2022 21:42:15 +0200 Original-Received: from localhost ([::1]:50816 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1oTTbJ-0007l6-M3 for geb-bug-gnu-emacs@m.gmane-mx.org; Wed, 31 Aug 2022 15:42:13 -0400 Original-Received: from eggs.gnu.org ([2001:470:142:3::10]:34544) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1oTTA2-0000Mp-Us for bug-gnu-emacs@gnu.org; Wed, 31 Aug 2022 15:14:03 -0400 Original-Received: from debbugs.gnu.org ([209.51.188.43]:50735) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_128_GCM_SHA256:128) (Exim 4.90_1) (envelope-from ) id 1oTTA2-0002dk-IZ for bug-gnu-emacs@gnu.org; Wed, 31 Aug 2022 15:14:02 -0400 Original-Received: from Debian-debbugs by debbugs.gnu.org with local (Exim 4.84_2) (envelope-from ) id 1oTTA2-0005dx-4F for bug-gnu-emacs@gnu.org; Wed, 31 Aug 2022 15:14: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 19:14: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.166197321221647 (code B ref 57499); Wed, 31 Aug 2022 19:14:02 +0000 Original-Received: (at 57499) by debbugs.gnu.org; 31 Aug 2022 19:13:32 +0000 Original-Received: from localhost ([127.0.0.1]:40484 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1oTT9Y-0005d4-1g for submit@debbugs.gnu.org; Wed, 31 Aug 2022 15:13:32 -0400 Original-Received: from eggs.gnu.org ([209.51.188.92]:56912) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1oTT9U-0005cq-OE for 57499@debbugs.gnu.org; Wed, 31 Aug 2022 15:13:30 -0400 Original-Received: from fencepost.gnu.org ([2001:470:142:3::e]:58438) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1oTT9P-0002aa-7o; Wed, 31 Aug 2022 15:13: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=JZKIRtm6NHkRgRRru4+L0rZY7x4OrLHj7BiNB5B7LAA=; b=DDmZdhT7jepX xY1/byFQ1GbB3tUOEYN9/u6/H12tGHbaGn1RDi2MaalZbYsjkd3Od1bLjnx6ZJkLw/WCgsgR0I/JR ye2/j6Y4GsA2Gkn2gITz8QyxaC7dcem/dMX+16I5Z06yqJpR/dGugMZKwEGZ0P+UV0Uefjh1Y7Czh 2s8oxgw0hXl9t69+eYAcu75wNZpoxz6dfBrrecUbCwsTyPyTh5GInjffoCb5hbBWwX+GeWle2ESyr R8Ds6+q13coSMNQpfmt2zmgBUlyqBesUlUXx7QwahvbTgt6khFCH8ZSBsKQGuyzILwq0lHO915vJl CQDFuBo8NNclyel0GVryOg==; Original-Received: from [87.69.77.57] (port=3838 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 1oTT9O-0008Ee-IW; Wed, 31 Aug 2022 15:13:23 -0400 In-Reply-To: <534c9018d2597d4fd752@heytings.org> (message from Gregory Heytings on Wed, 31 Aug 2022 18:33:15 +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:241217 Archived-At: > Date: Wed, 31 Aug 2022 18:33:15 +0000 > From: Gregory Heytings > cc: 57499@debbugs.gnu.org > > Just to be clear, I would be happier with the following docstring: > > 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 only. > > If FRAME is a frame, set the attributes only for that frame. 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. > > ARGS must come in pairs ATTRIBUTE VALUE. ATTRIBUTE must be a valid face > attribute name. All attributes can be set to `unspecified'; this fact is > not further mentioned below. To set an attribute to `unspecified', the > symbol 'unspecified must be used. Using nil may produce the same effect > in some cases, but is not guaranteed to work. This is a step back, IMO. It also repeats the same information more than once, and confuses the nil vs unspecified issue for no good reason. How about the following instead: 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 only. If FRAME is a frame, set the attributes only for that frame. 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. 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. All attributes can also be set to the special value `unspecified'; this can be used to reset the value of ATTRIBUTE in a way that overrides any value defined by the face's spec in `defface'. (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.)