mirror/emacs
1
0
Fork 0
mirror of https://git.savannah.gnu.org/git/emacs.git synced 2024-11-25 07:28:20 +00:00
Code Issues Releases Activity

Doc fixes for face functions.

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

Fixes: debbugs:16203
This commit is contained in:
Chong Yidong 2013-12-21 21:44:20 +08:00
parent c2790aecc8
commit bacb0e7791
4 changed files with 42 additions and 35 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

6
lisp/ChangeLog
View File

@ -1,3 +1,9 @@
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>
* indent.el (indent-rigidly-map): Add docstring, and move commands

55
lisp/cus-face.el
View File

@ -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.
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'.
If NOW is present and non-nil, FACE is created now, according to SPEC.
COMMENT is a string comment about FACE.
Several properties of THEME and FACE are used in the process:
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.
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.
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)

4
lisp/custom.el
View File

@ -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)...)

12
lisp/faces.el
View File

@ -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.