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

[Gregory Heytings <gregory@heytings.org>]

>> 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.
>
> You consider this an improvement and clarification?
>

I'm not sure, but I think it is, yes.

>
> 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.

>
> This issue goes to the very intimate levels of the implementation 
> details of face handling, and of how we merge their attributes so as to 
> keep them independent on each frame.  At the time, I thought that 
> simplifying the issue, albeit at the price of telling half-lies, is the 
> best we could do, so that users have a cookbook-type recipe that always 
> works.  It's quite possible that better ways of documenting this tricky 
> aspect exist, but rest assured that just saying "unspecified, not nil" 
> is not such a better way, because it leaves too many questions that beg 
> answers.
>

Is that not a quarter-lie, which would be better than a half-lie?

In which cases is the above sentence still wrong?  It seems to cover all 
cases I can think of, frame = nil (in which case all frames are affected), 
frame = t (in which case only future frames are affected) and frame = some 
frame (in which case only that frame is affected).