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

[Gregory Heytings <gregory@heytings.org>]

>
> I don't see the difference between my text and these two variants. Why 
> repeat that the value `unspecified' is a symbol `unspecified'?  We never 
> say such tautological things in doc strings.
>

I just want to make it as clear as possible that to get that special value 
`unspecified' one should use the symbol 'unspecified.  That might be 
unclear, because after using nil describe-face also displays 
`unspecified'.

I bet that what happened with both Damien and Joost is that they wanted to 
unset the background/foreground color of a face, they tried to use nil 
(because that's the typical value one would use everywhere else in Elisp), 
and it seemed to work: describe-face said the attribute was "unspecified", 
and the visual effect was also that of an "unspecified" attribute.  Later 
they discovered that for new frames it didn't work.

>
> Read the discussion in bug#54156 again!  That's what it was about.
>
> Or read the code in xfaces which deals with value of unspecified when 
> FRAME = t -- it doesn't just store the symbol 'unspecified' in the 
> face's attribute, it does something more sneaky.  And it interprets nil 
> as unspecified in some cases, but not in others.
>
> People stumble on these subtleties all the time, and the advice to use 
> an explicit separate call with FRAME = t in the current doc string was 
> intended to prevent that.  And note that it did work in Joost's case: he 
> maybe didn't fully understand _why_ he needs to do it, but he did 
> understand _how_ to do what he wanted.  Now we want to take that out, 
> because it hurts our excessive sense of rigor, and we will get the same 
> confusion back...
>

Hmmm...  Joost's conclusion was that using frame = nil and 'unspecified 
solved his problem, and that he would do that.

Just to be clear: I certainly do not want to take anything out.  I simply 
do not understand (neither by testing nor by reading the code) what

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

does when

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

has already been executed.  And in fact that's how this bug report 
started: I asked whether anyone could come up with a scenario that would 
make the effect of that call with frame = t apparent.

If there are cases where frame = t does something more, then clearly that 
information should stay in docstring.  My reading of the code is that it 
doesn't do anything more, because calling set-face-attribute with nil 
implies that Finternal_set_lisp_face_attribute is called with frame = 0, 
which in turn implies that Finternal_set_lisp_face_attribute is 
(recursively) called with frame = t.