Commit 187a71df authored by Eli Zaretskii's avatar Eli Zaretskii
Browse files

Clarify documentation of 'face-spec-set'

* lisp/faces.el (face-spec-set): Clarify the description of
SPEC-TYPE in the doc string.

* doc/lispref/display.texi (Defining Faces): Clarify the
description of 'face-spec-set's SPEC-TYPE argument.  (Bug#27246)
parent f361c54e
......@@ -2531,16 +2531,20 @@ This function also defines @var{face} as a valid face name if it is
not already one, and (re)calculates its attributes on existing frames.
@cindex override spec @r{(for a face)}
The argument @var{spec-type} determines which spec to set. If it is
@code{nil} or @code{face-override-spec}, this function sets the
@dfn{override spec}, which overrides over all other face specs on
@var{face}. If it is @code{customized-face} or @code{saved-face},
this function sets the customized spec or the saved custom spec. If
it is @code{face-defface-spec}, this function sets the default face
spec (the same one set by @code{defface}). If it is @code{reset},
this function clears out all customization specs and override specs
from @var{face} (in this case, the value of @var{spec} is ignored).
Any other value of @var{spec-type} is reserved for internal use.
The optional argument @var{spec-type} determines which spec to set.
If it is omitted or @code{nil} or @code{face-override-spec}, this
function sets the @dfn{override spec}, which overrides face specs on
@var{face} of all the other types mentioned below. This is useful
when calling this function outside of Custom code. If @var{spec-type}
is @code{customized-face} or @code{saved-face}, this function sets the
customized spec or the saved custom spec, respectively. If it is
@code{face-defface-spec}, this function sets the default face spec
(the same one set by @code{defface}). If it is @code{reset}, this
function clears out all customization specs and override specs from
@var{face} (in this case, the value of @var{spec} is ignored). The
effect of any other value of @var{spec-type} on the face specs is
reserved for internal use, but the function will still define
@var{face} itself and recalculate its attributes, as described above.
@end defun
@node Attribute Functions
......
......@@ -1667,7 +1667,7 @@ is given, in which case return its value instead."
face--attributes-unspecified)))
(defun face-spec-set (face spec &optional spec-type)
"Set the face spec SPEC for FACE.
"Set the FACE's spec SPEC, define FACE, and recalculate its attributes.
See `defface' for the format of SPEC.
The appearance of each face is controlled by its specs (set via
......@@ -1678,10 +1678,11 @@ This function also defines FACE as a valid face name if it is not
already one, and (re)calculates its attributes on existing
frames.
The argument SPEC-TYPE determines which spec to set:
nil or `face-override-spec' means the override spec (which is
usually what you want if calling this function outside of
Custom code);
The optional argument SPEC-TYPE determines which spec to set:
nil, omitted or `face-override-spec' means the override spec,
which overrides all the other types of spec mentioned below
(this is usually what you want if calling this function
outside of Custom code);
`customized-face' or `saved-face' means the customized spec or
the saved custom spec;
`face-defface-spec' means the default spec
......@@ -1689,7 +1690,7 @@ The argument SPEC-TYPE determines which spec to set:
`reset' means to ignore SPEC, but clear the `customized-face'
and `face-override-spec' specs;
Any other value means not to set any spec, but to run the
function for its other effects."
function for defining FACE and recalculating its attributes."
(if (get face 'face-alias)
(setq face (get face 'face-alias)))
;; Save SPEC to the relevant symbol property.
......
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment