[Top][All Lists]
[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[Emacs-diffs] /srv/bzr/emacs/trunk r108534: Doc improvements for face re
From: |
Chong Yidong |
Subject: |
[Emacs-diffs] /srv/bzr/emacs/trunk r108534: Doc improvements for face remapping. |
Date: |
Sat, 09 Jun 2012 14:26:46 +0800 |
User-agent: |
Bazaar (2.5.0) |
------------------------------------------------------------
revno: 108534
fixes bug: http://debbugs.gnu.org/11225
committer: Chong Yidong <address@hidden>
branch nick: trunk
timestamp: Sat 2012-06-09 14:26:46 +0800
message:
Doc improvements for face remapping.
* face-remap.el (face-remap-add-relative, face-remap-set-base)
(buffer-face-set, buffer-face-toggle, buffer-face-mode-invoke):
Doc fixes.
* doc/lispref/display.texi (Face Remapping): Minor clarification.
* doc/lispref/text.texi (Special Properties): Clarify the meaning of a
list of faces in the `face' property.
modified:
doc/lispref/ChangeLog
doc/lispref/display.texi
doc/lispref/text.texi
lisp/ChangeLog
lisp/face-remap.el
=== modified file 'doc/lispref/ChangeLog'
--- a/doc/lispref/ChangeLog 2012-06-08 16:39:49 +0000
+++ b/doc/lispref/ChangeLog 2012-06-09 06:26:46 +0000
@@ -1,3 +1,10 @@
+2012-06-09 Chong Yidong <address@hidden>
+
+ * text.texi (Special Properties): Clarify the meaning of a list of
+ faces in the `face' property.
+
+ * display.texi (Face Remapping): Minor clarification.
+
2012-06-08 Chong Yidong <address@hidden>
* display.texi (Face Attributes): Font family does not accept
=== modified file 'doc/lispref/display.texi'
--- a/doc/lispref/display.texi 2012-06-08 16:39:49 +0000
+++ b/doc/lispref/display.texi 2012-06-09 06:26:46 +0000
@@ -2511,39 +2511,34 @@
The value of this variable is an alist whose elements have the form
@code{(@var{face} . @var{remapping})}. This causes Emacs to display
any text having the face @var{face} with @var{remapping}, rather than
-the ordinary definition of @var{face}. @var{remapping} may be any
-face specification suitable for a @code{face} text property: either a
-face name, or a property list of attribute/value pairs, or a list in
-which each element is either a face name or a property list
-(@pxref{Special Properties}).
+the ordinary definition of @var{face}.
+
address@hidden may be any face specification suitable for a
address@hidden text property: either a face (i.e.@: a face name or a
+property list of attribute/value pairs), or a list of faces. For
+details, see the description of the @code{face} text property in
address@hidden Properties}. @var{remapping} serves as the complete
+specification for the remapped face---it replaces the normal
+definition of @var{face}, instead of modifying it.
If @code{face-remapping-alist} is buffer-local, its local value takes
effect only within that buffer.
-Two points bear emphasizing:
-
address@hidden
address@hidden
address@hidden serves as the complete specification for the remapped
-face---it replaces the normal definition of @var{face}, instead of
-modifying it.
-
address@hidden
-If @var{remapping} references the same face name @var{face}, either
-directly or via the @code{:inherit} attribute of some other face in
address@hidden, that reference uses the normal definition of
address@hidden In other words, the remapping cannot be recursive.
-
-For instance, if the @code{mode-line} face is remapped using this
-entry in @code{face-remapping-alist}:
+Note: face remapping is non-recursive. If @var{remapping} references
+the same face name @var{face}, either directly or via the
address@hidden:inherit} attribute of some other face in @var{remapping}, that
+reference uses the normal definition of @var{face}. For instance, if
+the @code{mode-line} face is remapped using this entry in
address@hidden:
+
@example
(mode-line italic mode-line)
@end example
+
@noindent
then the new definition of the @code{mode-line} face inherits from the
@code{italic} face, and the @emph{normal} (non-remapped) definition of
@code{mode-line} face.
address@hidden enumerate
@end defvar
The following functions implement a higher-level interface to
=== modified file 'doc/lispref/text.texi'
--- a/doc/lispref/text.texi 2012-05-27 01:34:14 +0000
+++ b/doc/lispref/text.texi 2012-06-09 06:26:46 +0000
@@ -3004,7 +3004,11 @@
@xref{Face Attributes}.
@item
-A list, where each element uses one of the two forms listed above.
+A list of faces. This specifies a face which is an aggregate of the
+attributes of each of the listed faces. Faces occurring earlier in
+the list have higher priority. Each list element must have one of the
+two above forms (i.e.@: either a face name or a property list of face
+attributes).
@end itemize
Font Lock mode (@pxref{Font Lock Mode}) works in most buffers by
=== modified file 'lisp/ChangeLog'
--- a/lisp/ChangeLog 2012-06-09 02:26:47 +0000
+++ b/lisp/ChangeLog 2012-06-09 06:26:46 +0000
@@ -1,3 +1,9 @@
+2012-06-09 Chong Yidong <address@hidden>
+
+ * face-remap.el (face-remap-add-relative, face-remap-set-base)
+ (buffer-face-set, buffer-face-toggle, buffer-face-mode-invoke):
+ Doc fixes (Bug#11225).
+
2012-06-09 Stefan Monnier <address@hidden>
* emacs-lisp/macroexp.el (macroexp--expand-all): Only autoload
=== modified file 'lisp/face-remap.el'
--- a/lisp/face-remap.el 2012-05-05 02:50:20 +0000
+++ b/lisp/face-remap.el 2012-06-09 06:26:46 +0000
@@ -109,14 +109,19 @@
Return a cookie which can be used to delete this remapping with
`face-remap-remove-relative'.
-The remaining arguments, SPECS, should be either a list of face
-names, or a property list of face attribute/value pairs. The
-remapping specified by SPECS takes effect alongside the
-remappings from other calls to `face-remap-add-relative', as well
-as the normal definition of FACE (at lowest priority). This
-function tries to sort multiple remappings for the same face, so
-that remappings specifying relative face attributes are applied
-after remappings specifying absolute face attributes.
+The remaining arguments, SPECS, should form a list of faces.
+Each list element should be either a face name or a property list
+of face attribute/value pairs. If more than one face is listed,
+that specifies an aggregate face, in the same way as in a `face'
+text property, except for possible priority changes noted below.
+
+The face remapping specified by SPECS takes effect alongside the
+remappings from other calls to `face-remap-add-relative' for the
+same FACE, as well as the normal definition of FACE (at lowest
+priority). This function tries to sort multiple remappings for
+the same face, so that remappings specifying relative face
+attributes are applied after remappings specifying absolute face
+attributes.
The base (lowest priority) remapping may be set to something
other than the normal definition of FACE via `face-remap-set-base'."
@@ -165,9 +170,11 @@
(defun face-remap-set-base (face &rest specs)
"Set the base remapping of FACE in the current buffer to SPECS.
This causes the remappings specified by `face-remap-add-relative'
-to apply on top of the face specification given by SPECS. SPECS
-should be either a list of face names, or a property list of face
-attribute/value pairs.
+to apply on top of the face specification given by SPECS.
+
+The remaining arguments, SPECS, should form a list of faces.
+Each list element should be either a face name or a property list
+of face attribute/value pairs, like in a `face' text property.
If SPECS is empty, call `face-remap-reset-base' to use the normal
definition of FACE as the base remapping; note that this is
@@ -361,12 +368,14 @@
;;;###autoload
(defun buffer-face-set (&rest specs)
"Enable `buffer-face-mode', using face specs SPECS.
-SPECS can be any value suitable for the `face' text property,
-including a face name, a list of face names, or a face-attribute
-If SPECS is nil, then `buffer-face-mode' is disabled.
+Each argument in SPECS should be a face, i.e. either a face name
+or a property list of face attributes and values. If more than
+one face is listed, that specifies an aggregate face, like in a
+`face' text property. If SPECS is nil or omitted, disable
+`buffer-face-mode'.
-This function will make the variable `buffer-face-mode-face'
-buffer local, and set it to FACE."
+This function makes the variable `buffer-face-mode-face' buffer
+local, and sets it to FACE."
(interactive (list (read-face-name "Set buffer face")))
(while (and (consp specs) (null (cdr specs)))
(setq specs (car specs)))
@@ -378,8 +387,10 @@
;;;###autoload
(defun buffer-face-toggle (&rest specs)
"Toggle `buffer-face-mode', using face specs SPECS.
-SPECS can be any value suitable for the `face' text property,
-including a face name, a list of face names, or a face-attribute
+Each argument in SPECS should be a face, i.e. either a face name
+or a property list of face attributes and values. If more than
+one face is listed, that specifies an aggregate face, like in a
+`face' text property.
If `buffer-face-mode' is already enabled, and is currently using
the face specs SPECS, then it is disabled; if buffer-face-mode is
@@ -402,10 +413,12 @@
ARG controls whether the mode is enabled or disabled, and is
interpreted in the usual manner for minor-mode commands.
-SPECS can be any value suitable for the `face' text property,
-including a face name, a list of face names, or a face-attribute
+SPECS can be any value suitable for a `face' text property,
+including a face name, a plist of face attributes and values, or
+a list of faces.
-If INTERACTIVE is non-nil, a message will be displayed describing the result.
+If INTERACTIVE is non-nil, display a message describing the
+result.
This is a wrapper function which calls `buffer-face-set' or
`buffer-face-toggle' (depending on ARG), and prints a status
[Prev in Thread] |
Current Thread |
[Next in Thread] |
- [Emacs-diffs] /srv/bzr/emacs/trunk r108534: Doc improvements for face remapping.,
Chong Yidong <=