mirrors/emacs
1
Fork 0
mirror of git://git.sv.gnu.org/emacs.git synced 2025-12-06 06:20:55 -08:00
Code Issues Projects Releases Wiki Activity

Clarify use of ':font' in face-remapping functions

Browse source 
* lisp/face-remap.el (face-remap-add-relative)
(face-remap-set-base, buffer-face-set, buffer-face-toggle)
(buffer-face-mode-invoke): Clarify how to use ':font' in face
attribute lists.  (Bug#79906)
This commit is contained in:
Eli Zaretskii 2025-11-29 11:25:02 +02:00
parent 5c0d2ca79a
commit a74b693683
1 changed files with 20 additions and 0 deletions
Download patch file Download diff file Expand all files Collapse all files

20
lisp/face-remap.el
View file

@ -122,6 +122,10 @@ 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' that specifies an aggregate face, in the same way as in a `face'
text property, except for possible priority changes noted below. text property, except for possible priority changes noted below.
If a face property list specifies `:font', the value should be
either a font-spec object or the return value of `font-face-attributes'
called with a font object, font spec, or font entity.
The face remapping specified by SPECS takes effect alongside the The face remapping specified by SPECS takes effect alongside the
remappings from other calls to `face-remap-add-relative' for the remappings from other calls to `face-remap-add-relative' for the
same FACE, as well as the normal definition of FACE (at lowest same FACE, as well as the normal definition of FACE (at lowest
@ -192,6 +196,10 @@ The remaining arguments, SPECS, specify the base of the remapping.
Each one of SPECS should be either a face name or a property list Each one of SPECS should be either a face name or a property list
of face attribute/value pairs, like in a `face' text property. of face attribute/value pairs, like in a `face' text property.
If a face property list specifies `:font', the value should be
either a font-spec object or the return value of `font-face-attributes'
called with a font object, font spec, or font entity.
If SPECS is empty or a single face `eq' to FACE, call `face-remap-reset-base' If SPECS is empty or a single face `eq' to FACE, call `face-remap-reset-base'
to use the normal definition of FACE as the base remapping; note that to use the normal definition of FACE as the base remapping; note that
this is different from SPECS containing a single value nil, which means this is different from SPECS containing a single value nil, which means
@ -572,6 +580,10 @@ one face is listed, that specifies an aggregate face, like in a
`face' text property. If SPECS is nil or omitted, disable `face' text property. If SPECS is nil or omitted, disable
`buffer-face-mode'. `buffer-face-mode'.
If a face property list specifies `:font', the value should be
either a font-spec object or the return value of `font-face-attributes'
called with a font object, font spec, or font entity.
This function makes the variable `buffer-face-mode-face' buffer This function makes the variable `buffer-face-mode-face' buffer
local, and sets it to FACE." local, and sets it to FACE."
(interactive (list (read-face-name "Set buffer face" (face-at-point t)))) (interactive (list (read-face-name "Set buffer face" (face-at-point t))))
@ -590,6 +602,10 @@ or a property list of face attributes and values. If more than
one face is listed, that specifies an aggregate face, like in a one face is listed, that specifies an aggregate face, like in a
`face' text property. `face' text property.
If a face property list specifies `:font', the value should be
either a font-spec object or the return value of `font-face-attributes'
called with a font object, font spec, or font entity.
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' the face specs SPECS, then it is disabled; if `buffer-face-mode'
is disabled, or is enabled and currently displaying some other is disabled, or is enabled and currently displaying some other
@ -615,6 +631,10 @@ SPECS can be any value suitable for a `face' text property,
including a face name, a plist of face attributes and values, including a face name, a plist of face attributes and values,
or a list of faces. or a list of faces.
If a face property list specifies `:font', the value should be
either a font-spec object or the return value of `font-face-attributes'
called with a font object, font spec, or font entity.
If INTERACTIVE is non-nil, display a message describing the If INTERACTIVE is non-nil, display a message describing the
result. result.