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

Previous Next

Full log

Message #29 received at 57499 <at> debbugs.gnu.org (full text, mbox):

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

> Date: Wed, 31 Aug 2022 13:43:25 +0000
> From: Gregory Heytings <gregory <at> heytings.org>
> cc: 57499 <at> debbugs.gnu.org
> 
> > How many Lisp programmers even know about unspecified, let alone 
> > understand how it differs from nil?
> 
> Well, the next paragraph in the docstring says:
> 
> 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.
> 
> 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.

> 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?
Would you be happy if that paragraph would have been removed?  If not,
why not?

Previous Next

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