[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[Emacs-diffs] master 187a71d: Clarify documentation of 'face-spec-set'
From: |
Eli Zaretskii |
Subject: |
[Emacs-diffs] master 187a71d: Clarify documentation of 'face-spec-set' |
Date: |
Sat, 10 Jun 2017 05:09:42 -0400 (EDT) |
branch: master
commit 187a71df596a331a23bf86ee314c12035f42aff2
Author: Eli Zaretskii <address@hidden>
Commit: Eli Zaretskii <address@hidden>
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)
---
doc/lispref/display.texi | 24 ++++++++++++++----------
lisp/faces.el | 13 +++++++------
2 files changed, 21 insertions(+), 16 deletions(-)
diff --git a/doc/lispref/display.texi b/doc/lispref/display.texi
index aa75dcf..4a895f7 100644
--- a/doc/lispref/display.texi
+++ b/doc/lispref/display.texi
@@ -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
address@hidden or @code{face-override-spec}, this function sets the
address@hidden spec}, which overrides over all other face specs on
address@hidden 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
address@hidden 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
address@hidden, 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
address@hidden (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
address@hidden itself and recalculate its attributes, as described above.
@end defun
@node Attribute Functions
diff --git a/lisp/faces.el b/lisp/faces.el
index 1f9b397..9a8a134 100644
--- a/lisp/faces.el
+++ b/lisp/faces.el
@@ -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.
[Prev in Thread] |
Current Thread |
[Next in Thread] |
- [Emacs-diffs] master 187a71d: Clarify documentation of 'face-spec-set',
Eli Zaretskii <=