From: Chong Yidong Date: Sat, 21 Dec 2013 13:44:20 +0000 (+0800) Subject: Doc fixes for face functions. X-Git-Tag: emacs-24.3.90~173^2^2~42^2~45^2~387^2~275 X-Git-Url: https://code.delx.au/gnu-emacs/commitdiff_plain/bacb0e7791b68b1b0a254c09910d666087a386b5 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 --- diff --git a/lisp/ChangeLog b/lisp/ChangeLog index fc42cbedca..0e452aa668 100644 --- a/lisp/ChangeLog +++ b/lisp/ChangeLog @@ -1,3 +1,9 @@ +2013-12-21 Chong Yidong + + * 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 * indent.el (indent-rigidly-map): Add docstring, and move commands diff --git a/lisp/cus-face.el b/lisp/cus-face.el index e1f1668d1a..ecf7bd3d84 100644 --- a/lisp/cus-face.el +++ b/lisp/cus-face.el @@ -285,47 +285,48 @@ If FRAME is nil, use the global defaults for FACE." ;;; Initializing. (defun custom-set-faces (&rest args) - "Initialize faces according to user preferences. -This associates the settings with the `user' theme. + "Apply a list of face specs for user customizations. +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: (FACE SPEC [NOW [COMMENT]]) -SPEC is stored as the saved value for FACE, as well as the value for the -`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." +See the documentation of `custom-theme-set-faces' for details." (apply 'custom-theme-set-faces 'user args)) (defun custom-theme-set-faces (theme &rest args) - "Initialize faces for theme THEME. -The arguments should be a list where each entry has the form: + "Apply a list of face specs associated with theme THEME. +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]]) -SPEC is stored as the saved value for FACE, as well as the value for the -`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. +FACE should be a face name (a symbol). If FACE is a face alias, +the setting refers to the parent face. -If NOW is present and non-nil, FACE is created now, according to SPEC. -COMMENT is a string comment about FACE. +SPEC should be a face spec. For details, see `defface'. + +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 -providing the NOW argument to all faces in the argument list: FACE is -created now. +This function works by calling `custom-push-theme' to record each +SPEC in each FACE's `theme-face' property, and in THEME's +`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 -FACE's list property `theme-face' \(using `custom-push-theme')." +If THEME has a non-nil `theme-immediate' property, this is +equivalent to providing the NOW argument to all faces in the +argument list." (custom-check-theme theme) (let ((immediate (get theme 'theme-immediate))) (dolist (entry args) diff --git a/lisp/custom.el b/lisp/custom.el index 43775a1691..8b675c4a74 100644 --- a/lisp/custom.el +++ b/lisp/custom.el @@ -353,7 +353,7 @@ FACE does not need to be quoted. 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 according to SPEC. @@ -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 `defcustom'. -SPEC should be an alist of the form +SPEC should be a \"face spec\", i.e., an alist of the form ((DISPLAY . ATTS)...) diff --git a/lisp/faces.el b/lisp/faces.el index 4d4d064a1f..403cf8b1b9 100644 --- a/lisp/faces.el +++ b/lisp/faces.el @@ -1576,7 +1576,11 @@ See `defface' for the format of SPEC. The appearance of each face is controlled by its spec, and by the 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: nil or `face-override-spec' means the override spec (which is @@ -1589,11 +1593,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. - -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." +function for its other effects." (if (get face 'face-alias) (setq face (get face 'face-alias))) ;; Save SPEC to the relevant symbol property.