Commit bacb0e77 authored by Chong Yidong's avatar Chong Yidong
Browse files

Doc fixes for face functions.

* faces.el (face-spec-set):
* cus-face.el (custom-theme-set-faces, custom-set-faces):
* custom.el (defface): Doc fixes.

Fixes: debbugs:16203
parent c2790aec
2013-12-21 Chong Yidong <cyd@gnu.org>
* faces.el (face-spec-set):
* cus-face.el (custom-theme-set-faces, custom-set-faces):
* custom.el (defface): Doc fixes (Bug#16203).
2013-12-21 Chong Yidong <cyd@gnu.org> 2013-12-21 Chong Yidong <cyd@gnu.org>
* indent.el (indent-rigidly-map): Add docstring, and move commands * indent.el (indent-rigidly-map): Add docstring, and move commands
......
...@@ -285,47 +285,48 @@ If FRAME is nil, use the global defaults for FACE." ...@@ -285,47 +285,48 @@ If FRAME is nil, use the global defaults for FACE."
;;; Initializing. ;;; Initializing.
(defun custom-set-faces (&rest args) (defun custom-set-faces (&rest args)
"Initialize faces according to user preferences. "Apply a list of face specs for user customizations.
This associates the settings with the `user' theme. This works by calling `custom-theme-set-faces' for the `user'
theme, a special theme referring to settings made via Customize.
The arguments should be a list where each entry has the form: The arguments should be a list where each entry has the form:
(FACE SPEC [NOW [COMMENT]]) (FACE SPEC [NOW [COMMENT]])
SPEC is stored as the saved value for FACE, as well as the value for the See the documentation of `custom-theme-set-faces' for details."
`user' theme. The `user' theme is one of the default themes known to Emacs.
See `custom-known-themes' for more information on the known themes.
See `custom-theme-set-faces' for more information on the interplay
between themes and faces.
See `defface' for the format of SPEC.
If NOW is present and non-nil, FACE is created now, according to SPEC.
COMMENT is a string comment about FACE."
(apply 'custom-theme-set-faces 'user args)) (apply 'custom-theme-set-faces 'user args))
(defun custom-theme-set-faces (theme &rest args) (defun custom-theme-set-faces (theme &rest args)
"Initialize faces for theme THEME. "Apply a list of face specs associated with theme THEME.
The arguments should be a list where each entry has the form: THEME should be a theme name (a symbol). The special theme named
`user' refers to user settings applied via Customize.
The remaining ARGS should be a list where each entry is a list of
the form:
(FACE SPEC [NOW [COMMENT]]) (FACE SPEC [NOW [COMMENT]])
SPEC is stored as the saved value for FACE, as well as the value for the FACE should be a face name (a symbol). If FACE is a face alias,
`user' theme. The `user' theme is one of the default themes known to Emacs. the setting refers to the parent face.
See `custom-known-themes' for more information on the known themes.
See `custom-theme-set-faces' for more information on the interplay
between themes and faces.
See `defface' for the format of SPEC.
If NOW is present and non-nil, FACE is created now, according to SPEC. SPEC should be a face spec. For details, see `defface'.
COMMENT is a string comment about FACE.
NOW, if present and non-nil, forces the face settings to take
immediate effect in the Emacs display; in particular, FACE is
initialized as a face if it is not yet one. If NOW is omitted or
nil, the caller is responsible for making the settings take
effect later, by calling `custom-theme-recalc-face' or
`face-spec-recalc'.
Several properties of THEME and FACE are used in the process: COMMENT is a string comment about FACE.
If THEME property `theme-immediate' is non-nil, this is equivalent of This function works by calling `custom-push-theme' to record each
providing the NOW argument to all faces in the argument list: FACE is SPEC in each FACE's `theme-face' property, and in THEME's
created now. `theme-settings' property. If FACE has not already been
customized, it also stores SPEC in the `saved-face' property.
SPEC itself is saved in FACE property `saved-face' and it is stored in If THEME has a non-nil `theme-immediate' property, this is
FACE's list property `theme-face' \(using `custom-push-theme')." equivalent to providing the NOW argument to all faces in the
argument list."
(custom-check-theme theme) (custom-check-theme theme)
(let ((immediate (get theme 'theme-immediate))) (let ((immediate (get theme 'theme-immediate)))
(dolist (entry args) (dolist (entry args)
......
...@@ -353,7 +353,7 @@ FACE does not need to be quoted. ...@@ -353,7 +353,7 @@ FACE does not need to be quoted.
Third argument DOC is the face documentation. Third argument DOC is the face documentation.
If FACE has been set with `custom-set-faces', set the face If FACE has been set with `custom-theme-set-faces', set the face
attributes as specified by that function, otherwise set the face attributes as specified by that function, otherwise set the face
attributes according to SPEC. attributes according to SPEC.
...@@ -361,7 +361,7 @@ The remaining arguments should have the form [KEYWORD VALUE]... ...@@ -361,7 +361,7 @@ The remaining arguments should have the form [KEYWORD VALUE]...
For a list of valid keywords, see the common keywords listed in For a list of valid keywords, see the common keywords listed in
`defcustom'. `defcustom'.
SPEC should be an alist of the form SPEC should be a \"face spec\", i.e., an alist of the form
((DISPLAY . ATTS)...) ((DISPLAY . ATTS)...)
......
...@@ -1576,7 +1576,11 @@ See `defface' for the format of SPEC. ...@@ -1576,7 +1576,11 @@ See `defface' for the format of SPEC.
The appearance of each face is controlled by its spec, and by the The appearance of each face is controlled by its spec, and by the
internal face attributes (which can be frame-specific and can be internal face attributes (which can be frame-specific and can be
set via `set-face-attribute'). set via `set-face-attribute'). This function sets the former.
In addition to setting the face spec, this function defines FACE
as a valid face name if it is not already one, and (re)calculates
the face's attributes on existing frames.
The argument SPEC-TYPE determines which spec to set: The argument SPEC-TYPE determines which spec to set:
nil or `face-override-spec' means the override spec (which is nil or `face-override-spec' means the override spec (which is
...@@ -1589,11 +1593,7 @@ The argument SPEC-TYPE determines which spec to set: ...@@ -1589,11 +1593,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 its other effects."
In addition to setting the face spec, this function defines FACE
as a valid face name if it is not already one, and (re)calculates
the face's attributes on existing frames."
(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