[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
bug#57499: Documentation bug in the docstring of set-face-attribute?
From: |
Gregory Heytings |
Subject: |
bug#57499: Documentation bug in the docstring of set-face-attribute? |
Date: |
Wed, 31 Aug 2022 13:43:25 +0000 |
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?
I'm not sure, but I think it is, yes.
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.
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.
Is that not a quarter-lie, which would be better than a half-lie?
In which cases is the above sentence still wrong? It seems to cover all
cases I can think of, frame = nil (in which case all frames are affected),
frame = t (in which case only future frames are affected) and frame = some
frame (in which case only that frame is affected).
- bug#57499: Documentation bug in the docstring of set-face-attribute?, Gregory Heytings, 2022/08/31
- bug#57499: Documentation bug in the docstring of set-face-attribute?, Gregory Heytings, 2022/08/31
- bug#57499: Documentation bug in the docstring of set-face-attribute?, Eli Zaretskii, 2022/08/31
- bug#57499: Documentation bug in the docstring of set-face-attribute?, Gregory Heytings, 2022/08/31
- bug#57499: Documentation bug in the docstring of set-face-attribute?, Eli Zaretskii, 2022/08/31
- bug#57499: Documentation bug in the docstring of set-face-attribute?, Gregory Heytings, 2022/08/31
- bug#57499: Documentation bug in the docstring of set-face-attribute?, Eli Zaretskii, 2022/08/31
- bug#57499: Documentation bug in the docstring of set-face-attribute?,
Gregory Heytings <=
- bug#57499: Documentation bug in the docstring of set-face-attribute?, Eli Zaretskii, 2022/08/31
- bug#57499: Documentation bug in the docstring of set-face-attribute?, Gregory Heytings, 2022/08/31
- bug#57499: Documentation bug in the docstring of set-face-attribute?, Eli Zaretskii, 2022/08/31
- bug#57499: Documentation bug in the docstring of set-face-attribute?, Gregory Heytings, 2022/08/31
- bug#57499: Documentation bug in the docstring of set-face-attribute?, Eli Zaretskii, 2022/08/31
- bug#57499: Documentation bug in the docstring of set-face-attribute?, Gregory Heytings, 2022/08/31