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

Clarify the documentation of 'set-face-attribute'

Browse source 
* lisp/faces.el (set-face-attribute): Mention the evaluation order
of attribute-value pairs in the docstring.

* doc/lispref/display.texi (Attribute Functions): Likewise, and
explain with an example that a different argument order might give
different results.  Also align the documentation in the manual
with that of the docstring, whose changes were discussed in
bug#57499 but not included in the manual.
This commit is contained in:
Gregory Heytings 2022-12-29 22:41:58 +00:00
parent dafa6d6bad
commit d086cd6cf8
2 changed files with 21 additions and 11 deletions
Download patch file Download diff file Expand all files Collapse all files

28
doc/lispref/display.texi
View file

@ -3057,17 +3057,23 @@ If @var{frame} is @code{t}, this function sets the default attributes
for newly created frames; they will effectively override the attribute for newly created frames; they will effectively override the attribute
values specified by @code{defface}. If @var{frame} is @code{nil}, values specified by @code{defface}. If @var{frame} is @code{nil},
this function sets the attributes for all existing frames, as well as this function sets the attributes for all existing frames, as well as
for newly created frames. However, if you want to @emph{reset} the for newly created frames.
value of an attribute to @code{unspecified} in a way that also affects
newly created frames, you @emph{must} explicitly call this function To @emph{unset} the value of an attribute, that is, to indicate that
with @var{frame} set to @code{t} and the value of the attribute set to the face doesn't by itself specify a value for the attribute, the
@code{unspecified} (@emph{not} @code{nil}!@:), in addition to the call special value @code{unspecified} (@emph{not} @code{nil}!@:) must be
with @var{frame} set to @code{nil}. This is because the default used.
attributes for newly created frames are merged with the face's spec in
@code{defface} when a new frame is created, and so having Note that the attribute-value pairs are evaluated in the order they
@code{unspecified} in the default attributes for new frames will be are specified, except the @code{:family} and @code{:foundry}
unable to override @code{defface}; the special call to this function attributes, which are evaluated first. This means both that only the
as described above will arrange for @code{defface} to be overridden. last value of a given attribute will be used, and that in some cases a
different order will give 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
placed before @code{:weight} the weight value is applied to the
specified font.
@end defun @end defun
The following commands and functions mostly provide compatibility The following commands and functions mostly provide compatibility

4
lisp/faces.el
View file

@ -690,6 +690,10 @@ be reset to `unspecified' when creating new frames, disregarding
what the FACE's face spec says, call this function with FRAME set to what the FACE's face spec says, call this function with FRAME set to
t and the ATTRIBUTE's value set to `unspecified'. 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.
The following attributes are recognized: The following attributes are recognized:
`:family' `:family'