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

[Eli Zaretskii <eliz@gnu.org>]

> Date: Wed, 31 Aug 2022 12:53:26 +0000
> From: Gregory Heytings <gregory@heytings.org>
> cc: 57499@debbugs.gnu.org
> 
> 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.

You consider this an improvement and clarification?  How many Lisp
programmers even know about unspecified, let alone understand how it
differs from 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.

It is clear to you because you've read bug#54156 and the recent
discussion on help-gnu-emacs.  The challenge is to make it clear to
others, who haven't.

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.  Not for you and me, perhaps, but for
many others.