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

[Gregory Heytings <gregory@heytings.org>]

>
> 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 and VALUE must be a value that is valid for ATTRIBUTE, as 
> described below for each attribute.
>
> All attributes can also be set to the special value `unspecified'; this 
> can be used to reset the value of ATTRIBUTE in a way that overrides any 
> value defined by the face's spec in `defface'.
>

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

>
> (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?