From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.io!.POSTED.blaine.gmane.org!not-for-mail From: Gregory Heytings Newsgroups: gmane.emacs.bugs Subject: bug#57499: Documentation bug in the docstring of set-face-attribute? Date: Wed, 31 Aug 2022 18:33:15 +0000 Message-ID: <534c9018d2597d4fd752@heytings.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> Mime-Version: 1.0 Content-Type: text/plain; format=flowed; charset=us-ascii Injection-Info: ciao.gmane.io; posting-host="blaine.gmane.org:116.202.254.214"; logging-data="30280"; mail-complaints-to="usenet@ciao.gmane.io" Cc: 57499@debbugs.gnu.org To: Eli Zaretskii Original-X-From: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane-mx.org@gnu.org Wed Aug 31 20:34:28 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 1oTSXj-0007ha-KI for geb-bug-gnu-emacs@m.gmane-mx.org; Wed, 31 Aug 2022 20:34:27 +0200 Original-Received: from localhost ([::1]:56522 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1oTSXe-0005Kn-GD for geb-bug-gnu-emacs@m.gmane-mx.org; Wed, 31 Aug 2022 14:34:22 -0400 Original-Received: from eggs.gnu.org ([2001:470:142:3::10]:51796) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1oTSXK-0005K8-Ab for bug-gnu-emacs@gnu.org; Wed, 31 Aug 2022 14:34:05 -0400 Original-Received: from debbugs.gnu.org ([209.51.188.43]:50695) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_128_GCM_SHA256:128) (Exim 4.90_1) (envelope-from ) id 1oTSXK-0005AL-2F for bug-gnu-emacs@gnu.org; Wed, 31 Aug 2022 14:34:02 -0400 Original-Received: from Debian-debbugs by debbugs.gnu.org with local (Exim 4.84_2) (envelope-from ) id 1oTSXJ-0004dN-U3 for bug-gnu-emacs@gnu.org; Wed, 31 Aug 2022 14:34:01 -0400 X-Loop: help-debbugs@gnu.org Resent-From: Gregory Heytings Original-Sender: "Debbugs-submit" Resent-CC: bug-gnu-emacs@gnu.org Resent-Date: Wed, 31 Aug 2022 18:34: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.166197080117748 (code B ref 57499); Wed, 31 Aug 2022 18:34:01 +0000 Original-Received: (at 57499) by debbugs.gnu.org; 31 Aug 2022 18:33:21 +0000 Original-Received: from localhost ([127.0.0.1]:40438 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1oTSWf-0004cB-3h for submit@debbugs.gnu.org; Wed, 31 Aug 2022 14:33:21 -0400 Original-Received: from heytings.org ([95.142.160.155]:49194) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1oTSWa-0004by-Rt for 57499@debbugs.gnu.org; Wed, 31 Aug 2022 14:33:19 -0400 DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=heytings.org; s=20220101; t=1661970795; bh=GVZdX3pToXuhzQNG9hdZi7iK6v+e3RLkqqzAzkw1f3A=; h=Date:From:To:cc:Subject:In-Reply-To:Message-ID:References:From; b=2aUvOmdt9WmsXoHTC4E0KeMCjAx7ZedFgtY3mel3YNV0yWtOF0ENxUsKsqNCnSJD9 x2S2+SY3GN4ei3TGq+iReHK6L7/MCTEcpg5wjOI0VU6PvowlWrBE4cZ5chxtpz02UM ev3uu3XrP9eZJo+RWfaH+UWu854nRdsKGTHHz3453+DkQu/JKclWElAzg8s7EJKFXN 5tdHRdq85T1xMJSXk0+HOgVU3CZWlyyuYa0guXIubG7shZ0/dfv7YIAkWZnCQ1SqRb bsr4G944K3bWSCf8so9Pdi0Zw/y2XcWfOPE7jP+HsVY4MH0gDEPPwTzcAHnu04/zFl xdXX1WlSQOoug== In-Reply-To: <83pmggs89x.fsf@gnu.org> 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:241216 Archived-At: >> So we could even move the sentence there: 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. > > I don't think this answers the questions that did and will pop up. > Hmm... at least it would have answered the question of bug#54156, and the recent question on help-gnu-emacs. >> In which cases is the above sentence still wrong? > > It isn't wrong, it just doesn't explain itself. What do we want to say > with that passage that isn't said elsewhere in the doc string? > That nil shouldn't be used for attributes which don't give an explicit meaning to nil. For example, :underline nil means "explicitly don't underline". But, for example again, the docstring does not give an explicit meaning to :height nil or to :background nil. > > Would you be happy if that paragraph would have been removed? If not, > why not? > I'm not sure I understand your question. You mean, the sentence "All attributes can be set to `unspecified'; this fact is not further mentioned below"? 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.