Subject: bug#57499: Documentation bug in the docstring of set-face-attribute?

From: Gregory Heytings <[email-masked]>
Date: Wed, 31 Aug 2022 08:17:15 +0000

[Sorry, my previous post was incomplete.]

>
> The docstring of set-face-attribute says:
>
> "As an exception, to reset the value of some attribute to `unspecified' 
> in a way that overrides the non-`unspecified' value defined by the 
> face's spec in `defface', for new frames, you must explicitly call this 
> function with FRAME set to t and the attribute's value set to 
> `unspecified'; just using FRAME of nil will not affect new frames in 
> this case."
>
> Not only is that sentence hard to parse, it also seems wrong.
>
> Can someone come up with a scenario in which a call
>
> (set-face-attribute 'some-face nil :some-attribute 'unspecified)
>
> only affects existing frames?  In my testing it affects all frames 
> (existing and future ones), and that's also what the code seems to do: 
> set-face-attribute sets where to 0 when frame is nil, and calls 
> internal-set-face-attribute
>

with frame = 0, which according to the docstring of 
internal-set-lisp-face-attribute "means change the face on all frames, and 
change the default for new frames".