procyberian/emacs
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

Doc improvements for face remapping.

Browse source 
* 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
This commit is contained in:
Chong Yidong 2012-06-09 14:26:46 +08:00
parent d9857e534b
commit 6175e34b61
5 changed files with 68 additions and 43 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

7
doc/lispref/ChangeLog
View file

@ -1,3 +1,10 @@
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>
* display.texi (Face Attributes): Font family does not accept

37
doc/lispref/display.texi
View file

@ -2511,39 +2511,34 @@ Scale,,, emacs, The GNU Emacs Manual}).
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}.
@var{remapping} may be any face specification suitable for a
@code{face} 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
@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
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
@code{: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
@code{face-remapping-alist}:
@enumerate
@item
@var{remapping} serves as the complete specification for the remapped
face---it replaces the normal definition of @var{face}, instead of
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
(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.
@end enumerate
@end defvar
The following functions implement a higher-level interface to

6
doc/lispref/text.texi
View file

@ -3004,7 +3004,11 @@ time you want to specify a particular attribute for certain text.
@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

6
lisp/ChangeLog
View file

@ -1,3 +1,9 @@
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>
* emacs-lisp/macroexp.el (macroexp--expand-all): Only autoload

55
lisp/face-remap.el
View file

@ -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
`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 @@ to apply on top of the normal definition of FACE."
(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 @@ variable `buffer-face-mode-face' is used to display the buffer text."
;;;###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 @@ buffer local, and set it to FACE."
;;;###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 @@ buffer local, and set it to SPECS."
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