From e86eae21a9b72a751d2dc3419b56debfce2022a9 Mon Sep 17 00:00:00 2001 From: Eli Zaretskii Date: Sat, 26 Feb 2022 09:41:05 +0200 Subject: Document better how to reset attributes of faces for new frames * doc/lispref/display.texi (Attribute Functions): * lisp/faces.el (set-face-attribute): Explain how to reset an attribute's value for future frames. (Bug#54156) --- doc/lispref/display.texi | 13 +++++++++++-- lisp/faces.el | 7 ++++++- 2 files changed, 17 insertions(+), 3 deletions(-) diff --git a/doc/lispref/display.texi b/doc/lispref/display.texi index 0ea421c774b..8a138588d31 100644 --- a/doc/lispref/display.texi +++ b/doc/lispref/display.texi @@ -2915,12 +2915,21 @@ names (such as @code{:family} or @code{:underline}) and values. Thus, sets the attribute @code{:weight} to @code{bold} and the attribute @code{:slant} to @code{italic}. - If @var{frame} is @code{t}, this function sets the default attributes for newly created frames; they will effectively override the attribute values specified by @code{defface}. If @var{frame} is @code{nil}, this function sets the attributes for all existing frames, as well as -for newly created frames. +for newly created frames. However, if you want to @emph{reset} the +value of an attribute to @code{unspecified} in a way that also affects +newly created frames, you @emph{must} explicitly call this function +with @var{frame} set to @code{t} and the value of the attribute set to +@code{unspecified} (@emph{not} @code{nil}!@:), in addition to the call +with @var{frame} set to @code{nil}. This is because the default +attributes for newly created frames are merged with the face's spec in +@code{defface} when a new frame is created, and so having +@code{unspecified} in the default attributes for new frames will be +unable to override @code{defface}; the special call to this function +as described above will arrange for @code{defface} to be overridden. @end defun The following commands and functions mostly provide compatibility diff --git a/lisp/faces.el b/lisp/faces.el index 50a82d454be..1d21a216224 100644 --- a/lisp/faces.el +++ b/lisp/faces.el @@ -663,7 +663,12 @@ face spec. It is mostly intended for internal use only. 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. +default for new frames only. As an exception, to reset the value +of some attribute to `unspecified' in a way that overrides the +non-`unspecified' value defined by the face's spec in `defface', +for new frames, you must explicitly call this function with FRAME +set to t and the attribute's value set to `unspecified'; just +using FRAME of nil will not affect new frames in this case. ARGS must come in pairs ATTRIBUTE VALUE. ATTRIBUTE must be a valid face attribute name. All attributes can be set to -- cgit v1.2.1