emacs-28 928e05f: Clarify "default face attributes" in the ELisp manual

[Eli Zaretskii]

branch: emacs-28
commit 928e05f2d63564284eb51a7102f96439c1b87d9f
Author: Eli Zaretskii <eliz@gnu.org>
Commit: Eli Zaretskii <eliz@gnu.org>

    Clarify "default face attributes" in the ELisp manual
    
    * doc/lispref/display.texi (Defining Faces): Add index entries for
    face symbol properties.
    (Attribute Functions): Clarify "default face attribute values" wrt
    'face-all-attributes' and 'face-attribute'.  (Bug#51465)
---
 doc/lispref/display.texi | 30 ++++++++++++++++++++++--------
 1 file changed, 22 insertions(+), 8 deletions(-)

diff --git a/doc/lispref/display.texi b/doc/lispref/display.texi
index 4500795..e5ba85d 100644
--- a/doc/lispref/display.texi
+++ b/doc/lispref/display.texi
@@ -2750,6 +2750,11 @@ terminal must match one of the @var{value}s specified 
for it in
   :group 'basic-faces)
 @end example
 
+@kindex face-defface-spec @r{(face symbol property)}
+@kindex saved-face @r{(face symbol property)}
+@kindex customized-face @r{(face symbol property)}
+@kindex theme-face @r{(face symbol property)}
+@kindex face-documentation @r{(face symbol property)}
   Internally, Emacs stores each face's default spec in its
 @code{face-defface-spec} symbol property (@pxref{Symbol Properties}).
 The @code{saved-face} property stores any face spec saved by the user
@@ -2806,9 +2811,12 @@ This function returns the value of the @var{attribute} 
attribute for
 
 If @var{frame} is omitted or @code{nil}, that means the selected frame
 (@pxref{Input Focus}).  If @var{frame} is @code{t}, this function
-returns the value of the specified attribute for newly-created frames
-(this is normally @code{unspecified}, unless you have specified some
-value using @code{set-face-attribute}; see below).
+returns the value of the specified attribute for newly-created frames,
+i.e.@: the value of the attribute before applying the face spec in the
+face's @code{defface} definition (@pxref{Defining Faces}) or the spec
+set by @code{face-spec-set}.  This default value of @var{attribute} is
+normally @code{unspecified}, unless you have specified some other
+value using @code{set-face-attribute}; see below.
 
 If @var{inherit} is @code{nil}, only attributes directly defined by
 @var{face} are considered, so the return value may be
@@ -2858,7 +2866,12 @@ elements of the result are name-value pairs of the form
 @w{@code{(@var{attr-name} . @var{attr-value})}}.  Optional argument
 @var{frame} specifies the frame whose definition of @var{face} to
 return; if omitted or @code{nil}, the returned value describes the
-default attributes of @var{face} for newly created frames.
+default attributes of @var{face} for newly created frames, i.e.@: the
+values these attributes have before applying the face spec in the
+face's @code{defface} definition or the spec set by
+@code{face-spec-set}.  These default values of the attributes are
+normally @code{unspecified}, unless you have specified some other
+value using @code{set-face-attribute}; see below.
 @end defun
 
 @defun merge-face-attribute attribute value1 value2
@@ -2876,7 +2889,7 @@ for all frames.  This function is mostly intended for 
internal usage.
 
 @defun set-face-attribute face frame &rest arguments
 This function sets one or more attributes of @var{face} for
-@var{frame}.  The attributes specifies in this way override the face
+@var{frame}.  The attributes specified in this way override the face
 spec(s) belonging to @var{face}.
 
 The extra arguments @var{arguments} specify the attributes to set, and
@@ -2893,9 +2906,10 @@ sets the attribute @code{:weight} to @code{bold} and the 
attribute
 
 
 If @var{frame} is @code{t}, this function sets the default attributes
-for newly created frames.  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; 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.
 @end defun
 
   The following commands and functions mostly provide compatibility