Improve documentation of 'set-face-font'

* lisp/faces.el (set-face-font):
* doc/emacs/frames.texi (Fonts):
* doc/lispref/display.texi (Face Attributes)
(Attribute Functions): Clarify and correct the documentation
of set-face-font and related descriptions of font
specifications.  (Bug#14647)

3 files changed, 40 insertions, 23 deletions

diff --git a/doc/emacs/frames.texi b/doc/emacs/frames.texi
index cac1f7fea6d..091c011fb96 100644
--- a/doc/emacs/frames.texi
+++ b/doc/emacs/frames.texi
@@ -592,9 +592,9 @@ command can be helpful.  It describes the character at point, and
 names the font that it's rendered in.
 
 @cindex fontconfig
-  On X, there are four different ways to express a font name.  The
-first is to use a @dfn{Fontconfig pattern}.  Fontconfig patterns have
-the following form:
+  There are four different ways to express a font name.  The first is
+to use a @dfn{Fontconfig pattern}.  Fontconfig patterns have the
+following form:
 
 @example
 @var{fontname}[-@var{fontsize}][:@var{name1}=@var{values1}][:@var{name2}=@var{values2}]...
@@ -650,6 +650,10 @@ For a more detailed description of Fontconfig patterns, see the
 Fontconfig manual, which is distributed with Fontconfig and available
 online at @url{https://fontconfig.org/fontconfig-user.html}.
 
+On MS-Windows, only the subset of the form
+@var{fontname}[-@var{fontsize}] is supported for all fonts; the full
+Fontconfig pattern might not work for all of them.
+
 @cindex GTK font pattern
   The second way to specify a font is to use a @dfn{GTK font pattern}.
 These have the syntax
@@ -685,12 +689,15 @@ Monospace 12
 Monospace Bold Italic 12
 @end example
 
+On MS-Windows, only the subset @var{fontname} is supported.
+
 @cindex XLFD
 @cindex X Logical Font Description
   The third way to specify a font is to use an @dfn{XLFD} (@dfn{X
 Logical Font Description}).  This is the traditional method for
-specifying fonts under X@.  Each XLFD consists of fourteen words or
-numbers, separated by dashes, like this:
+specifying fonts under X, and is also supported on MS-Windows.  Each
+XLFD consists of fourteen words or numbers, separated by dashes, like
+this:
 
 @example
 -misc-fixed-medium-r-semicondensed--13-*-*-*-c-60-iso8859-1
@@ -774,6 +781,8 @@ equivalent to
 -misc-fixed-medium-r-semicondensed--13-*-*-*-c-60-iso8859-1
 @end example
 
+This form is not supported on MS-Windows.
+
 @cindex client-side fonts
 @cindex server-side fonts
   On X, Emacs recognizes two types of fonts: @dfn{client-side} fonts,
diff --git a/doc/lispref/display.texi b/doc/lispref/display.texi
index 29abc0a9f27..95f9cc15a8b 100644
--- a/doc/lispref/display.texi
+++ b/doc/lispref/display.texi
@@ -2466,16 +2466,18 @@ or a fontset.  @xref{Low-Level Font}, for information about font
 objects, font specs, and font entities.  @xref{Fontsets}, for
 information about fontsets.
 
-When specifying this attribute using @code{set-face-attribute}
-(@pxref{Attribute Functions}), you may also supply a font spec, a font
-entity, or a string.  Emacs converts such values to an appropriate
-font object, and stores that font object as the actual attribute
-value.  If you specify a string, the contents of the string should be
-a font name (@pxref{Fonts,,, emacs, The GNU Emacs Manual}); if the
-font name is an XLFD containing wildcards, Emacs chooses the first
-font matching those wildcards.  Specifying this attribute also changes
-the values of the @code{:family}, @code{:foundry}, @code{:width},
-@code{:height}, @code{:weight}, and @code{:slant} attributes.
+@anchor{face-font-attribute}
+When specifying this attribute using @code{set-face-attribute} or
+@code{set-face-font} (@pxref{Attribute Functions}), you may also
+supply a font spec, a font entity, or a string.  Emacs converts such
+values to an appropriate font object, and stores that font object as
+the actual attribute value.  If you specify a string, the contents of
+the string should be a font name (@pxref{Fonts,,, emacs, The GNU Emacs
+Manual}); if the font name is an XLFD containing wildcards, Emacs
+chooses the first font matching those wildcards.  Specifying this
+attribute also changes the values of the @code{:family},
+@code{:foundry}, @code{:width}, @code{:height}, @code{:weight}, and
+@code{:slant} attributes.
 
 @cindex inheritance, for faces
 @item :inherit
@@ -2834,10 +2836,13 @@ This sets the @code{:stipple} attribute of @var{face} to
 
 @deffn Command set-face-font face font &optional frame
 Change the font-related attributes of @var{face} to those of
-@var{font} (a string).  This sets the attributes @code{:family},
-@code{:foundry}, @code{:width}, @code{:height}, @code{:weight}, and
-@code{:slant}.  If @var{frame} is non-@code{nil}, only change the
-attributes on the specified frame.
+@var{font} (a string or a font object).  @xref{face-font-attribute},
+for the supported formats of the @var{font} argument.  This function
+sets the attribute @code{:font} of the face, and indirectly also the
+@code{:family}, @code{:foundry}, @code{:width}, @code{:height},
+@code{:weight}, and @code{:slant} attributes, as defined by the font.
+If @var{frame} is non-@code{nil}, only change the attributes on the
+specified frame.
 @end deffn
 
 @defun set-face-bold face bold-p &optional frame
diff --git a/lisp/faces.el b/lisp/faces.el
index 75753ecefc9..dc5bcca7609 100644
--- a/lisp/faces.el
+++ b/lisp/faces.el
@@ -887,10 +887,13 @@ Use `set-face-attribute' for finer control of font weight and slant."
 
 
 (defun set-face-font (face font &optional frame)
-  "Change font-related attributes of FACE to those of FONT (a string).
-The format of the font varies based on the font system in used,
-but it can commonly be an X logical font description (XLFD)
-string, or a simpler XFD string like \"courier:size=10\".
+  "Change font-related attributes of FACE to those of FONT.
+FONT can be a string, a font spec, a font entity, a font object,
+or a fontset.  However, interactively, only strings are accepted.
+The format of the font string specification varies based on the font
+system in use, but it can commonly be an X Logical Font
+Description (XLFD) string, or a simpler string like \"Courier-10\"
+or \"courier:size=10\".
 
 FRAME nil or not specified means change face on all frames.
 This sets the attributes `:family', `:foundry', `:width',