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

[Gregory Heytings]

> > 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-lisp-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".
>
> This was discussed in bug#54156.  Are there any new findings or 
> considerations that would require to reopen that discussion?

As far as I can tell, there are, but if you disagree, feel free to close 
the bug.  Bug#54156 starts with someone telling that

(set-face-attribute 'some-face nil :background nil)

did not have an effect in new frames.  To which you replied:

> The correct way to do [that] is this:
>
> (set-face-attribute 'some-face nil :background 'unspecified)
> (set-face-attribute 'some-face t :background 'unspecified)
>
> That is, one must explicitly call set-face-attribute with FRAME = t (as 
> well as nil), and pass 'unspecified' (NOT nil!) as the value.

and you later added that the call with frame = t is "a special trick to 
override defface with 'unspecified'".

It seems however that the call with frame = t is unnecessary, or at least, 
I could not come up with a scenario in which the first call does not also 
affect new frames.