Clarify documentation of a "face's font"

* doc/lispref/display.texi (Attribute Functions)
(Face Attributes): Clarify that the :font attribute of a face and
the font returned by 'face-font' are by default for ASCII
characters.  (Bug#53664)

diff --git a/doc/lispref/display.texi b/doc/lispref/display.texi
index 66823c6556797b8a22a073c3f158da04f7ef83e4..854aa06dbbd422a66d66176084831dd44e237eaa 100644 (file)
--- a/doc/lispref/display.texi
+++ b/doc/lispref/display.texi
@@ -2549,9 +2549,10 @@ used automatically to handle certain shades of gray.
 
 @item :font
 The font used to display the face.  Its value should be a font object
-or a fontset.  @xref{Low-Level Font}, for information about font
-objects, font specs, and font entities.  @xref{Fontsets}, for
-information about fontsets.
+or a fontset.  If it is a font object, it specifies the font to be
+used by the face for displaying ASCII characters.  @xref{Low-Level
+Font}, for information about font objects, font specs, and font
+entities.  @xref{Fontsets}, for information about fontsets.
 
 @anchor{face-font-attribute}
 When specifying this attribute using @code{set-face-attribute} or
@@ -2994,13 +2995,19 @@ return value is always specified, use a value of @code{default} for
 @var{inherit}.
 
 @defun face-font face &optional frame character
-This function returns the name of the font of face @var{face}.
+This function returns the name of the font used by the specified
+@var{face}.
 
 If the optional argument @var{frame} is specified, it returns the name
-of the font of @var{face} for that frame.  If @var{frame} is omitted or
-@code{nil}, the selected frame is used.  In the latter case, if the
-optional third argument @var{character} is supplied, it returns the font
-name used for @var{character}.
+of the font of @var{face} for that frame; @var{frame} defaults to the
+selected frame if it is @code{nil} or omitted.  If @var{frame} is
+@code{t}, the function reports on the font defaults for @var{face} to
+be used for new frames.
+
+By default, the returned font is for displaying ASCII characters, but
+if @var{frame} is anything but @code{t}, and the optional third
+argument @var{character} is supplied, the function returns the font
+name used by @var{face} for that character.
 @end defun
 
 @defun face-foreground face &optional frame inherit

diff --git a/src/xfaces.c b/src/xfaces.c
index dff5ae346de33e6f780514a8cdd79b0c05ad3f09..f7ee19195f4e4695400b4dd9ddd118419688a4b6 100644 (file)
--- a/src/xfaces.c
+++ b/src/xfaces.c
@@ -4168,9 +4168,9 @@ If the optional argument FRAME is given, report on face FACE in that frame.
 If FRAME is t, report on the defaults for face FACE (for new frames).
   The font default for a face is either nil, or a list
   of the form (bold), (italic) or (bold italic).
-If FRAME is omitted or nil, use the selected frame.  And, in this case,
-if the optional third argument CHARACTER is given,
-return the font name used for CHARACTER.  */)
+If FRAME is omitted or nil, use the selected frame.
+If FRAME is anything but t, and the optional third argument CHARACTER
+is given, return the font name used by FACE for CHARACTER on FRAME.  */)
   (Lisp_Object face, Lisp_Object frame, Lisp_Object character)
 {
   if (EQ (frame, Qt))