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 ...@@ -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. not already one, and (re)calculates its attributes on existing frames.
@cindex override spec @r{(for a face)} @cindex override spec @r{(for a face)}
The argument @var{spec-type} determines which spec to set. If it is The optional argument @var{spec-type} determines which spec to set.
@code{nil} or @code{face-override-spec}, this function sets the If it is omitted or @code{nil} or @code{face-override-spec}, this
@dfn{override spec}, which overrides over all other face specs on function sets the @dfn{override spec}, which overrides face specs on
@var{face}. If it is @code{customized-face} or @code{saved-face}, @var{face} of all the other types mentioned below. This is useful
this function sets the customized spec or the saved custom spec. If when calling this function outside of Custom code. If @var{spec-type}
it is @code{face-defface-spec}, this function sets the default face is @code{customized-face} or @code{saved-face}, this function sets the
spec (the same one set by @code{defface}). If it is @code{reset}, customized spec or the saved custom spec, respectively. If it is
this function clears out all customization specs and override specs @code{face-defface-spec}, this function sets the default face spec
from @var{face} (in this case, the value of @var{spec} is ignored). (the same one set by @code{defface}). If it is @code{reset}, this
Any other value of @var{spec-type} is reserved for internal use. 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 @end defun
@node Attribute Functions @node Attribute Functions
......
...@@ -1667,7 +1667,7 @@ is given, in which case return its value instead." ...@@ -1667,7 +1667,7 @@ is given, in which case return its value instead."
face--attributes-unspecified))) face--attributes-unspecified)))
(defun face-spec-set (face spec &optional spec-type) (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. See `defface' for the format of SPEC.
The appearance of each face is controlled by its specs (set via 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 ...@@ -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 already one, and (re)calculates its attributes on existing
frames. frames.
The argument SPEC-TYPE determines which spec to set: The optional argument SPEC-TYPE determines which spec to set:
nil or `face-override-spec' means the override spec (which is nil, omitted or `face-override-spec' means the override spec,
usually what you want if calling this function outside of which overrides all the other types of spec mentioned below
Custom code); (this is usually what you want if calling this function
outside of Custom code);
`customized-face' or `saved-face' means the customized spec or `customized-face' or `saved-face' means the customized spec or
the saved custom spec; the saved custom spec;
`face-defface-spec' means the default spec `face-defface-spec' means the default spec
...@@ -1689,7 +1690,7 @@ The argument SPEC-TYPE determines which spec to set: ...@@ -1689,7 +1690,7 @@ The argument SPEC-TYPE determines which spec to set:
`reset' means to ignore SPEC, but clear the `customized-face' `reset' means to ignore SPEC, but clear the `customized-face'
and `face-override-spec' specs; and `face-override-spec' specs;
Any other value means not to set any spec, but to run the 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) (if (get face 'face-alias)
(setq face (get face 'face-alias))) (setq face (get face 'face-alias)))
;; Save SPEC to the relevant symbol property. ;; 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