[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[Emacs-diffs] trunk r115662: Doc fixes for face functions.
From: |
Chong Yidong |
Subject: |
[Emacs-diffs] trunk r115662: Doc fixes for face functions. |
Date: |
Sat, 21 Dec 2013 13:44:41 +0000 |
User-agent: |
Bazaar (2.6b2) |
------------------------------------------------------------
revno: 115662
revision-id: address@hidden
parent: address@hidden
fixes bug: http://debbugs.gnu.org/16203
committer: Chong Yidong <address@hidden>
branch nick: trunk
timestamp: Sat 2013-12-21 21:44:20 +0800
message:
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.
modified:
lisp/ChangeLog changelog-20091113204419-o5vbwnq5f7feedwu-1432
lisp/cus-face.el cusface.el-20091113204419-o5vbwnq5f7feedwu-1092
lisp/custom.el custom.el-20091113204419-o5vbwnq5f7feedwu-1093
lisp/faces.el faces.el-20091113204419-o5vbwnq5f7feedwu-562
=== modified file 'lisp/ChangeLog'
--- a/lisp/ChangeLog 2013-12-21 08:37:08 +0000
+++ b/lisp/ChangeLog 2013-12-21 13:44:20 +0000
@@ -1,5 +1,11 @@
2013-12-21 Chong Yidong <address@hidden>
+ * 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 <address@hidden>
+
* indent.el (indent-rigidly-map): Add docstring, and move commands
into named functions.
(indent-rigidly-left, indent-rigidly-right)
=== modified file 'lisp/cus-face.el'
--- a/lisp/cus-face.el 2013-01-02 16:13:04 +0000
+++ b/lisp/cus-face.el 2013-12-21 13:44:20 +0000
@@ -285,47 +285,48 @@
;;; 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.
-
-If NOW is present and non-nil, FACE is created now, according to 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'.
+
COMMENT is a string comment about FACE.
-Several properties of THEME and FACE are used in the process:
-
-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')."
+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 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)
=== modified file 'lisp/custom.el'
--- a/lisp/custom.el 2013-12-18 14:54:24 +0000
+++ b/lisp/custom.el 2013-12-21 13:44:20 +0000
@@ -353,7 +353,7 @@
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 @@
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)...)
=== modified file 'lisp/faces.el'
--- a/lisp/faces.el 2013-12-20 23:06:17 +0000
+++ b/lisp/faces.el 2013-12-21 13:44:20 +0000
@@ -1576,7 +1576,11 @@
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 @@
`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.
[Prev in Thread] |
Current Thread |
[Next in Thread] |
- [Emacs-diffs] trunk r115662: Doc fixes for face functions.,
Chong Yidong <=