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

[Gregory Heytings <gregory@heytings.org>]

>> 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.
>
> I don't think this answers the questions that did and will pop up.
>

Hmm... at least it would have answered the question of bug#54156, and the 
recent question on help-gnu-emacs.

>> In which cases is the above sentence still wrong?
>
> It isn't wrong, it just doesn't explain itself.  What do we want to say 
> with that passage that isn't said elsewhere in the doc string?
>

That nil shouldn't be used for attributes which don't give an explicit 
meaning to nil.  For example, :underline nil means "explicitly don't 
underline".  But, for example again, the docstring does not give an 
explicit meaning to :height nil or to :background nil.

>
> Would you be happy if that paragraph would have been removed?  If not, 
> why not?
>

I'm not sure I understand your question.  You mean, the sentence "All 
attributes can be set to `unspecified'; this fact is not further mentioned 
below"?

Just to be clear, I would be happier with the following docstring:

Set attributes of FACE on FRAME from ARGS.

This function overrides the face attributes specified by FACE's face spec. 
It is mostly intended for internal use only.

If FRAME is a frame, set the attributes only for that frame.  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.

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