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

[Gregory Heytings <gregory@heytings.org>]

>
> Or let me turn the table and ask: what do you want to change in the 
> current doc string?  You want to tell that nil requires 2 calls, but 
> unspecified doesn't?
>

I see that this issue is repeatedly confusing users, so I would suggest 
something like:

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.

To reset the value of some attribute to `unspecified', you must use 
'unspecified, not nil.

This seems both much clearer than what we have now, and more correct, 
given that as far as I can tell

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

changes the face attribute to "unspecified" on existing and future frame, 
and

(set-face-attribute 'some-face t :some-attribute 'unspecified)

changes the face attribute to "unspecified" on future frames only.