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 19:11:06 +0300 Message-ID: <83pmggs89x.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> Injection-Info: ciao.gmane.io; posting-host="blaine.gmane.org:116.202.254.214"; logging-data="9716"; 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 18:14:13 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 1oTQM0-0002K8-Rr for geb-bug-gnu-emacs@m.gmane-mx.org; Wed, 31 Aug 2022 18:14:13 +0200 Original-Received: from localhost ([::1]:54056 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1oTQLz-0003pw-AA for geb-bug-gnu-emacs@m.gmane-mx.org; Wed, 31 Aug 2022 12:14:11 -0400 Original-Received: from eggs.gnu.org ([2001:470:142:3::10]:49718) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1oTQIx-0008DM-8x for bug-gnu-emacs@gnu.org; Wed, 31 Aug 2022 12:11:03 -0400 Original-Received: from debbugs.gnu.org ([209.51.188.43]:50535) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_128_GCM_SHA256:128) (Exim 4.90_1) (envelope-from ) id 1oTQIx-0007EU-0I for bug-gnu-emacs@gnu.org; Wed, 31 Aug 2022 12:11:03 -0400 Original-Received: from Debian-debbugs by debbugs.gnu.org with local (Exim 4.84_2) (envelope-from ) id 1oTQIw-0007Cx-GE for bug-gnu-emacs@gnu.org; Wed, 31 Aug 2022 12:11: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 16:11: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.166196225227690 (code B ref 57499); Wed, 31 Aug 2022 16:11:02 +0000 Original-Received: (at 57499) by debbugs.gnu.org; 31 Aug 2022 16:10:52 +0000 Original-Received: from localhost ([127.0.0.1]:40284 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1oTQIm-0007CY-2F for submit@debbugs.gnu.org; Wed, 31 Aug 2022 12:10:52 -0400 Original-Received: from eggs.gnu.org ([209.51.188.92]:51722) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1oTQIh-0007CE-Ty for 57499@debbugs.gnu.org; Wed, 31 Aug 2022 12:10:50 -0400 Original-Received: from fencepost.gnu.org ([2001:470:142:3::e]:48220) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1oTQIc-0007CC-G4; Wed, 31 Aug 2022 12:10:42 -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=Pz708i/bEjq69FjOHP02UIbMVdz4LZ0OQrM9IV1lxhg=; b=nGs4QkfWNW4t QBJY57SMizi8cNdmwuIPRHdVmoEi8PupHM+S3DPVguGQnVPUtWDIcaX0EOAH+pWodTZsV+aO6iKYX nB8Pm/vNO5FDkdiX++RNH3mo9zQFZFwUzVZrg2rUNUrK4BNMWIiObsnEiMotm3L8GJc28yNo/02Sb yofrYfJSUDyhGjssLGB8wWd3zA0eMv4Vz1INpvGLOS59lVN2E7VfT7SSS54kYkQOl28kR/zGVvin7 QMbWDIV0U0f0W7Tfkox6xUvd2u4sRGfYHW1tSdkidsStXWGPDZ48SkHs4LPHYKRo3+yCNBNts36dR oxAng837Vds074xnzAAJIA==; Original-Received: from [87.69.77.57] (port=4417 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 1oTQIb-00072C-TZ; Wed, 31 Aug 2022 12:10:42 -0400 In-Reply-To: <534c9018d2952b7a6bd0@heytings.org> (message from Gregory Heytings on Wed, 31 Aug 2022 13:43:25 +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:241203 Archived-At: > Date: Wed, 31 Aug 2022 13:43:25 +0000 > From: Gregory Heytings > cc: 57499@debbugs.gnu.org > > > How many Lisp programmers even know about unspecified, let alone > > understand how it differs from nil? > > Well, the next paragraph in the docstring says: > > 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. > > 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. > 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? Would you be happy if that paragraph would have been removed? If not, why not?