The Fontspec Package Font Selection For X E L Tex and Lual Tex
The Fontspec Package Font Selection For X E L Tex and Lual Tex
The Fontspec Package Font Selection For X E L Tex and Lual Tex
2020/02/21 v2.7i
Contents
I Getting started 5
1 History 5
2 Introduction 5
2.1 Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5
2 Font selection 9
2.1 By font name . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9
2.2 By file name . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10
2.3 By custom file name using a .fontspec file . . . . . . . . . . . . . . . . . . 11
2.4 Querying whether a font ‘exists’ . . . . . . . . . . . . . . . . . . . . . . . . 12
1
3 Commands to select font families 13
IV OpenType 31
1 Introduction 31
1.1 How to select font features . . . . . . . . . . . . . . . . . . . . . . . . . . . 31
1.2 How do I know what font features are supported by my fonts? . . . . . . . . 32
2
V Commands for accents and symbols (‘encodings’) 50
1 A new Unicode-based encoding from scratch 50
3 Summary of commands 53
3
4 Renaming existing features & options 63
5 Programming interface 63
5.1 Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63
5.2 Functions for loading new fonts and families . . . . . . . . . . . . . . . . . . 63
5.3 Conditionals . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 64
4
Part I
Getting started
1 History
This package began life as a LATEX interface to select system-installed macOS fonts in Jonathan
Kew’s XETEX, the first widely-used Unicode extension to TEX. Over time, XETEX was extended
to support OpenType fonts and then was ported into a cross-platform program to run also on
Windows and Linux.
More recently, LuaTEX is fast becoming the TEX engine of the day; it supports Unicode
encodings and OpenType fonts and opens up the internals of TEX via the Lua programming
language. Hans Hagen’s ConTEXt Mk. IV is a re-write of his powerful typesetting system, tak-
ing full advantage of LuaTEX’s features including font support; a kernel of his work in this area
has been extracted to be useful for other TEX macro systems as well, and this has enabled
fontspec to be adapted for LATEX when run with the LuaTEX engine.
2 Introduction
The fontspec package allows users of either XETEX or LuaTEX to load OpenType fonts in a
LATEX document. No font installation is necessary, and font features can be selected and used
as desired throughout the document.
Without fontspec, it is necessary to write cumbersome font definition files for LATEX, since
LTEX’s font selection scheme (known as the ‘NFSS’) has a lot going on behind the scenes to
A
allow easy commands like \emph or \bfseries. With an uncountable number of fonts now
available for use, however, it becomes less desirable to have to write these font definition (.fd)
files for every font one wishes to use.
Because fontspec is designed to work in a variety of modes, this user documentation is
split into separate sections that are designed to be relatively independent. Nonetheless, the
basic functionality all behaves in the same way, so previous users of fontspec under XETEX
should have little or no difficulty switching over to LuaTEX.
This manual can get rather in-depth, as there are a lot of details to cover. See the docu-
ments fontspec-example.tex for a complete minimal example to get started quickly.
2.1 Acknowledgements
This package could not have been possible without the early and continued support the author
of XETEX, Jonathan Kew. When I started this package, he steered me many times in the right
direction.
I’ve had great feedback over the years on feature requests, documentation queries, bug
reports, font suggestions, and so on from lots of people all around the world. Many thanks to
you all.
Thanks to David Perry and Markus Böhning for numerous documentation improvements
and David Perry again for contributing the text for one of the sections of this manual.
Special thanks to Khaled Hosny, who was the driving force behind the support for
LuaLATEX, ultimately leading to version 2.0 of the package.
5
3 Package loading and options
For basic use, no package options are required:
\usepackage{fontspec}
Package options will be introduced below; some preliminary details are discussed first.
3.3 Configuration
If you wish to customise any part of the fontspec interface, this should be done by creating
your own fontspec.cfg file, which will be automatically loaded if it is found by XETEX or
LuaTEX. A fontspec.cfg file is distributed with fontspec with a small number of defaults set
up within it.
To customise fontspec to your liking, use the standard .cfg file as a starting point or
write your own from scratch, then either place it in the same folder as the main document
for isolated cases, or in a location that XETEX or LuaTEX searches by default; e.g. in MacTEX:
~/Library/texmf/tex/latex/.
The package option no-config will suppress the loading of the fontspec.cfg file under
all circumstances.
3.4 Warnings
This package can give some warnings that can be harmless if you know what you’re doing.
Use the quiet package option to write these warnings to the transcript (.log) file instead.
Use the silent package option to completely suppress these warnings if you don’t even
want the .log file cluttered up.
6
4 Interaction with LATEX 2ε and other packages
This section documents some areas of adjustment that fontspec makes to improve default
behaviour with LATEX 2ε and third-party packages.
\strongfontdeclare{\bfseries,\fontseries{k}\selectfont}
\strongreset If too many levels of \strong are reached, \strongreset is inserted. By default this is a
no-op and the font will simply remain the same. Use \renewcommand\strongreset{\mdseries}
to start again from the beginning if desired.
An example for setting up a font family for use with \strong is discussed in 4.3.1 on
page 17.
7
Part II
General font selection
1 Main commands
This section concerns the variety of commands that can be used to select fonts.
\setmainfont{⟨font⟩}[⟨font features⟩]
\setsansfont{⟨font⟩}[⟨font features⟩]
\setmonofont{⟨font⟩}[⟨font features⟩]
These are the main font-selecting commands of this package which select the standard
fonts used in a document, as shown in Example 1. Here, the scales of the fonts have been
chosen to equalise their lowercase letter heights. The Scale font feature will be discussed
further in Section 6 on page 24, including methods for automatic scaling. Note that further
options may need to be added to select appropriate bold/italic fonts, but this shows the main
idea.
Note that while these commands all look and behave largely identically, the default setup
for font loading automatically adds the Ligatures=TeX feature for the \setmainfont and
\setsansfont commands. These defaults (and further customisations possible) are discussed
in Section 1 on page 19.
\newfontfamily⟨cmd⟩{⟨font⟩}[⟨font features⟩]
\setfontfamily⟨cmd⟩{⟨font⟩}[⟨font features⟩]
\renewfontfamily⟨cmd⟩{⟨font⟩}[⟨font features⟩]
\providefontfamily⟨cmd⟩{⟨font⟩}[⟨font features⟩]
These commands define new font family commands (like \rmfamily). The new com-
mand checks if ⟨cmd⟩ has been defined, and issues an error if so. The renew command checks
if ⟨cmd⟩ has been defined, and issues an error if not. The provide command checks if ⟨cmd⟩
has been defined, and silently aborts if so. The set command never checks; use at your own
risk.
\fontspec{⟨font⟩}[⟨font features⟩]
The plain \fontspec command is not generally recommended for document use. It is an
ad hoc command best suited for testing and loading fonts on a one-off basis.
All of the commands listed above accept comma-separated ⟨font feature⟩=⟨option⟩ lists;
these are described later:
• For general font features, see Section 6 on page 24
• For OpenType fonts, see Part IV on page 31
• For XETEX-only general font features, see Part VII on page 56
• For LuaTEX-only general font features, see Part VI on page 54
• For features for AAT fonts in XETEX, see Section 3 on page 58
8
Example 1: Loading the default, sans serif, and monospaced fonts.
\setmainfont{texgyrebonum-regular.otf}
\setsansfont{lmsans10-regular.otf}[Scale=MatchLowercase]
\setmonofont{Inconsolatazi4-Regular.otf}[Scale=MatchLowercase]
Pack my box with five dozen liquor jugs \rmfamily Pack my box with five dozen liquor jugs\par
Pack my box with five dozen liquor jugs \sffamily Pack my box with five dozen liquor jugs\par
Pack my box with five dozen liquor jugs \ttfamily Pack my box with five dozen liquor jugs
2 Font selection
In both LuaTEX and XETEX, fonts can be selected (using the ⟨font⟩ argument in Section 1) either
by ‘font name’ or by ‘file name’, but there are some differences in how each engine finds and
selects fonts — don’t be too surprised if a font invocation in one engine needs correction to
work in the other.
LuaTEX users only In order to load fonts by their name rather than by their filename (e.g.,
‘Latin Modern Roman’ instead of ‘ec-lmr10’), you may need to run the script luaotfload-tool,
which is distributed with the luaotfload package. Note that if you do not execute this script
beforehand, the first time you attempt to typeset the process will pause for (up to) several
minutes. (But only the first time.) Please see the luaotfload documentation for more informa-
tion.
9
2.2 By file name
XETEX and LuaTEX also allow fonts to be loaded by file name instead of font name. When
you have a very large collection of fonts, you will sometimes not wish to have them all in-
stalled in your system’s font directories. In this case, it is more convenient to load them from
a different location on your disk. This technique is also necessary in XETEX when loading
OpenType fonts that are present within your TEX distribution, such as /usr/local/texlive/
2013/texmf-dist/fonts/opentype/public. Fonts in such locations are visible to XETEX
but cannot be loaded by font name, only file name; LuaTEX does not have this restriction.
When selecting fonts by file name, any font that can be found in the default search paths
may be used directly (including in the current directory) without having to explicitly define
the location of the font file on disk.
Fonts selected by filename must include bold and italic variants explicitly, unless a
.fontspec file is supplied for the font family (see Section 2.3). We’ll give some first examples
specifying everything explicitly:
\setmainfont{texgyrepagella-regular.otf}[
BoldFont = texgyrepagella-bold.otf ,
ItalicFont = texgyrepagella-italic.otf ,
BoldItalicFont = texgyrepagella-bolditalic.otf ]
fontspec knows that the font is to be selected by file name by the presence of the ‘.otf’ exten-
sion. An alternative is to specify the extension separately, as shown following:
\setmainfont{texgyrepagella-regular}[
Extension = .otf ,
BoldFont = texgyrepagella-bold ,
... ]
If desired, an abbreviation can be applied to the font names based on the mandatory ‘font
name’ argument:
\setmainfont{texgyrepagella}[
Extension = .otf ,
UprightFont = *-regular ,
BoldFont = *-bold ,
... ]
In this case ‘texgyrepagella’ is no longer the name of an actual font, but is used to construct
the font names for each shape; the * is replaced by ‘texgyrepagella’. Note in this case that
UprightFont is required for constructing the font name of the normal font to use.
To load a font that is not in one of the default search paths, its location in the filesystem
must be specified with the Path feature:
\setmainfont{texgyrepagella}[
Path = /Users/will/Fonts/ ,
UprightFont = *-regular ,
BoldFont = *-bold ,
... ]
10
Note that XETEX and LuaTEX are able to load the font without giving an extension, but fontspec
must know to search for the file; this can be indicated by using the Path feature without an
argument:
\setmainfont{texgyrepagella-regular}[
Path, BoldFont = texgyrepagella-bold,
... ]
My preference is to always be explicit and include the extension; this also allows fontspec to
automatically identify that the font should be loaded by filename.
In previous versions of the package, the Path feature was also provided under the alias
ExternalLocation, but this latter name is now deprecated and should not be used for new
documents.
\defaultfontfeatures[My Charis]
{
Extension = .ttf ,
UprightFont = CharisSILR,
BoldFont = CharisSILB,
ItalicFont = CharisSILI,
BoldItalicFont = CharisSILBI,
% <any other desired options>
}
The optional argument to \defaultfontfeatures must exactly match that requested by the
font loading command (\setmainfont, etc.) — in particular note that spaces are significant
here, so \setmainfont{MyCharis} will not ‘see’ the default font feature setting within the
.fontspec file.
1 Located in the current folder or within a standard texmf location.
11
Finally, note that options for individual font faces can also be defined in this way. To
continue the example above, here we colour the different faces:
\defaultfontfeatures[CharisSILR]{Color=blue}
\defaultfontfeatures[CharisSILB]{Color=red}
Such configuration lines could be stored either inline inside My Charis.fontspec or within
their own .fontspec files; in this way, fontspec is designed to handle ‘nested’ configuration
options.
Where \defaultfontfeatures is being used to specify font faces by a custom name,
the Font feature is used to set the filename of the font face. For example:
\defaultfontfeatures[charis]
{
UprightFont = charis-regular,
% <other desired options for all font faces in the family>
}
\defaultfontfeatures[charis-regular]
{
Font = CharisSILR
% <other desired options just for the `upright' font>
}
The fontspec interface here is designed to be flexible to accomodate a variety of use cases; there
is more than one way to achieve the same outcome when font faces are collected together into
a larger font family.
\IfFontExistsTF{cmr10}{T}{F}
\IfFontExistsTF{Times New Roman}{T}{F}
\IfFontExistsTF{texgyrepagella-regular.otf}{T}{F}
\IfFontExistsTF{/Users/will/Library/Fonts/CODE2000.TTF}{T}{F}
12
3 Commands to select font families
For cases when a specific font with a specific feature set is going to be re-used many times in
a document, it is inefficient to keep calling \fontspec for every use. While the \fontspec
command does not define a new font instance after the first call, the feature options must still
be parsed and processed.
For this reason, new commands can be created for loading a particular font family with the
\newfontfamily command and variants, outlined in Section 1 on page 8 and demonstrated
in Example 2. This macro should be used to create commands that would be used in the same
way as \rmfamily, for example. If you would like to create a command that only changes
the font inside its argument (i.e., the same behaviour as \emph) define it using regular LATEX
commands:
\newcommand\textnote[1]{{\notefont #1}}
\textnote{This is a note.}
Note that the double braces are intentional; the inner pair is used to delimit the scope of the
font change.
Comment for advanced users: The commands defined by \newfontfamily (and \newfontface;
see next section) include their encoding information, so even if the document is set to use a
legacy TEX encoding, such commands will still work correctly. For example,
\documentclass{article}
\usepackage{fontspec}
\newfontfamily\unicodefont{Lucida Grande}
\usepackage{mathpazo}
\usepackage[T1]{fontenc}
\begin{document}
A legacy \TeX\ font. {\unicodefont A unicode font.}
\end{document}
\newfontface⟨cmd⟩{⟨font⟩}[⟨font features⟩]
\setfontface⟨cmd⟩{⟨font⟩}[⟨font features⟩]
\renewfontface⟨cmd⟩{⟨font⟩}[⟨font features⟩]
\providefontface⟨cmd⟩{⟨font⟩}[⟨font features⟩]
Sometimes only a specific font face is desired, without accompanying italic or bold vari-
ants being automatically selected. This is common when selecting a fancy italic font, say, that
has swash features unavailable in the upright forms. \newfontface is used for this purpose,
shown in Example 3, which is repeated in Section 3.4 on page 59.
\newfontfamily\notefont{Kurier}
This is a note. \notefont This is a \emph{note}.
13
Example 3: Defining a single font face.
14
\setmainfont{Minion MM Roman}[
SmallCapsFont={Minion MM Small Caps & Oldstyle Figures}
]
Roman 123 \\ \textsc{Small caps 456}
In fact, this example is overly simplistic since it does not cover the other shapes in a font
family. You should specify the small caps font for each individual bold and italic shape as in
\setmainfont{ <upright> }[
UprightFeatures = { SmallCapsFont={ <sc> } } ,
BoldFeatures = { SmallCapsFont={ <bf sc> } } ,
ItalicFeatures = { SmallCapsFont={ <it sc> } } ,
BoldItalicFeatures = { SmallCapsFont={ <bf it sc> } } ,
]
Roman 123 \\ \textsc{Small caps 456}
For most modern fonts that have small caps as a font feature, this level of control isn’t generally
necessary.
All of the bold, italic, and small caps fonts can be loaded with different font features
from the main font. See Section 3 for details. When an OpenType font is selected for
SmallCapsFont, the small caps font feature is not automatically enabled. In this case, users
should write instead, if necessary,
\setmainfont{...}[
SmallCapsFont={...},
SmallCapsFeatures={Letters=SmallCaps},
]
\fontfamily{ppl}\selectfont
In fontspec, the family names are auto-generated based on the fontname of the font; for ex-
ample, writing \fontspec{Times New Roman} for the first time would generate an internal
font family name of ‘TimesNewRoman(1)’. Please note that you should not rely on the name
that is generated.
In certain cases it is desirable to be able to choose this internal font family name so it
can be re-used elsewhere for interacting with other packages that use the LATEX’s font selection
interface; an example might be
\usepackage{fancyvrb}
\fvset{fontfamily=myverbatimfont}
To select a font for use in this way in fontspec use the NFSSFamily feature:2
\newfontfamily\verbatimfont{Inconsolata}[NFSSFamily=myverbatimfont]
2 Thanks to Luca Fascione for the example and motivation for finally implementing this feature.
15
It is then possible to write commands such as:
\fontfamily{myverbatimfont}\selectfont
which is essentially the same as writing \verbatimfont, or to go back to the orginal example:
\fvset{fontfamily=myverbatimfont}
Only use this feature when necessary; the in-built font switching commands that fontspec
generates (such as \verbatimfont in the example above) are recommended in all other cases.
If you don’t wish to explicitly set the NFSS family but you would like to know what it is, an
alternative mechanism for package writers is introduced as part of the fontspec programming
interface; see the function \fontspec_set_family:Nnn for details (Section 5 on page 63).
\setmainfont{font1.otf}[
FontFace = {c}{\shapedefault}{ font2.otf } ,
FontFace = {c}{m}{ Font = font3.otf , Color = red }
]
Writing \fontseries{c}\selectfont will result in font2 being selected, which then fol-
lowed by \fontshape{m}\selectfont will result in font3 being selected (in red). A font
face that is defined in terms of a different series but an upright shape (\shapedefault, as
shown above) will attempt to find a matching small caps feature and define that face as well.
Conversely, a font face defined in terms of a non-standard font shape will not.
There are some standards for choosing shape and series codes; the LATEX 2ε font selection
guide3 has a comprehensive listing.
The FontFace command also interacts properly with the SizeFeatures command as
follows: (nonsense set of font selection choices)
3 texdoc fntguide
16
FontFace = {c}{n}{
Font = Times ,
SizeFeatures = {
{ Size = -10 , Font = Georgia } ,
{ Size = 10-15} , % default "Font = Times"
{ Size = 15- , Font = Cochin } ,
},
},
Note that if the first Font feature is omitted then each size needs its own inner Font declara-
tion.
\setmonofont{SourceCodePro}[
Extension = .otf ,
UprightFont = *-Light ,
BoldFont = *-Regular ,
FontFace = {k}{n}{*-Black} ,
]
\strongfontdeclare{\bfseries,\fontseries{k}\selectfont}
17
However, the default text fonts may not necessarily be the ones you wish to use when
typesetting maths (especially with the use of fancy ligatures and so on). For this reason, you
may optionally use the commands above (in the same way as our other \fontspec-like com-
mands) to explicitly state which fonts to use inside such commands as \mathrm. Additionally,
the \setboldmathrm command allows you define the font used for \mathrm when in bold
maths mode (which is activated with, among others, \boldmath).
For example, if you were using Optima with the Euler maths font, you might have this
in your preamble:
\usepackage{mathpazo}
\usepackage{fontspec}
\setmainfont{Optima}
\setmathrm{Optima}
\setboldmathrm[BoldFont={Optima ExtraBlack}]{Optima Bold}
These commands are compatible with the unicode-math package. Having said that, unicode-
math also defines a more general way of defining fonts to use in maths mode, so you can
ignore this subsection if you’re already using that package.
Spaces \fontspec and \addfontfeatures ignore trailing spaces as if it were a ‘naked’ con-
trol sequence; e.g., ‘M. \fontspec{...} N’ and ‘M. \fontspec{...}N’ are the same.
18
Part III
Selecting font features
The commands discussed so far such as \fontspec each take an optional argument for access-
ing the font features of the requested font. Commands are provided to set default features to
be applied for all fonts, and even to change the features that a font is presently loaded with.
Different font shapes can be loaded with separate features, and different features can even be
selected for different sizes that the font appears in. This part discusses these options.
1 Default settings
\defaultfontfeatures{⟨font features⟩}
It is sometimes useful to define font features that are applied to every subsequent font
selection command. This may be defined with the \defaultfontfeatures command, shown
in Example 5. New calls of \defaultfontfeatures overwrite previous ones, and defaults can
be reset by calling the command with an empty argument.
\defaultfontfeatures[⟨font name⟩]{⟨font features⟩}
Default font features can be specified on a per-font and per-face basis by using the op-
tional argument to \defaultfontfeatures as shown.
\defaultfontfeatures[texgyreadventor-regular.otf]{Color=blue}
\setmainfont{texgyreadventor-regular.otf}% will be blue
Multiple fonts may be affected by using a comma separated list of font names.
\defaultfontfeatures[⟨\font-switch⟩]{⟨font features⟩}
New in v2.4. Defaults can also be applied to symbolic families such as those created with
the \newfontfamily command and for \rmfamily, \sffamily, and \ttfamily:
\defaultfontfeatures[\rmfamily,\sffamily]{Ligatures=TeX}
\setmainfont{texgyreadventor-regular.otf}% will use standard TeX ligatures
\fontspec{texgyreadventor-regular.otf}
Some default text 0123456789 \\
\defaultfontfeatures{
Numbers=OldStyle, Color=888888
}
\fontspec{texgyreadventor-regular.otf}
Some default text 0123456789 Now grey, with old-style figures:
Now grey, with old-style figures: 0123456789 0123456789
19
The line above to set TEX-like ligatures is now activated by default in fontspec.cfg. To reset
default font features, simply call the command with an empty argument:
\defaultfontfeatures[\rmfamily,\sffamily]{}
\setmainfont{texgyreadventor-regular.otf}% will no longer use standard TeX ligatures
\defaultfontfeatures+{⟨font features⟩}
\defaultfontfeatures+[⟨font name⟩]{⟨font features⟩}
New in v2.4. Using the + form of the command appends the ⟨font features⟩ to any
already-selected defaults.
20
Example 6: A demonstration of the \addfontfeatures command.
\fontspec{texgyreadventor-regular.otf}%
[Numbers={Proportional,OldStyle}]
`In 1842, 999 people sailed 97 miles in
13 boats. In 1923, 111 people sailed 54
miles in 56 boats.' \bigskip
‘In 1842, 999 people sailed 97 miles in 13 boats. In
{\addfontfeatures{Numbers={Monospaced,Lining}}
1923, 111 people sailed 54 miles in 56 boats.’
\begin{tabular}{@{} cccc @{}}
Year & People & Miles & Boats \\
Year People Miles Boats
\hline 1842 & 999 & 75 & 13 \\
1842 999 75 13 1923 & 111 & 54 & 56
1923 111 54 56 \end{tabular}}
BoldFeatures={⟨features⟩}
ItalicFeatures={⟨features⟩}
BoldItalicFeatures={⟨features⟩}
SlantedFeatures={⟨features⟩}
BoldSlantedFeatures={⟨features⟩}
SmallCapsFeatures={⟨features⟩}
UprightFeatures={⟨features⟩}
It is entirely possible that separate fonts in a family will require separate options; e.g.,
Hoefler Text Italic contains various swash feature options that are completely unavailable in
the upright shapes.
The font features defined at the top level of the optional \fontspec argument are
applied to all shapes of the family. Using Upright-, SmallCaps-, Bold-, Italic-, and
BoldItalicFeatures, separate font features may be defined to their respective shapes in
addition to, and with precedence over, the ‘global’ font features. See Example 7.
Note that because most fonts include their small caps glyphs within the main font,
features specified with SmallCapsFeatures are applied in addition to any other shape-
specific features as defined above, and hence SmallCapsFeatures can be nested within
ItalicFeatures and friends. Every combination of upright, italic, bold and small caps can
thus be assigned individual features, as shown in the somewhat ludicrous Example 8.
21
Example 7: Features for, say, just italics.
\fontspec{EBGaramond-Regular.otf}%
[ItalicFont=EBGaramond-Italic.otf]
Don’t Ask Victoria! \itshape Don’t Ask Victoria! \\
Don’t Ask Victoria! \addfontfeature{ItalicFeatures={Style=Swash}}
Don’t Ask Victoria! \\
Example 8: An example of setting the SmallCapsFeatures separately for each font shape.
\fontspec{texgyretermes}[
Extension = {.otf},
UprightFont = {*-regular}, ItalicFont = {*-italic},
BoldFont = {*-bold}, BoldItalicFont = {*-bolditalic},
UprightFeatures={Color = 220022,
SmallCapsFeatures = {Color=115511}},
ItalicFeatures={Color = 2244FF,
SmallCapsFeatures = {Color=112299}},
BoldFeatures={Color = FF4422,
SmallCapsFeatures = {Color=992211}},
BoldItalicFeatures={Color = 888844,
SmallCapsFeatures = {Color=444422}},
]
Upright SMALL CAPS Upright {\scshape Small Caps}\\
Italic ITALIC SMALL CAPS \itshape Italic {\scshape Italic Small Caps}\\
Bold BOLD SMALL CAPS \upshape\bfseries Bold {\scshape Bold Small Caps}\\
Bold Italic BOLD ITALIC SMALL CAPS \itshape Bold Italic {\scshape Bold Italic Small Caps}
22
4 Selecting fonts from TrueType Collections (TTC files)
TrueType Collections are multiple fonts contained within a single file. Each font within a col-
lection must be explicitly chosen using the FontIndex command. Since TrueType Collections
are often used to contain the italic/bold shapes in a family, fontspec automatically selects
the italic, bold, and bold italic fontfaces from the same file. For example, to load the macOS
system font Optima:
\setmainfont{Optima.ttc}[
Path = /System/Library/Fonts/ ,
UprightFeatures = {FontIndex=0} ,
BoldFeatures = {FontIndex=1} ,
ItalicFeatures = {FontIndex=2} ,
BoldItalicFeatures = {FontIndex=3} ,
]
Support for TrueType Collections has only been tested in XETEX, but should also work with an
up-to-date version of LuaTEX and the luaotfload package.
23
Example 9: An example of specifying different font features for different sizes of font with
SizeFeatures.
\fontspec{texgyrechorus-mediumitalic.otf}[
SizeFeatures={
{Size={-8}, Font=texgyrebonum-italic.otf, Color=AA0000},
Small {Size={8-14}, Color=00AA00},
Normal size {Size={14-}, Color=0000AA}} ]
Interaction with other features For SizeFeatures to work with ItalicFeatures, BoldFeatures,
etc., and SmallCapsFeatures, a strict heirarchy is required:
UprightFeatures =
{
SizeFeatures =
{
{
Size = -10,
Font = ..., % if necessary
SmallCapsFeatures = {...},
... % other features for this size range
},
... % other size ranges
}
}
Table 1: Syntax for specifying the size to apply custom font features.
24
6.1 Colour
Color (or Colour) uses font specifications to set the colour of the text. You should think of
this as the literal glyphs of the font being coloured in a certain way. Notably, this mechanism
is different to that of the color/xcolor/hyperref/etc. packages, and in fact using fontspec com-
mands to set colour will prevent your text from changing colour using those packages at all!
For example, if you set the colour in a \setmainfont command, \color{...} and related
commands, including hyperlink colouring, will no longer have any effect on text in this font.)
Therefore, fontspec’s colour commands are best used to set explicit colours in specific situa-
tions, and the xcolor package is recommended for more general colour functionality.
The colour is defined as a triplet of two-digit Hex RGB values, with optionally another
value for the transparency (where 00 is completely transparent and FF is opaque.) Trans-
parency is supported by LuaLATEX; XELATEX with the xdvipdfmx driver does not support this
feature.
If you load the xcolor package, you may use any named colour instead of writing the
colours in hexadecimal.
\usepackage{xcolor}
...
\fontspec[Color=red]{Verdana} ...
\definecolor{Foo}{rgb}{0.3,0.4,0.5}
\fontspec[Color=Foo]{Verdana} ...
\fontspec[Color=red,Opacity=0.7]{Verdana} ...
It is still possible to specify a colour in six-char hexadecimal form while defining opacity in
this way, if you like.
6.2 Scale
Scale = ⟨number⟩
Scale = MatchLowercase
Scale = MatchUppercase
In its explicit form, Scale takes a single numeric argument for linearly scaling the font,
as demonstrated in Example 1.
\fontsize{48}{48}
WSPR
\fontspec{texgyrebonum-bold.otf}
{\addfontfeature{Color=FF000099}W}\kern-0.4ex
{\addfontfeature{Color=0000FF99}S}\kern-0.4ex
{\addfontfeature{Color=DDBB2299}P}\kern-0.5ex
{\addfontfeature{Color=00BB3399}R}
25
As well as a numerical argument, the Scale feature also accepts options MatchLowercase
and MatchUppercase, which will scale the font being selected to match the current default ro-
man font to either the height of the lowercase or uppercase letters, respectively; these features
are shown in Example 11. The amount of scaling used in each instance is reported in the .log
file.
Additional calls to the Scale feature overwrite the settings of the former. If you want to
accumulate scale factors (useful perhaps to fine-tune the settings of MatchLowercase), the
ScaleAgain feature can be used as many times as necessary. For example:
Note that when Scale=MatchLowercase is used with \setmainfont, the new ‘main’
font of the document will be scaled to match the old default. If you wish to automatically scale
all fonts except have the main font use ‘natural’ scaling, you may write
One or both of these lines may be placed into a local fontspec.cfg file (see Section 3.3
on page 6) for this behaviour to be effected in your own documents automatically. (Also see
Section 1 on page 19 for more information on setting font defaults.)
\setmainfont{Georgia}
\newfontfamily\lc[Scale=MatchLowercase]{Verdana}
The perfect match {\lc is hard to find.}\\
The perfect match is hard to find. \newfontfamily\uc[Scale=MatchUppercase]{Arial}
LOGOFONT L O G O \uc F O N T
26
Example 12: Scaling the default interword space. An exaggerated value has been chosen to emphasise
the effects here.
\fontspec{texgyretermes-regular.otf}
Some text for our example to take
up some space, and to demonstrate
the default interword space.
\bigskip
Some text for our example to take up some space, and to \fontspec{texgyretermes-regular.otf}%
demonstrate the default interword space. [WordSpace = 0.3]
Some text for our example to take
Sometextforourexampletotakeupsomespace,andtodemon- up some space, and to demonstrate
stratethedefaultinterwordspace. the default interword space.
\nonfrenchspacing
\fontspec{texgyreschola-regular.otf}
Letters, Words. Sentences. \par
\fontspec{texgyreschola-regular.otf}[PunctuationSpace=2]
Letters, Words. Sentences. Letters, Words. Sentences. \par
Letters, Words. Sentences. \fontspec{texgyreschola-regular.otf}[PunctuationSpace=0]
Letters, Words. Sentences. Letters, Words. Sentences.
27
As part of fontspec.cfg, the default monospaced family (e.g., \ttfamily) is set up to
automatically set HyphenChar = None.
If the input is a single character, then this character is used. Finally, if the input is longer
than a single character it must be the UTF-8 slot number of the hyphen character you desire.
Note that TEX’s optimisations in how it loads fonts means that you cannot use this feature
in \addfontfeatures.
\def\text{\fbox{\parbox{1.55cm}{%
EXAMPLE EXAMPLE HYPHENATION%
HYPHENATION }}\qquad\qquad\null\par\bigskip}
\fontspec{LinLibertine_R.otf}[HyphenChar=None]
EXAMPLE \text
HYPHEN+ \fontspec{LinLibertine_R.otf}[HyphenChar={+}]
ATION \text
28
Example 15: A demonstration of automatic optical size selection.
Example 16: Explicit optical size substitution for the Latin Modern Roman family.
29
If you want the bold shape to be faked automatically, or the italic shape to be slanted au-
tomatically, use the AutoFakeBold and AutoFakeSlant features. For example, the following
two invocations are equivalent:
\fontspec[AutoFakeBold=1.5]{Charis SIL}
\fontspec[BoldFeatures={FakeBold=1.5}]{Charis SIL}
If both of the AutoFake... features are used, then the bold italic font will also be faked.
\fontspec{Didot}
\addfontfeature{LetterSpace=0.0}
USE TRACKING FOR DISPLAY CAPS TEXT \\
USE TRACKING FOR DISPLAY CAPS TEXT \addfontfeature{LetterSpace=2.0}
USE TRACKING FOR DISPLAY CAPS TEXT USE TRACKING FOR DISPLAY CAPS TEXT
30
Part IV
OpenType
1 Introduction
OpenType fonts (and other ‘smart’ font technologies such as AAT and Graphite) can change
the appearance of text in many different ways. These changes are referred to as font features.
When the user applies a feature — for example, small capitals — to a run of text, the code in-
side the font makes appropriate substitutions and small capitals appear in place of lowercase
letters. However, the use of such features does not affect the underlying text. In our small
caps example, the lowercase letters are still stored in the document; only the appearance has
been changed by the OpenType feature. This makes it possible to search and copy text with-
out difficulty. If the user selected a different font that does not support small caps, the ‘plain’
lowercase letters would appear instead.
Some OpenType features are required to support particular scripts, and these features
are often applied automatically. The Indic scripts, for example, often require that characters
be reshaped and reordered after they are typed by the user, in order to display them in the
traditional ways that readers expect. Other features can be applied to support a particular
language. The Junicode font for medievalists uses by default the Old English shape of the
letter thorn, while in modern Icelandic thorn has a more rounded shape. If a user tags some
text as being in Icelandic, Junicode will automatically change to the Icelandic shape through
an OpenType feature that localises the shapes of letters.
There are a large group of OpenType features, designed to support high quality typogra-
phy a multitude of languages and writing scripts. Examples of some font features have already
been shown in previous sections; the complete set of OpenType font features supported by
fontspec is described below in Section 3.
The OpenType specification provides four-letter codes (e.g., smcp for small capitals) for
each feature. The four-letter codes are given below along with the fontspec names for various
features, for the benefit of people who are already familiar with OpenType. You can ignore the
codes if they don’t mean anything to you.
31
1.2 How do I know what font features are supported by my fonts?
Although I’ve long desired to have a feature within fontspec to display the OpenType
features within a font, it’s never been high on my priority list. One reason for that is
the existence of the document opentype-info.tex, which is available on CTAN or typing
kpsewhich opentype-info.tex in a Terminal window. Make a copy of this file and place
it somewhere convenient. Then open it in your regular TEX editor and change the font name
to the font you’d like to query; after running through plain XETEX, the output PDF will look
something like this:
I intentionally picked a font above that by design contains few font features; ‘regular’ text fonts
such as Latin Modern Roman contain many more, and I didn’t want to clutter up the document
too much. After finding the scripts, languages, and features contained within the font, you’ll
then need to cross-check the OpenType tags with the ‘logical’ names used by fontspec.
otfinfo Alternatively, and more simply, you can use the command line tool otfinfo, which
is distributed with TEXLive. Simply type in a Terminal window, say:
32
pnum Proportional Figures
size Optical Size
tnum Tabular Figures
zero Slashed Zero
33
Example 19: An example of various Scripts and Languages.
ﺍﻟﻌﺮﺑﻲ العربي
हिन्दी िहन्दी
লেখ েলখ
\testfeature{Script=Arabic}{\arabictext}
મર્યાદા-સૂચક નિવેદન મર્યાદા-સૂચક િનવેદન \testfeature{Script=Devanagari}{\devanagaritext}
\testfeature{Script=Bengali}{\bengalitext}
നമ്മുടെ പാരബര്യ നമ്മുെട പാരബര്യ
\testfeature{Script=Gujarati}{\gujaratitext}
ਆਦਿ ਸਚੁ ਜੁਗਾਦਿ ਸਚੁ ਆਿਦ ਸਚੁ ਜੁਗਾਿਦ ਸਚੁ \testfeature{Script=Malayalam}{\malayalamtext}
தமிழ் தேடி தமிழ் ேதடி \testfeature{Script=Gurmukhi}{\gurmukhitext}
\testfeature{Script=Tamil}{\tamiltext}
ּתּה ִרְדָּֽתּה
ָֽ ִר ְד \testfeature{Script=Hebrew}{\hebrewtext}
cấp số mỗi cấp số mỗi \def\examplefont{DoulosSILR.ttf}
\testfeature{Language=Vietnamese}{\vietnamesetext}
Table 2: Defined Scripts for OpenType fonts. Aliased names are shown in adjacent positions
marked with red pilcrows (¶).
34
Table 3: Defined Languages for OpenType fonts. Aliased names are shown in adjacent positions marked with red pilcrows
(¶).
35
A brief reference is provided (Table 4 on the next page) but note that this is an in-
complete listing — only the ‘enable’ keys are shown, and where alternative interfaces are
provided for convenience only the first is shown. (E.g., Numbers=OldStyle is the same as
Numbers=Lowercase.)
For completeness, the complete list of OpenType features not provided with a fontspec
interface is shown in Table 5 on page 38. Features omitted are partially by design and partially
by oversight; for example, the aalt feature is largely useless in TEX since it is designed for
providing a GUI interface for selecting ‘all alternates’ of a glyph. Others, such as optical bounds
for example, simply haven’t yet been considered due to a lack of fonts available for testing.
Suggestions welcome for how/where to add these missing features to the package.
The numbering is entirely font-specific. Glyph ‘5’ might be the character ‘v’, for example. Char-
acter variants are specifically designed not to conflict with each other, so you can enable them
individually per character. (Unlike stylistic alternates, say.) Note that the indexing starts from
zero.
a&h \fontspec{LinLibertine_R.otf}
\textsc{a} \& h \\
&h \addfontfeature{Alternate=0}
\textsc{a} \& h
36
Table 4: Summary of OpenType features in fontspec, alphabetic by feature tag.
ABVM Diacritics = AboveBase Above-base Mark NLCK CJKShape = NLC NLC Kanji Forms
Positioning NUMR VerticalPosition = Numerator Numerators
AFRC Fractions = Alternate Alternative Fractions ONUM Numbers = Lowercase Oldstyle Figures
BLWM Diacritics = BelowBase Below-base Mark ORDN VerticalPosition = Ordinal Ordinals
Positioning ORNM Ornament = N Ornaments
CALT Contextuals = Alternate Contextual Alternates PALT CharacterWidth = AlternateProportional Proportional Alternate
CASE Letters = Uppercase Case-Sensitive Forms Widths
CLIG Ligatures = Contextual Contextual Ligatures PCAP Letters = PetiteCaps Petite Capitals
CPSP Kerning = Uppercase Capital Spacing PKNA Style = ProportionalKana Proportional Kana
CSWH Contextuals = Swash Contextual Swash PNUM Numbers = Proportional Proportional Figures
CVNN CharacterVariant = N :M Character Variant N PWID CharacterWidth = Proportional Proportional Widths
C2PC Letters = UppercasePetiteCaps Petite Capitals From QWID CharacterWidth = Quarter Quarter Widths
Capitals RAND Letters = Random Randomize
C2SC Letters = UppercaseSmallCaps Small Capitals From RLIG Ligatures = Required Required Ligatures
Capitals
RUBY Style = Ruby Ruby Notation Forms
DLIG Ligatures = Rare Discretionary Ligatures
SALT Alternate = N Stylistic Alternates
DNOM VerticalPosition = Denominator Denominators
SINF VerticalPosition = ScientificInferior Scientific Inferiors
EXPT CJKShape = Expert Expert Forms
SMCP Letters = SmallCaps Small Capitals
FALT Contextuals = LineFinal Final Glyph on Line
SMPL CJKShape = Simplified Simplified Forms
Alternates
SSNN StylisticSet = N Stylistic Set N
FINA Contextuals = WordFinal Terminal Forms
SSTY Style = MathScript Math script style alternates
FRAC Fractions = On Fractions
SUBS VerticalPosition = Inferior Subscript
FWID CharacterWidth = Full Full Widths
SUPS VerticalPosition = Superior Superscript
HALT CharacterWidth = AlternateHalf Alternate Half Widths
SWSH Style = Swash Swash
HIST Style = Historic Historical Forms
TITL Style = Titling Titling
HKNA Style = HorizontalKana Horizontal Kana Alternates
TNUM Numbers = Monospaced Tabular Figures
HLIG Ligatures = Historic Historical Ligatures
TRAD CJKShape = Traditional Traditional Forms
HWID CharacterWidth = Half Half Widths
TWID CharacterWidth = Third Third Widths
INIT Contextuals = WordInitial Initial Forms
UNIC Letters = Unicase Unicase
ITAL Style = Italic Italics
VALT Vertical = AlternateMetrics Alternate Vertical Metrics
JP78 CJKShape = JIS1978 JIS78 Forms
VERT Vertical = Alternates Vertical Writing
JP83 CJKShape = JIS1983 JIS83 Forms
VHAL Vertical = HalfMetrics Alternate Vertical Half
JP90 CJKShape = JIS1990 JIS90 Forms
Metrics
JP04 CJKShape = JIS2004 JIS2004 Forms
VKNA Style = VerticalKana Vertical Kana Alternates
KERN Kerning = On Kerning
VKRN Vertical = Kerning Vertical Kerning
LIGA Ligatures = Common Standard Ligatures
VPAL Vertical = ProportionalMetrics Proportional Alternate
LNUM Numbers = Uppercase Lining Figures Vertical Metrics
LOCL LocalForms = On Localized Forms VRT2 Vertical = RotatedGlyphs Vertical Alternates and
MARK Diacritics = MarkToBase Mark Positioning Rotation
MEDI Contextuals = Inner Medial Forms VRTR Vertical = AlternatesForRotation Vertical Alternates for
MKMK Diacritics = MarkToMark Mark to Mark Positioning Rotation
NALT Annotation = N Alternate Annotation Forms ZERO Numbers = SlashedZero Slashed Zero
37
Table 5: List of unsupported OpenType features.
3.1.3 Contextuals
This feature refers to substitutions of glyphs that vary ‘contextually’ by their relative position
in a word or string of characters; features such as contextual swashes are accessed via the
options shown in Table 6.
Historic forms are accessed in OpenType fonts via the feature Style=Historic; this is
generally not contextual in OpenType, which is why it is not included in this feature.
3.1.4 Diacritics
Specifies how combining diacritics should be placed. These will usually be controlled auto-
matically according to the Script setting.
38
Table 6: Options for the OpenType font feature ‘Contextuals’.
\setsansfont{Lato}[Fractions=On]
\setmonofont{IBM Plex Mono}[Fractions=On]
39
Table 9: Options for the OpenType font feature ‘Kerning’.
As briefly mentioned previously at the end of 3.1.7, the Uppercase option will add a
small amount of tracking between uppercase letters, seen in Example 22, which uses the Ro-
mande fonts6 (thanks to Clea F. Rees for the suggestion). The Uppercase option acts sepa-
rately to the regular kerning controlled by the On/Off options.
3.1.7 Letters
The Letters feature specifies how the letters in the current font will look. OpenType
fonts may contain the following options: SmallCaps, PetiteCaps, UppercaseSmallCaps,
UppercasePetiteCaps, and Unicase.
Petite caps are smaller than small caps. SmallCaps and PetiteCaps turn lowercase let-
ters into the smaller caps letters, whereas the Uppercase... options turn the capital letters
into the smaller caps (good, e.g., for applying to already uppercase acronyms like ‘NASA’).
This difference is shown in Example 23. ‘Unicase’ is a weird hybrid of upper and lower case
letters.
3.1.8 Ligatures
Ligatures refer to the replacement of two separate characters with a specially drawn glyph
for functional or æsthetic reasons. The list of options, of which multiple may be selected at
one time, is shown in Table 11. A demonstration with the Linux Libertine fonts7 is shown in
Example 24.
Note the additional features accessed with Ligatures=TeX. These are not actually real
OpenType features, but additions provided by luaotfload (i.e., LuaTEX only) to emulate TEX’s
behaviour for ASCII input of curly quotes and punctuation. In XETEX this is achieved with the
6 http://arkandis.tuxfamily.org/adffonts.html
7 http://www.linuxlibertine.org/
Example 22: Adding extra kerning for uppercase letters. (The difference is usually very small.)
\fontspec{RomandeADFStd-DemiBold.otf}
UPPERCASE EXAMPLE \\
UPPERCASE EXAMPLE \addfontfeature{Kerning=Uppercase}
UPPERCASE EXAMPLE UPPERCASE EXAMPLE
40
Table 10: Options for the OpenType font feature ‘Letters’.
\fontspec{texgyreadventor-regular.otf}[Letters=SmallCaps]
THIS SENTENCE no verb \\
THIS SENTENCE no verb \fontspec{texgyreadventor-regular.otf}[Letters=UppercaseSmallCaps]
this sentence no verb THIS SENTENCE no verb
Mapping feature (see Section 1.1 on page 56) but for consistency Ligatures=TeX will perform
the same function as Mapping=tex-text.
41
Example 24: An example of the Ligatures feature.
3.1.10 Numbers
The Numbers feature defines how numbers will look in the selected font, accepting options
shown in Table 13.
The synonyms Uppercase and Lowercase are equivalent to Lining and OldStyle,
respectively. The differences have been shown previously in Section 2 on page 20. The
Monospaced option is useful for tabular material when digits need to be vertically aligned.
The SlashedZero option replaces the default zero with a slashed version to prevent con-
fusion with an uppercase ‘O’, shown in Example 25.
The Arabic option (with tag anum) maps regular numerals to their Arabic script or Per-
sian equivalents based on the current Language setting (see Section 2 on page 33). This option
is based on a LuaTEX feature of the luaotfload package, not an OpenType feature. (Thus, this
feature is unavailable in XETEX.) This feature should be considered deprecated; while there are
no plans to remove it from this package, if its support is dropped from the font loader it could
disappear from fontspec with little notice.
\fontspec[Numbers=Lining]{texgyrebonum-regular.otf}
0123456789
\fontspec[Numbers=SlashedZero]{texgyrebonum-regular.otf}
0123456789 0123456789 0123456789
42
Table 13: Options for the OpenType font feature ‘Numbers’.
3.1.12 Style
‘Ruby’ refers to a small optical size, used in Japanese typography for annotations. For fonts
with multiple salt OpenType features, use the fontspec Alternate feature instead.
Example 26 shows an example of a font feature that involves glyph substitution for par-
ticular letters within an alphabet. Other options in these categories operate in similar ways,
with the choice of how particular substitutions are organised with which feature largely up to
the font designer.
The Uppercase option is designed to select various uppercase forms for glyphs such as
accents and dashes, such as shown in Example 27; note the raised position of the hyphen to
better match the surrounding letters. It will (probably) not actually map letters to uppercase.8
This option used to be selected under the Letters feature, but moved here as it generally does
not actually affect the letters themselves. The Kerning feature also contains an Uppercase
option, which adds a small amount of spacing in between letters (see 3.1.6 on page 38).
In other features, larger breadths of changes can be seen, covering the style of an entire
alphabet. See Example 28; here, the Italic option affects the Latin text and the Ruby option
the Japanese.
8 If you want automatic uppercase letters, look to LATEX’s \MakeUppercase command.
\fontspec{Quattrocento.otf}
MQW M Q W \\
\addfontfeature{Style=Alternate}
MQW M Q W
43
Table 14: Options for the OpenType font feature ‘Style’.
\fontspec{LinLibertine_R.otf}
UPPER-CASE example \\
UPPER-CASE example \addfontfeature{Style=Uppercase}
UPPER-CASE example UPPER-CASE example
Example 28: Example of the Italic and Ruby options of the Style feature.
44
Note the difference here between the default and the horizontal style kana in Example 29:
the horizontal style is slightly wider.
Example 29: Example of the HorizontalKana and VerticalKana options of the Style feature.
45
Example 30: Insular letterforms, as used in medieval Northern Europe, for the Junicode font accessed
with the StylisticSet feature.
\fontspec{Junicode}
Insular forms. Insular forms. \\
Inꞅulaꞃ ꝼoꞃmꞅ. \addfontfeature{StylisticSet=2}
Insular forms. \\
Example 31: Enlarged minuscules (capital letters remain unchanged) for the Junicode font, accessed with
the StylisticSet feature.
\fontspec{Junicode}
ENLARGED Minuscules. ENLARGED Minuscules. \\
ENLARGED Minuscules. \addfontfeature{StylisticSet=6}
ENLARGED Minuscules. \\
\fontspec{LibreCaslonText-Regular.otf}[VerticalPosition=Superior]
Superior: 1234567890 \\
\fontspec{LibreCaslonText-Regular.otf}[VerticalPosition=Numerator]
Numerator: 12345 \\
Superior: ¹²³⁴⁵⁶⁷⁸⁹⁰ \fontspec{LibreCaslonText-Regular.otf}[VerticalPosition=Denominator]
Numerator: 12345 Denominator: 12345 \\
Denominator: 12345 \fontspec{LibreCaslonText-Regular.otf}[VerticalPosition=ScientificInferior]
Scientific Inferior: ₁₂₃₄₅ Scientific Inferior: 12345
46
3.2.1 Annotation — nalt
Some fonts are equipped with an extensive range of numbers and numerals in different forms.
These are accessed with the Annotation feature (OpenType feature nalt), selected numeri-
cally as shown in Example 33. Note that the indexing starts from zero.
47
Example 33: Annotation forms for OpenType fonts.
123456789
⑴⑵⑶⑷⑸⑹⑺⑻⑼
①②③④⑤⑥⑦⑧⑨
❶❷❸❹❺❻❼❽❾
\def\test{\makebox[2cm][l]{\texta}%
\makebox[2.5cm][l]{\textb}%
\makebox[2.5cm][l]{abcdef}}
\fontspec{Hiragino Mincho Pro}
abcdef {\addfontfeature{CharacterWidth=Proportional}\test}\\
ようこそ ワカヨタレソ abcdef {\addfontfeature{CharacterWidth=Full}\test}\\
ワカヨタレソ abcdef {\addfontfeature{CharacterWidth=Half}\test}
48
Table 17: Options for the OpenType font feature ‘CJKShape’.
49
Part V
Commands for accents and symbols
(‘encodings’)
The functionality described in this section is experimental.
In the pre-Unicode era, significant work was required by LATEX to ensure that input char-
acters in the source could be interpreted correctly depending on file encoding, and that glyphs
in the output were selected correctly depending on the font encoding. With Unicode, we have
the luxury of a single file and font encoding that is used for both input and output.
While this may provide some illusion that we could get away simply with typing Unicode
text and receive correct output, this is not always the case. For a start, hyphenation in particular
is language-specific, so tags should be used when switch between languages in a document.
The babel and polyglossia packages both provide features for this.
Multilingual documents will often use different fonts for different languages, not just for
style, but for the more pragmatic reason that fonts do not all contain the same glyphs. (In fact,
only test fonts such as Code2000 provide anywhere near the full Unicode coverage.) Indeed,
certain fonts may be perfect for a certain application but miss a handful of necessary diacritics
or accented letters. In these cases, fontspec can leverage the font encoding technology built
into LATEX2 to provide on a per-font basis either provide fallback options or error messages
when a desired accent or symbol is not available. However, at present these features can only
be provided for input using LATEX commands rather than Unicode input; for example, typing
\`e instead of è or \textcopyright instead of © in the source file.
The most widely-used encoding in LATEX 2ε was T1 with companion ‘TS1’ symbols pro-
vided by the textcomp package. These encodings provided glyphs to typeset text in a variety of
western European languages. As with most legacy LATEX 2ε input methods, accents and sym-
bols were input using encoding-dependent commands such as \`e as described above. As of
2017, in LATEX 2ε on XETEX and LuaTEX, the default encoding is TU, which uses Unicode for
input and output. The TU encoding provides appropriate encoding-dependent definitions for
input commands to match the coverage of the T1+TS1 encodings. Wider coverage is not pro-
vided by default since (a) each font will provide different glyph coverage, and (b) it is expected
that most users will be writing with direct Unicode input.
For those users who do need finer-grained control, fontspec provides an interface for a
more extensible system.
57 \DeclareTextSymbol{\CYRIE}{OT2}{5}
58 \DeclareTextSymbol{\CYRDJE}{OT2}{6}
59 \DeclareTextSymbol{\CYRTSHE}{OT2}{7}
60 \DeclareTextSymbol{\cyrnje}{OT2}{8}
50
61 \DeclareTextSymbol{\cyrlje}{OT2}{9}
62 \DeclareTextSymbol{\cyrdzhe}{OT2}{10}
To recreate this encoding in a form suitable for fontspec, create a new file named, say,
fontrange-cyr.def and populate it with
...
\DeclareTextSymbol{\CYRIE} {\LastDeclaredEncoding}{"0404}
\DeclareTextSymbol{\CYRDJE} {\LastDeclaredEncoding}{"0402}
\DeclareTextSymbol{\CYRTSHE}{\LastDeclaredEncoding}{"040B}
\DeclareTextSymbol{\cyrnje} {\LastDeclaredEncoding}{"045A}
\DeclareTextSymbol{\cyrlje} {\LastDeclaredEncoding}{"0459}
\DeclareTextSymbol{\cyrdzhe}{\LastDeclaredEncoding}{"045F}
...
The numbers "0404, "0402, …, are the Unicode slots (in hexadecimal) of each glyph respec-
tively. The fontspec package provides a number of shorthands to simplify this style of input;
in this case, you could also write
\EncodingSymbol{\CYRIE}{"0404}
...
To use this encoding in a fontspec font, you would first add this to your preamble:
\DeclareUnicodeEncoding{unicyr}{
\input{fontrange-cyr.def}
}
\setmainfont{...}[NFSSEncoding=unicyr]
The first argument unicyr is the name of the ‘encoding’ to use in the font family. (There’s
nothing special about the name chosen but it must be unique.) The second argument to
\DeclareUnicodeEncoding also allows adjustments to be made for per-font changes. We’ll
cover this use case in the next section.
\DeclareUnicodeEncoding{unicyr}{
\input{tuenc.def}
\input{fontrange-cyr.def}
\EncodingSymbol{\textruble}{"20BD}
}
51
Of course if you consistently add a number of symbols to an encoding it would be a good idea
to create a new fontrange-XX.def file to suit your needs.
When removing symbols, use the \UndeclareSymbol{⟨cmd⟩} command. For example,
if you a loading a font that you know is missing, say, the interrobang (not that unusual a
situation), you might write:
\DeclareUnicodeEncoding{nobang}{
\input{tuenc.def}
\UndeclareSymbol\textinterrobang
}
Provided that you use the command \textinterrobang to typeset this symbol, it will appear
in fonts with the default encoding, while in any font loaded with the nobang encoding an
attempt to access the symbol will either use the default fallback definition or return an error,
depending on the symbol being undeclared.
The third use case is to redefine a symbol or accent. The most common use case in this
scenario is to adjust a specific accent command to either fine-tune its placement or to ‘fake’ it
entirely. For example, the underdot diacritic is used in typeset Sanskrit, but it is not necessarily
included as an accent symbol is all fonts. By default the underdot is defined in TU as:
\EncodingAccent{\d}{"0323}
For fonts with a missing (or poorly-spaced) "0323 accent glyph, the ‘traditional’ TEX fake
accent construction could be used instead:
\DeclareUnicodeEncoding{fakeacc}{
\input{tuenc.def}
\EncodingCommand{\d}[1]{%
\hmode@bgroup
\o@lign{\relax#1\crcr\hidewidth\ltx@sh@ft{-1ex}.\hidewidth}%
\egroup
}
}
\newfontfamily\sanskitfont{CharisSIL}
\newfontfamily\titlefont{Posterama}[NFSSEncoding=fakeacc]
To reiterate from above, typing this input with Unicode text (‘kalitaṃ’) will bypass this en-
coding mechanism and you will receive only what is contained literally within the font.
52
3 Summary of commands
The LATEX 2ε kernel provides the following font encoding commands suitable for Unicode en-
codings:
\DeclareTextCommand{⟨command⟩}{⟨encoding⟩}[⟨num⟩][⟨default⟩]{⟨code⟩}
\DeclareUnicodeAccent{⟨command⟩}{⟨encoding⟩}{⟨slot⟩}
\DeclareTextSymbol{⟨command⟩}{⟨encoding⟩}{⟨slot⟩}
\DeclareTextComposite{⟨command⟩}{⟨encoding⟩}{⟨letter⟩}{⟨slot⟩}
\DeclareTextCompositeCommand{⟨command⟩}{⟨encoding⟩}{⟨letter⟩}{⟨code⟩}
\UndeclareTextCommand{⟨command⟩}{⟨encoding⟩}
See fntguide.pdf for full documentation of these. As shown above, the following short-
hands are provided by fontspec to simplify the process of defining Unicode font range encod-
ings:
\EncodingCommand{⟨command⟩}[⟨num⟩][⟨default⟩]{⟨code⟩}
\EncodingAccent{⟨command⟩}{⟨code⟩}
\EncodingSymbol{⟨command⟩}{⟨code⟩}
\EncodingComposite{⟨command⟩}{⟨letter⟩}{⟨slot⟩}
\EncodingCompositeCommand{⟨command⟩}{⟨letter⟩}{⟨code⟩}
\UndeclareSymbol{⟨command⟩}
\UndeclareAccent{⟨command⟩}
\UndeclareCommand{⟨command⟩}
\UndeclareComposite{⟨command⟩}{⟨letter⟩}
53
Part VI
LuaTEX-only font features
1 Different font technologies and shapers
LuaTEX does not directly support any font rendering technologies out of the box, it requires ad-
ditional functionality to be added to properly support and control technologies such as Open-
Type.
Using the Renderer feature, there are a number of options that fontspec can pass to
the engine to control which font technology is being used. Pre-2019, there were two options
provided by luaotfload that generally did not require user intervention.
• Renderer = Base : a simplified mode useful only in a limited number of situations such
as mathematics typesetting.
From 2019 the possibility of using the Harfbuzz text shaping engine within LuaTEX has
been developed by Khaled Hosny. When running a suitable LuaTEX engine with Harfbuzz
support, fontspec provides the following options:
• Renderer = OpenType : use the Harfbuzz engine with the OpenType shaper.
• Renderer = AAT : use the Harfbuzz engine with the AAT shaper.
• Renderer = Graphite : use the Harfbuzz engine with the Graphite shaper.
• Renderer = ⟨foo⟩ : use the Harfbuzz engine with the ⟨foo⟩ shaper.
Support for the Harfbuzz renderer is preliminary and may be improved over time. Please
treat the interface for Harfbuzz fonts as subject to change.
54
Figure 1: An example of custom font features.
\documentclass{article}
\usepackage{fontspec}
\directlua{
fonts.handlers.otf.addfeature {
name = "oneb",
type = "substitution",
data = {
["1"] = "one.ss01",
}
}
}
\setmainfont{Vollkorn-Regular.otf}[RawFeature=+oneb]
\begin{document}
1234567890
\end{document}
55
Part VII
Fonts and features with XETEX
1 XETEX-only font features
The features described here are available for any font selected by fontspec.
1.1 Mapping
The Mapping feature enables a XETEX text-mapping scheme, with an example shown in Exam-
ple 37.
Only one mapping can be active at a time and a second call to Mapping will override the
first. Using the tex-text mapping is also equivalent to writing Ligatures=TeX. The use of
the latter syntax is recommended for better compatibility with LuaTEX documents.
\fontspec{texgyrepagella-regular.otf}[Mapping=tex-text]
“¡A small amount of—text!” ``!`A small amount of---text!''
56
1.3 Optical font sizes
Multiple Master fonts are parameterised over orthogonal font axes, allowing continuous se-
lection along such features as weight, width, and optical size. Whereas an OpenType font will
have only a few separate optical sizes, a Multiple Master font’s optical size can be specified
over a continuous range. Unfortunately, this flexibility makes it harder to create an automatic
interface through LATEX, and the optical size for a Multiple Master font must always be speci-
fied explicitly.
\fontspec{Minion MM Roman}[OpticalSize=11]
MM optical size test \\
\fontspec{Minion MM Roman}[OpticalSize=47]
MM optical size test \\
\fontspec{Minion MM Roman}[OpticalSize=71]
MM optical size test \\
\fontspec{Charis SIL}[
Renderer=Graphite,
RawFeature={Uppercase Eng alternates=Large eng on baseline}]
Ŋ
共産主義者は
共産 主 義 者は
57
Here’s another:
\fontspec{AwamiNastaliq-Regular.ttf}[Renderer=Graphite] ^^^^06b5
\addfontfeature{RawFeature={Lam with V=V over bowl}} ^^^^06b5
macOS’s font technology began life before the ubiquitous-OpenType era and revolved
around the Apple-invented ‘AAT’ font format. This format had some advantages (and other
disadvantages) but it never became widely popular in the font world.
Nonetheless, this is the font format that was first supported by XETEX (due to its pedigree
on macOS in the first place) and was the first font format supported by fontspec. A number
of fonts distributed with macOS are still in the AAT format, such as ‘Skia’.
3.1 Ligatures
Ligatures refer to the replacement of two separate characters with a specially drawn
glyph for functional or æsthetic reasons. For AAT fonts, you may choose from any combina-
tion of Required, Common, Rare (or Discretionary), Logos, Rebus, Diphthong, Squared,
AbbrevSquared, and Icelandic.
Some other Apple AAT fonts have those ‘Rare’ ligatures contained in the Icelandic fea-
ture. Notice also that the old TEX trick of splitting up a ligature with an empty brace pair does
not work in XETEX; you must use a 0 pt kern or \hbox (e.g., \null) to split the characters up if
you do not want a ligature to be performed (the usual examples for when this might be desired
are words like ‘shelffull’).
3.2 Letters
The Letters feature specifies how the letters in the current font will look. For AAT fonts, you
may choose from Normal, Uppercase, Lowercase, SmallCaps, and InitialCaps.
3.3 Numbers
The Numbers feature defines how numbers will look in the selected font. For AAT fonts, they
may be a combination of Lining or OldStyle and Proportional or Monospaced (the latter
is good for tabular material). The synonyms Uppercase and Lowercase are equivalent to
Lining and OldStyle, respectively. The differences have been shown previously in Section 2
on page 20.
58
3.4 Contextuals
This feature refers to glyph substitution that vary by their position; things like contextual
swashes are implemented here. The options for AAT fonts are WordInitial, WordFinal (Ex-
ample ??), LineInitial, LineFinal, and Inner (Example ??, also called ‘non-final’ some-
times). As non-exclusive selectors, like the ligatures, you can turn them off by prefixing their
name with No.
3.6 Fractions
Many fonts come with the capability to typeset various forms of fractional material. This is
accessed in fontspec with the Fractions feature, which may be turned On or Off in both AAT
and OpenType fonts.
In AAT fonts, the ‘fraction slash’ or solidus character, is to be used to create fractions. When
Fractions are turned On, then only pre-drawn fractions will be used.
Using the Diagonal option (AAT only), the font will attempt to create the fraction from
superscript and subscript characters.
Some (Asian fonts predominantly) also provide for the Alternate feature.
3.7 Variants
The Variant feature takes a single numerical input for choosing different alphabetic shapes.
See Section 1 on page 61 for a way to assign names to variants, which should be done on a
per-font basis.
3.8 Alternates
Selection of Alternates again must be done numerically. See Section 1 on page 61 for a way
to assign names to alternates, which should be done on a per-font basis.
3.9 Style
The options of the Style feature are defined in AAT as one of the following: Display,
Engraved, IlluminatedCaps, Italic, Ruby,11 TallCaps, or Titling.
Typical examples for these features are shown in 3.1.12.
11 ‘Ruby’ refers to a small optical size, used in Japanese typography for annotations.
59
3.10 CJK shape
There have been many standards for how CJK ideographic glyphs are ‘supposed’ to look. Some
fonts will contain many alternate glyphs in order to be able to display these gylphs correctly in
whichever form is appropriate. Both AAT and OpenType fonts support the following CJKShape
options: Traditional, Simplified, JIS1978, JIS1983, JIS1990, and Expert. OpenType
also supports the NLC option.
3.12 Diacritics
Diacritics are marks, such as the acute accent or the tilde, applied to letters; they usually in-
dicate a change in pronunciation. In Arabic scripts, diacritics are used to indicate vowels. You
may either choose to Show, Hide or Decompose them in AAT fonts. The Hide option is for
scripts such as Arabic which may be displayed either with or without vowel markings. E.g.,
\fontspec[Diacritics=Hide]{...}
Some older fonts distributed with macOS included ‘O/’ etc. as shorthand for writing ‘Ø’
under the label of the Diacritics feature. If you come across such fonts, you’ll want to turn
this feature off (imagine typing hello/goodbye and getting ‘helløgoodbye’ instead!) by de-
composing the two characters in the diacritic into the ones you actually want. I recommend
using the proper LATEX input conventions for obtaining such characters instead.
3.13 Annotation
Various Asian fonts are equipped with a more extensive range of numbers and numerals in dif-
ferent forms. These are accessed through the Annotation feature with the following options:
Off, Box, RoundedBox, Circle, BlackCircle, Parenthesis, Period, RomanNumerals, Diamond,
BlackSquare, BlackRoundSquare, and DoubleCircle.
60
Part VIII
Customisation and programming
interface
This chapter describes the current interfaces and hooks that use fontspec for various macro
programming purposes.
\newopentypefeature{Style}{NoLocalForms}{-locl}
\newfontfeature In case the above commands do not accommodate the desired font feature (perhaps a
new XETEX feature that fontspec hasn’t been updated to support), a command is provided to
pass arbitrary input into the font selection string:
\newfontfeature{⟨name⟩}{⟨input string⟩}
For example, Zapfino used to contain an AAT feature ‘Avoid d-collisions’. To access it with
this package, you could do some like the following:
\newAATfeature{Alternate}{HoeflerSwash}{17}{1}
\fontspec{Hoefler Text Italic}[Alternate=HoeflerSwash]
This is XeTeX by Jonathan Kew. This is XeTeX by Jonathan Kew.
61
The advantage to using the \newAATfeature and \newopentypefeature commands in-
stead of \newfontfeature is that they check if the selected font actually contains the desired
font feature at load time. By contrast, \newfontfeature will not give a warning for improper
input.
\fontspec{texgyrepagella-regular.otf}[RawFeature=+smcp]
PAGELLA SMALL CAPS Pagella small caps
62
4 Renaming existing features & options
\aliasfontfeature If you don’t like the name of a particular font feature, it may be aliased to another with
the \aliasfontfeature{⟨existing name⟩}{⟨new name⟩} command, such as shown in Exam-
ple 41.
Spaces in feature (and option names, see below) are allowed. (You may have noticed this
already in the lists of OpenType scripts and languages).
\aliasfontfeatureoption If you wish to change the name of a font feature option, it can be aliased to another with
the command \aliasfontfeatureoption{⟨font feature⟩}{⟨existing name⟩}{⟨new name⟩},
such as shown in Example 42.
This example demonstrates an important point: when aliasing the feature options, the
original feature name must be used when declaring to which feature the option belongs.
Only feature options that exist as sets of fixed strings may be altered in this way. That
is, Proportional can be aliased to Prop in the Letters feature, but 550099BB cannot be
substituted for Purple in a Color specification. For this type of thing, the \newfontfeature
command should be used to declare a new, e.g., PurpleColor feature:
\newfontfeature{PurpleColor}{color=550099BB}
Except that this example was written before support for named colours was implemented. But
you get the idea.
5 Programming interface
5.1 Variables
\l_fontspec_family_tl In some cases, it is useful to know what the LATEX font family of a specific fontspec font is. Af-
\l_fontspec_font ter a \fontspec-like command, this is stored inside the \l_fontspec_family_tl macro. Oth-
erwise, LATEX’s own \f@family macro can be useful here, too. The raw TEX font that is defined
from the ‘base’ font in the family is stored in \l_fontspec_font.
\g_fontspec_encoding_tl Package authors who need to load fonts with legacy LATEX NFSS commands may also need
to know what the default font encoding is. Since this has changed from EU1/EU2 to TU, it is
best to use the variable \g_fontspec_encoding_tl instead.
\aliasfontfeature{ItalicFeatures}{IF}
\fontspec{Hoefler Text}[IF = {Alternate=1}]
Roman Letters And Swash Roman Letters \itshape And Swash
63
Example 42: Renaming font feature options.
\aliasfontfeature{VerticalPosition}{Vert Pos}
\aliasfontfeatureoption{VerticalPosition}{ScientificInferior}{Sci Inf}
\fontspec{LinLibertine_R.otf}[Vert Pos=Sci Inf]
Sciₑntific Infₑriₒr: ₁₂₃₄₅ Scientific Inferior: 12345
5.3 Conditionals
The following functions in expl3 syntax may be used for writing code that interfaces with
fontspec-loaded fonts. The following conditionals are all provided in TF, T, and F forms.
\fontspec_if_fontspec_font:TF Test whether the currently selected font has been loaded by fontspec.
\fontspec_if_opentype:TF Test whether the currently selected font is an OpenType font. Always true for LuaTEX fonts.
64
(End definition for \fontspec_if_opentype:TF. This function is documented on page ??.)
\fontspec_if_small_caps:TF Test whether the currently selected font has a ‘small caps’ face to be selected with \scshape
or similar. Note that testing whether the font has the Letters=SmallCaps font feature is
sufficient but not necessary for this command to return true, since small caps can also be
loaded from separate font files. The logic of this command is complicated by the fact that
fontspec will merge shapes together (for italic small caps, etc.).
(End definition for \fontspec_if_small_caps:TF. This function is documented on page ??.)
\fontspec_if_feature:nTF Test whether the currently selected font contains the raw OpenType feature #1. E.g.: \fontspec_if_feature:n
Returns false if the font is not loaded by fontspec or is not an OpenType font.
(End definition for \fontspec_if_feature:nTF. This function is documented on page ??.)
\fontspec_if_feature:nnnTF Test whether the currently selected font with raw OpenType script tag #1 and raw OpenType
language tag #2 contains the raw OpenType feature tag #3. E.g.: \fontspec_if_feature:nnnTF {latn} {RO
Returns false if the font is not loaded by fontspec or is not an OpenType font.
(End definition for \fontspec_if_feature:nnnTF. This function is documented on page ??.)
\fontspec_if_script:nTF Test whether the currently selected font contains the raw OpenType script #1. E.g.: \fontspec_if_script:nTF
Returns false if the font is not loaded by fontspec or is not an OpenType font.
(End definition for \fontspec_if_script:nTF. This function is documented on page ??.)
\fontspec_if_language:nTF Test whether the currently selected font contains the raw OpenType language tag #1. E.g.:
\fontspec_if_language:nTF {ROM} {True} {False}. Returns false if the font is not
loaded by fontspec or is not an OpenType font.
(End definition for \fontspec_if_language:nTF. This function is documented on page ??.)
\fontspec_if_language:nnTF Test whether the currently selected font contains the raw OpenType language tag #2 in script
#1. E.g.: \fontspec_if_language:nnTF {cyrl} {SRB} {True} {False}. Returns false if
the font is not loaded by fontspec or is not an OpenType font.
(End definition for \fontspec_if_language:nnTF. This function is documented on page ??.)
\fontspec_if_current_script:nTF Test whether the currently loaded font is using the specified raw OpenType script tag #1.
(End definition for \fontspec_if_current_script:nTF. This function is documented on page ??.)
\fontspec_if_current_language:nTF Test whether the currently loaded font is using the specified raw OpenType language tag #1.
(End definition for \fontspec_if_current_language:nTF. This function is documented on page ??.)
65