procyberian/emacs
2
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

Clarify "default face attributes" in the ELisp manual

Browse source 
* 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)
This commit is contained in:
Eli Zaretskii 2021-10-29 10:10:01 +03:00
parent 5dbb04e0eb
commit 928e05f2d6
1 changed files with 22 additions and 8 deletions
Download patch file Download diff file Expand all files Collapse all files

30
doc/lispref/display.texi
View file

@ -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