[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
master cacd584: Improve documentation of 'set-face-font'
From: |
Eli Zaretskii |
Subject: |
master cacd584: Improve documentation of 'set-face-font' |
Date: |
Sat, 2 Nov 2019 06:42:03 -0400 (EDT) |
branch: master
commit cacd58463b9265ab737a85cceb502cd8538d3c9b
Author: Eli Zaretskii <address@hidden>
Commit: Eli Zaretskii <address@hidden>
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 cac1f7f..091c011 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 29abc0a..95f9cc1 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 75753ec..dc5bcca 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',
[Prev in Thread] |
Current Thread |
[Next in Thread] |
- master cacd584: Improve documentation of 'set-face-font',
Eli Zaretskii <=