From cacd58463b9265ab737a85cceb502cd8538d3c9b Mon Sep 17 00:00:00 2001 From: Eli Zaretskii Date: Sat, 2 Nov 2019 12:41:51 +0200 Subject: [PATCH] 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) --- doc/emacs/frames.texi | 19 ++++++++++++++----- doc/lispref/display.texi | 33 +++++++++++++++++++-------------- lisp/faces.el | 11 +++++++---- 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', -- 2.39.5