Commit cacd5846 authored by Eli Zaretskii's avatar Eli Zaretskii

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