GNU bug report logs - #57499
Documentation bug in the docstring of set-face-attribute?

Previous Next

Full log

View this message in rfc822 format

From: Gregory Heytings <gregory <at> heytings.org>
To: Eli Zaretskii <eliz <at> gnu.org>
Cc: 57499 <at> debbugs.gnu.org
Subject: bug#57499: Documentation bug in the docstring of set-face-attribute?
Date: Wed, 31 Aug 2022 19:33:53 +0000

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

Previous Next

GNU bug tracking system
Copyright (C) 1999 Darren O. Benham, 1997,2003 nCipher Corporation Ltd, 1994-97 Ian Jackson.