From 928e05f2d63564284eb51a7102f96439c1b87d9f Mon Sep 17 00:00:00 2001 From: Eli Zaretskii Date: Fri, 29 Oct 2021 10:10:01 +0300 Subject: [PATCH] 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 4500795e45b..e5ba85db9f1 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 -- 2.39.2