; Fix recently modified docs of 'set-face-attribute' (bug#52493)

* doc/lispref/display.texi (Attribute Functions): Clarify wording
and restore removed information about resetting attributes to
'unspecified' for future frames.

* lisp/faces.el (set-face-attribute): Minor copyedit of doc
string.

2 files changed, 17 insertions, 10 deletions

diff --git a/doc/lispref/display.texi b/doc/lispref/display.texi
index 5397489e44f..604d5bd1a23 100644
--- a/doc/lispref/display.texi
+++ b/doc/lispref/display.texi
@@ -3059,16 +3059,23 @@ 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.
 
-To @emph{unset} the value of an attribute, that is, to indicate that
-the face doesn't by itself specify a value for the attribute, the
-special value @code{unspecified} (@emph{not} @code{nil}!@:) must be
-used.
+To @emph{reset} the value of an attribute, that is, to indicate that
+the face doesn't by itself specify a value for the attribute, use the
+special value @code{unspecified} (@emph{not} @code{nil}!@:) for the
+attribute, and set the @var{frame} argument to @code{t}, 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.
 
 Note that the attribute-value pairs are evaluated in the order they
-are specified, except the @code{:family} and @code{:foundry}
-attributes, which are evaluated first.  This means both that only the
-last value of a given attribute will be used, and that in some cases a
-different order will give different results.  For example, when
+are specified, with the exception of the @code{:family} and
+@code{:foundry} attributes, which are evaluated first.  This means
+that if a certain attribute is specified more than once, only the last
+value will be used.  It also means that in some cases a different
+order of attributes will produce different results.  For example, when
 @code{:weight} is placed before @code{:font}, the weight value is
 applied to the current font of the face, and might be rounded to the
 closest available weight of that font, whereas when @code{:font} is
diff --git a/lisp/faces.el b/lisp/faces.el
index fe683e437f5..0dd89be4738 100644
--- a/lisp/faces.el
+++ b/lisp/faces.el
@@ -691,8 +691,8 @@ what the FACE's face spec says, call this function with FRAME set to
 t and the ATTRIBUTE's value set to `unspecified'.
 
 Note that the ATTRIBUTE VALUE pairs are evaluated in the order
-they are specified, except the `:family' and `:foundry'
-attributes which are evaluated first.
+they are specified, except that the `:family' and `:foundry'
+attributes are evaluated first.
 
 The following attributes are recognized: