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

[Gregory Heytings <gregory@heytings.org>]

>> I just want to make it as clear as possible that to get that special 
>> value `unspecified' one should use the symbol 'unspecified.
>
> We have gazillions of such situations everywhere in Emacs where symbol 
> values are documented, and we never say anything beyond the name of the 
> symbol with proper quoting.
>

For some reason this situation seems different (from a user point of 
view), give that the same question pops again and again.  Why is adding 
such a note a problem?

>
> That is why the doc string mentions 'defface', and that's why it talks 
> specifically about new frames.  I thought mentioning both makes the 
> extra set-face-attribute call with FRAME = t natural and easier to 
> remember and apply.
>

I'm really puzzled.  Why should the value 'unspecified be mentioned there 
as if it were somehow different from the other possible values, when in 
fact it isn't?  Once again when one calls

(set-face-attribute 'isearch nil :background 'unspecified)

this is what is happening:

(internal-set-lisp-face-attributes 'isearch :background 'unspecified 0)

which calls, recursively:

(internal-set-lisp-face-attributes 'isearch :background 'unspecified t)
(internal-set-lisp-face-attributes 'isearch :background 'unspecified #<frame-1>)
...
(internal-set-lisp-face-attributes 'isearch :background 'unspecified #<frame-n>)

And when one calls

(set-face-attribute 'isearch t :background 'unspecified)

this is what is happening:

(internal-set-lisp-face-attributes 'isearch :background 'unspecified t)

So this call is already included in the previous one.  Why should we tell 
users to add such a redundant call in their code?

As far as I understand, the actual and real problem here is some users use 
nil when they should use 'unspecified, because they are not aware that nil 
and 'unspecified are subtly different.  The subtle difference is that 
using nil works for frame = #<frame-1> ... #<frame-n>, but does not work 
with frame = t.

>
> In addition to the attribute values listed below, all attributes can 
> also be set to the special value `unspecified', which means the face 
> doesn't by itself specify a value for the attribute.
>

With "... the special value `unspecified' (for which the explicit symbol 
'unspecified must be used), which means ...", that'd be okay.

>
> When a new frame is created, attribute values in the FACE's `defspec' 
> normally override the `unspecified' values in the FACE's default 
> attributes.  To avoid that, i.e. to cause ATTRIBUTE's value be reset to 
> `unspecified' when creating new frames, disregarding what the FACE's 
> face spec says, call this function with FRAME set to t and the 
> ATTRIBUTE's value set to `unspecified'.
>

See above: I really don't understand why the 'unspecified value should be 
detailed as if it were different from the other values, when in fact it 
isn't.  The real and actual problem here is that users are confused by the 
fact that a nil value for an attribute is equivalent to an 'unspecified 
value for existing frames, but is not equivalent to 'unspecified for new 
frames.