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)

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