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

[Eli Zaretskii]

> Date: Wed, 31 Aug 2022 19:33:53 +0000
> From: Gregory Heytings <gregory@heytings.org>
> cc: 57499@debbugs.gnu.org
> 
> This is better indeed, but I'd add "by using the symbol 'unspecified for 
> VALUE" after "the special value `unspecified'".  Or perhaps use "the 
> special VALUE `unspecified' with the explicit symbol 'unspecified".

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.

> > (Of course, after making such a change, we will again need to answer 
> > questions how come using value of nil and FRAME = nil doesn't reset the 
> > attribute, something that the current doc string avoids.  Oh well.)
> >
> 
> I'm not sure I understand what you mean.  If the docstring says one should 
> use the symbol 'unspecified, it should be clear to everyone that nil 
> shouldn't be used, no?  What am I missing?

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