From a74b69368353f644c245cd8e9ff443eaa3db4e6c Mon Sep 17 00:00:00 2001
From: Eli Zaretskii <eliz@gnu.org>
Date: Sat, 29 Nov 2025 11:25:02 +0200
Subject: [PATCH] Clarify use of ':font' in face-remapping functions

* 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)
---
 lisp/face-remap.el | 20 ++++++++++++++++++++
 1 file changed, 20 insertions(+)

diff --git a/lisp/face-remap.el b/lisp/face-remap.el
index bd8ead32127..7de0995f3d8 100644
--- a/lisp/face-remap.el
+++ b/lisp/face-remap.el
@@ -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'
 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
 remappings from other calls to `face-remap-add-relative' for the
 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
 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'
 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
@@ -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
 `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
 local, and sets it to FACE."
   (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
 `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
 the face specs SPECS, then it is disabled; if `buffer-face-mode'
 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,
 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
 result.