Commit 6175e34b authored by Chong Yidong's avatar Chong Yidong

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.

Fixes: debbugs:11225
parent d9857e53
2012-06-09 Chong Yidong <cyd@gnu.org>
* 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 <cyd@gnu.org> 2012-06-08 Chong Yidong <cyd@gnu.org>
* display.texi (Face Attributes): Font family does not accept * display.texi (Face Attributes): Font family does not accept
......
...@@ -2511,39 +2511,34 @@ Scale,,, emacs, The GNU Emacs Manual}). ...@@ -2511,39 +2511,34 @@ Scale,,, emacs, The GNU Emacs Manual}).
The value of this variable is an alist whose elements have the form The value of this variable is an alist whose elements have the form
@code{(@var{face} . @var{remapping})}. This causes Emacs to display @code{(@var{face} . @var{remapping})}. This causes Emacs to display
any text having the face @var{face} with @var{remapping}, rather than any text having the face @var{face} with @var{remapping}, rather than
the ordinary definition of @var{face}. @var{remapping} may be any the ordinary definition of @var{face}.
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 @var{remapping} may be any face specification suitable for a
which each element is either a face name or a property list @code{face} text property: either a face (i.e.@: a face name or a
(@pxref{Special Properties}). property list of attribute/value pairs), or a list of faces. For
details, see the description of the @code{face} text property in
@ref{Special 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 If @code{face-remapping-alist} is buffer-local, its local value takes
effect only within that buffer. effect only within that buffer.
Two points bear emphasizing: Note: face remapping is non-recursive. If @var{remapping} references
the same face name @var{face}, either directly or via the
@enumerate @code{:inherit} attribute of some other face in @var{remapping}, that
@item reference uses the normal definition of @var{face}. For instance, if
@var{remapping} serves as the complete specification for the remapped the @code{mode-line} face is remapped using this entry in
face---it replaces the normal definition of @var{face}, instead of @code{face-remapping-alist}:
modifying it.
@item
If @var{remapping} references the same face name @var{face}, either
directly or via the @code{:inherit} attribute of some other face in
@var{remapping}, that reference uses the normal definition of
@var{face}. 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}:
@example @example
(mode-line italic mode-line) (mode-line italic mode-line)
@end example @end example
@noindent @noindent
then the new definition of the @code{mode-line} face inherits from the 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{italic} face, and the @emph{normal} (non-remapped) definition of
@code{mode-line} face. @code{mode-line} face.
@end enumerate
@end defvar @end defvar
The following functions implement a higher-level interface to The following functions implement a higher-level interface to
......
...@@ -3004,7 +3004,11 @@ time you want to specify a particular attribute for certain text. ...@@ -3004,7 +3004,11 @@ time you want to specify a particular attribute for certain text.
@xref{Face Attributes}. @xref{Face Attributes}.
@item @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 @end itemize
Font Lock mode (@pxref{Font Lock Mode}) works in most buffers by Font Lock mode (@pxref{Font Lock Mode}) works in most buffers by
......
2012-06-09 Chong Yidong <cyd@gnu.org>
* 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 <monnier@iro.umontreal.ca> 2012-06-09 Stefan Monnier <monnier@iro.umontreal.ca>
* emacs-lisp/macroexp.el (macroexp--expand-all): Only autoload * emacs-lisp/macroexp.el (macroexp--expand-all): Only autoload
......
...@@ -109,14 +109,19 @@ The list structure of ENTRY may be destructively modified." ...@@ -109,14 +109,19 @@ The list structure of ENTRY may be destructively modified."
Return a cookie which can be used to delete this remapping with Return a cookie which can be used to delete this remapping with
`face-remap-remove-relative'. `face-remap-remove-relative'.
The remaining arguments, SPECS, should be either a list of face The remaining arguments, SPECS, should form a list of faces.
names, or a property list of face attribute/value pairs. The Each list element should be either a face name or a property list
remapping specified by SPECS takes effect alongside the of face attribute/value pairs. If more than one face is listed,
remappings from other calls to `face-remap-add-relative', as well that specifies an aggregate face, in the same way as in a `face'
as the normal definition of FACE (at lowest priority). This text property, except for possible priority changes noted below.
function tries to sort multiple remappings for the same face, so
that remappings specifying relative face attributes are applied The face remapping specified by SPECS takes effect alongside the
after remappings specifying absolute face attributes. 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 The base (lowest priority) remapping may be set to something
other than the normal definition of FACE via `face-remap-set-base'." other than the normal definition of FACE via `face-remap-set-base'."
...@@ -165,9 +170,11 @@ to apply on top of the normal definition of FACE." ...@@ -165,9 +170,11 @@ to apply on top of the normal definition of FACE."
(defun face-remap-set-base (face &rest specs) (defun face-remap-set-base (face &rest specs)
"Set the base remapping of FACE in the current buffer to SPECS. "Set the base remapping of FACE in the current buffer to SPECS.
This causes the remappings specified by `face-remap-add-relative' This causes the remappings specified by `face-remap-add-relative'
to apply on top of the face specification given by SPECS. SPECS to apply on top of the face specification given by SPECS.
should be either a list of face names, or a property list of face
attribute/value pairs. 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 If SPECS is empty, call `face-remap-reset-base' to use the normal
definition of FACE as the base remapping; note that this is definition of FACE as the base remapping; note that this is
...@@ -361,12 +368,14 @@ variable `buffer-face-mode-face' is used to display the buffer text." ...@@ -361,12 +368,14 @@ variable `buffer-face-mode-face' is used to display the buffer text."
;;;###autoload ;;;###autoload
(defun buffer-face-set (&rest specs) (defun buffer-face-set (&rest specs)
"Enable `buffer-face-mode', using face specs SPECS. "Enable `buffer-face-mode', using face specs SPECS.
SPECS can be any value suitable for the `face' text property, Each argument in SPECS should be a face, i.e. either a face name
including a face name, a list of face names, or a face-attribute or a property list of face attributes and values. If more than
If SPECS is nil, then `buffer-face-mode' is disabled. one face is listed, that specifies an aggregate face, like in a
`face' text property. If SPECS is nil or omitted, disable
This function will make the variable `buffer-face-mode-face' `buffer-face-mode'.
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"))) (interactive (list (read-face-name "Set buffer face")))
(while (and (consp specs) (null (cdr specs))) (while (and (consp specs) (null (cdr specs)))
(setq specs (car specs))) (setq specs (car specs)))
...@@ -378,8 +387,10 @@ buffer local, and set it to FACE." ...@@ -378,8 +387,10 @@ buffer local, and set it to FACE."
;;;###autoload ;;;###autoload
(defun buffer-face-toggle (&rest specs) (defun buffer-face-toggle (&rest specs)
"Toggle `buffer-face-mode', using face specs SPECS. "Toggle `buffer-face-mode', using face specs SPECS.
SPECS can be any value suitable for the `face' text property, Each argument in SPECS should be a face, i.e. either a face name
including a face name, a list of face names, or a face-attribute 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 If `buffer-face-mode' is already enabled, and is currently using
the face specs SPECS, then it is disabled; if buffer-face-mode is the face specs SPECS, then it is disabled; if buffer-face-mode is
...@@ -402,10 +413,12 @@ buffer local, and set it to SPECS." ...@@ -402,10 +413,12 @@ buffer local, and set it to SPECS."
ARG controls whether the mode is enabled or disabled, and is ARG controls whether the mode is enabled or disabled, and is
interpreted in the usual manner for minor-mode commands. interpreted in the usual manner for minor-mode commands.
SPECS can be any value suitable for the `face' text property, SPECS can be any value suitable for a `face' text property,
including a face name, a list of face names, or a face-attribute 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 This is a wrapper function which calls `buffer-face-set' or
`buffer-face-toggle' (depending on ARG), and prints a status `buffer-face-toggle' (depending on ARG), and prints a status
......
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