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
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,
......
......@@ -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
......
......@@ -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',
......
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