emacs-29 69b2aaaade: ; Fix recently modified docs of 'set-face-attribute' (bug#52493)

[Eli Zaretskii]

branch: emacs-29
commit 69b2aaaaded71b05b41b52ee5072d4d8babe33b6
Author: Eli Zaretskii <eliz@gnu.org>
Commit: Eli Zaretskii <eliz@gnu.org>

    ; 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.
---
 doc/lispref/display.texi | 23 +++++++++++++++--------
 lisp/faces.el            |  4 ++--
 2 files changed, 17 insertions(+), 10 deletions(-)

diff --git a/doc/lispref/display.texi b/doc/lispref/display.texi
index 5397489e44..604d5bd1a2 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 fe683e437f..0dd89be473 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: