summaryrefslogtreecommitdiff
path: root/macros/latex/contrib/fontspec/fontspec-doc-fontsel.tex
blob: c1900322c09555ec96e6dfc04a8df15e9e24c587 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
%%^^A%%  fontspec-doc-fontsel.tex -- part of FONTSPEC <wspr.io/fontspec>

\documentclass[a4paper]{l3doc}
\usepackage{fontspec-doc-style}
\showexamplesfalse
\begin{document}

\part{General font selection}

\section{Main commands}
\label{sec:main-cmd}

This section concerns the variety of commands that can be used to select
fonts.

\bigskip
\cmdbox{%
  \CMD{\string\setmainfont}\marg{font}\oarg{font features}\\
  \CMD{\string\setsansfont}{\color[gray]{0.5}\marg{font}\oarg{font features}}\\
  \CMD{\string\setmonofont}{\color[gray]{0.5}\marg{font}\oarg{font features}}
}

These are the main font-selecting commands of this package which select the standard fonts used in a document, as shown in \exref{fontload}.
Here, the scales of the fonts have been chosen to equalise their
lowercase letter heights. The \feat{Scale} font feature will be discussed
further in \vref{sec:font-ind-features}, 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 \cs{setmainfont} and \cs{setsansfont} commands.
These defaults (and further customisations possible) are discussed in \vref{sec:defaults}.

\bigskip
\cmdbox{%
  \CMD{\string\newfontfamily}\meta{cmd}\marg{font}\oarg{font features}\\
  \CMD{\string\setfontfamily}{\color[gray]{0.5}\meta{cmd}\marg{font}\oarg{font features}}\\
  \CMD{\string\renewfontfamily}{\color[gray]{0.5}\meta{cmd}\marg{font}\oarg{font features}}
  \CMD{\string\providefontfamily}{\color[gray]{0.5}\meta{cmd}\marg{font}\oarg{font features}}
}

These commands define new font family commands (like \cs{rmfamily}).
The |new| command checks if \meta{cmd} has been defined, and issues an error if so.
The |renew| command checks if \meta{cmd} has been defined, and issues an error if not.
The |provide| command checks if \meta{cmd} has been defined, and silently aborts if so.
The |set| command never checks; use at your own risk.



\bigskip
\cmdbox{%
  \CMD{\string\fontspec}\marg{font}\oarg{font features}
}

The plain \cs{fontspec} command is not generally recommended for document use. It is an
ad hoc commands best suited for testing and loading fonts on a one-off basis.

All of the commands listed above accept comma-separated
\meta{font feature}=\meta{option} lists; these are described later:
\begin{itemize}
\item For general font features, see \vref{sec:font-ind-features}
\item For OpenType fonts, see Part~\vref{sec:opentype-features}
\item For \XeTeX-only general font features, see Part~\vref{sec:xetex-features}
\item For \LuaTeX-only general font features, see Part~\vref{sec:luatex-features}
\item For features for \AAT\ fonts in \XeTeX, see \vref{sec:aat-features}
\end{itemize}

\begin{Lexample}{fontload}{Loading the default, sans serif, and monospaced fonts.}
  \setmainfont{texgyrebonum-regular.otf}
  \setsansfont{lmsans10-regular.otf}[Scale=MatchLowercase]
  \setmonofont{Inconsolatazi4-Regular.otf}[Scale=MatchLowercase]

  \rmfamily Pack my box with five dozen liquor jugs\par
  \sffamily Pack my box with five dozen liquor jugs\par
  \ttfamily Pack my box with five dozen liquor jugs
\end{Lexample}

\section{Font selection}

In both \LuaTeX\ and \XeTeX, fonts can be selected (using the \meta{font} argument in \ref{sec:main-cmd}) 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.


\subsection{By font name}

Fonts known to \LuaTeX\ or \XeTeX\ may be loaded by their standard names as
you'd speak them out loud, such as \emph{Times New Roman} or
\emph{Adobe Garamond}.
`Known to' in this case generally means `exists in a standard fonts location'
such as |~/Library/Fonts| on \MacOSX, or |C:\Windows\Fonts| on Windows.
In \LuaTeX, fonts found in the \textsc{texmf} tree can also be loaded by name.
In \XeTeX, fonts found in the \textsc{texmf} tree can be loaded in Windows and Linux,
but not on \MacOSX.

The simplest example might be something like
\begin{Verbatim}
  \setmainfont{Cambria}[ ... ]
\end{Verbatim}
in which the bold and italic fonts will be found automatically
(if they exist) and are immediately accessible with the usual
\cs{textit} and \cs{textbf} commands.

The `font name' can be found in various ways, such as by looking in the name listed in a application like \emph{Font Book} on Mac~OS~X.
Alternatively, \TeX{}Live contains the \texttt{otfinfo} command line program, which can query this information; for example:
\begin{Verbatim}
    otfinfo -i `kpsewhich lmroman10-regular.otf`
\end{Verbatim}
results in a line that reads:
\begin{Verbatim}
  Preferred family:    Latin Modern Roman
\end{Verbatim}
(The `preferred family' name is usually better than the `family' name.)

\paragraph{\LuaTeX\ users only}
In order to load fonts by their name rather than by their filename (\eg,
`Latin Modern Roman' instead of `ec-lmr10'), you may need to run the script
\texttt{luaotfload-tool}, which is distributed with the \pkg{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 \pkg{luaotfload} documentation for more information.


\subsection{By file name}
\label{sec: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 installed 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 \path{/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 \texttt{.fontspec} file is supplied for the font family (see section~\ref{sec:fontspecfile}).
We'll give some first examples specifying everything explicitly:
\begin{Verbatim}
  \setmainfont{texgyrepagella-regular.otf}[
       BoldFont       = texgyrepagella-bold.otf ,
       ItalicFont     = texgyrepagella-italic.otf ,
       BoldItalicFont = texgyrepagella-bolditalic.otf ]
\end{Verbatim}
\pkg{fontspec} knows that the font is to be selected by file name by the
presence of the `|.otf|' extension.
An alternative is to specify the extension separately, as shown following:
\begin{Verbatim}
  \setmainfont{texgyrepagella-regular}[
       Extension      = .otf ,
       BoldFont       = texgyrepagella-bold ,
       ... ]
\end{Verbatim}
If desired, an abbreviation can be applied to the font names based on the
mandatory `font name' argument:
\begin{Verbatim}
  \setmainfont{texgyrepagella}[
       Extension      = .otf ,
       UprightFont    = *-regular ,
       BoldFont       = *-bold ,
       ... ]
\end{Verbatim}
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:
\begin{Verbatim}
  \setmainfont{texgyrepagella}[
       Path           = /Users/will/Fonts/ ,
       UprightFont    = *-regular ,
       BoldFont       = *-bold ,
       ... ]
\end{Verbatim}
Note that \XeTeX\ and \LuaTeX\ are able to load the font without giving an
extension, but \pkg{fontspec} must know to search for the file; this can can
be indicated by using the |Path| feature without an argument:
\begin{Verbatim}
  \setmainfont{texgyrepagella-regular}[
       Path, BoldFont = texgyrepagella-bold,
       ... ]
\end{Verbatim}
My preference is to always be explicit and include the extension; this also allows \pkg{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.


\subsection{By custom file name using a \texttt{.fontspec} file}
\label{sec:fontspecfile}

When \pkg{fontspec} is first asked to load a font, a font settings file is searched
for with the name `\meta{fontname}\texttt{.fontspec}'.\footnote{Located in the current folder or within a standard \texttt{texmf} location.}
If you want to \emph{disable} this feature on a per-font basis, use the \feat{IgnoreFontspecFile} font option.

The contents of this file can be used to specify font shapes and font features without having to have this information present within each document.
Therefore, it can be more flexible than the alternatives listed above.

When searching for this \texttt{.fontspec} file, \meta{fontname} is stripped of spaces and file extensions are omitted.
For example, given |\setmainfont{TeX Gyre Adventor}|, the \texttt{.fontspec} file would be
called \texttt{TeXGyreAdventor.fontspec}.
If you wanted to transparently load options for |\setmainfont{texgyreadventor-regular.otf}|, the configuration
file would be \texttt{texgyreadventor-regular.fontspec}.

N.B. that while spaces are stripped, the lettercase of the names should match.

This mechanism can be used to define custom names or aliases for your font collections.
The syntax within this file follows from the \cs{defaultfontfeatures}, defined in more detail later but mirroring the standard \pkg{fontspec} font loading syntax.
As an example, suppose we're defining a font family to be loaded with \verb|\setmainfont{My Charis}|.
The corresponding \texttt{MyCharis.fontspec} file would contain, say,
\begin{Verbatim}
  \defaultfontfeatures[My Charis]
    {
      Extension = .ttf ,
      UprightFont    = CharisSILR,
      BoldFont       = CharisSILB,
      ItalicFont     = CharisSILI,
      BoldItalicFont = CharisSILBI,
      % <any other desired options>
    }
\end{Verbatim}
The optional argument to \cs{defaultfontfeatures} must exactly match that requested by the font loading command (\verb|\setmainfont|, etc.) --- in particular note that spaces are significant here, so |\setmainfont{MyCharis}| will not `see' the default font feature setting within the \texttt{.fontspec} file.

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:
\begin{Verbatim}
  \defaultfontfeatures[CharisSILR]{Color=blue}
  \defaultfontfeatures[CharisSILB]{Color=red}
\end{Verbatim}
Such configuration lines could be stored either inline inside \texttt{My Charis.fontspec}
or within their own \texttt{.fontspec} files; in this way, \pkg{fontspec} is designed to
handle `nested' configuration options.

Where \cs{defaultfontfeatures} is being used to specify font faces by a custom name,
the \feat{Font} feature is used to set the filename of the font face. For example:
\begin{Verbatim}
  \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>
    }
\end{Verbatim}
The \pkg{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.


\subsection{Querying whether a font `exists'}

\cmdbox{
  \CMD{\string\IfFontExistsTF}\marg{font name}\marg{true branch}\marg{false branch}
}

The conditional \cs{IfFontExistsTF} is provided to test whether the \meta{font name} exists or is loadable.
If it is, the \meta{true branch} code is executed; otherwise, the \meta{false branch} code is.

This command can be slow since the engine may resort to scanning the filesystem for a missing font.
Nonetheless, it has been a popular request for users who wish to define `fallback fonts' for their documents for greater portability.

In this command, the syntax for the \meta{font name} is a restricted/simplified version of the font loading syntax used for \cs{fontspec} and so on.
Fonts to be loaded by filename are detected by the presence of an appropriate extension (|.otf|, etc.), and paths should be included inline.
E.g.:
\begin{Verbatim}
  \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}
\end{Verbatim}

The \cs{IfFontExistsTF} command is a synonym for the programming interface function \cs{fontspec_font_if_exist:nTF} (\vref*{sec:api}).



\section{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 \cs{fontspec} for every use. While the \cs{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 \cmd\newfontfamily\ command and variants,
outlined in \vref{sec:main-cmd} and demonstrated in \exref{nff}.
This macro should be used to create commands that would be used in
the same way as \cmd\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 \cs{emph}) define it using regular \LaTeX\
commands:
\begin{Verbatim}
  \newcommand\textnote[1]{{\notefont #1}}
  \textnote{This is a note.}
\end{Verbatim}
Note that the double braces are intentional; the inner pair are used to
to delimit the scope of the font change.

\begin{Lexample}{nff}{Defining new font families.}
  \newfontfamily\notefont{Kurier}
  \notefont This is a \emph{note}.
\end{Lexample}

\emph{Comment for advanced users:}
The commands defined by \cs{newfontfamily} (and \cs{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,
\begin{Verbatim}
\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}
\end{Verbatim}


\section{Commands to select single font faces}

\cmdbox{%
  \CMD{\string\newfontface}\meta{cmd}\marg{font}\oarg{font features}\\
  \CMD{\string\setfontface}{\color[gray]{0.5}\meta{cmd}\marg{font}\oarg{font features}}\\
  \CMD{\string\renewfontface}{\color[gray]{0.5}\meta{cmd}\marg{font}\oarg{font features}}\\
  \CMD{\string\providefontface}{\color[gray]{0.5}\meta{cmd}\marg{font}\oarg{font features}}
}

Sometimes only a specific font face is desired, without accompanying italic or bold variants
being automatically selected.
This is common when selecting a fancy italic font, say, that has swash features unavailable
in the upright forms. \cmd\newfontface\ is used for this purpose, shown
in \exref{nfface}, which is repeated in \vref{sec:contextuals}.

\begin{Xexample}{nfface}{Defining a single font face.}
  \newfontface\fancy{Hoefler Text Italic}%
      [Contextuals={WordInitial,WordFinal}]
  \fancy where is all the vegemite
  % \emph, \textbf, etc., all don't work
\end{Xexample}


\subsection{More control over font shape selection}
\label{sec:bfitfonts}

\cmdbox{
 \feat{BoldFont} = \meta{font name} \\
 \feat{ItalicFont} = \meta{font name} \\
 \feat{~BoldItalicFont} = \meta{font name} \\
 \feat{SlantedFont} = \meta{font name} \\
 \feat{BoldSlantedFont} = \meta{font name} \\
 \feat{SmallCapsFont} = \meta{font name} \\
 \feat{UprightFont} = \meta{font name}
}

The automatic bold, italic, and bold italic font selections will not be
adequate for the needs of every font: while some fonts mayn't even
have bold or italic shapes, in which case a skilled (or lucky)
designer may be able to chose well-matching accompanying shapes from
a different font altogether, others can have a range of bold and
italic fonts to chose among.  The \feat{BoldFont} and
\feat{ItalicFont} features are provided for these situations. If only
one of these is used, the bold italic font is requested as the
default from the \emph{new} font. See \exref{bff}.

\begin{Xexample}{bff}{Explicit selection of the bold font.}
  \fontspec{Helvetica Neue UltraLight}%
           [BoldFont={Helvetica Neue}]
                Helvetica Neue UltraLight         \\
  {\itshape     Helvetica Neue UltraLight Italic} \\
  {\bfseries               Helvetica Neue       } \\
  {\bfseries\itshape       Helvetica Neue Italic} \\
\end{Xexample}

If a bold italic shape is not defined, or you want to specify
\emph{both} custom bold and italic shapes, the \feat{BoldItalicFont}
feature is provided.



\subsubsection{Small caps and slanted font shapes}

When a font family has both slanted \emph{and} italic shapes, these may be specified separately using the analogous features \feat{SlantedFont} and \feat{BoldSlantedFont}.
Without these, however, the \LaTeX\ font switches for slanted (\cs{textsl}, \cs{slshape}) will default to the italic shape.

Pre-OpenType, it was common for font families to be distributed with small caps glyphs in separate fonts, due to the limitations on the number of glyphs allowed in the PostScript Type~1 format.
Such fonts may be used by declaring the \feat{SmallCapsFont} of the family you are specifying:
\begin{Verbatim}
  \setmainfont{Minion MM Roman}[
    SmallCapsFont={Minion MM Small Caps & Oldstyle Figures}
  ]
  Roman 123 \\ \textsc{Small caps 456}
\end{Verbatim}
In fact, you should specify the small caps font for each individual bold and
italic shape as in
\begin{Verbatim}
  \setmainfont{ <upright> }[
    UprightFeatures    = { SmallCapsFont={ <sc> } } ,
    BoldFeatures       = { SmallCapsFont={ <bf sc> } } ,
    ItalicFeatures     = { SmallCapsFont={ <it sc> } } ,
    BoldItalicFeatures = { SmallCapsFont={ <bf it sc> } } ,
  ]
  Roman 123 \\ \textsc{Small caps 456}
\end{Verbatim}
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 \ref{sec:bfit-feat} for details.
When an OpenType font is selected for |SmallCapsFont|, the small caps
font feature is \emph{not} automatically enabled. In this case, users
should write instead, if necessary,
\begin{Verbatim}
  \setmainfont{...}[
    SmallCapsFont={...},
    SmallCapsFeatures={Letters=SmallCaps},
  ]
\end{Verbatim}

\subsection{Specifically choosing the \NFSS\ family}

In \LaTeX's \NFSS, font families are defined with names such as `\texttt{ppl}' (Palatino), `\texttt{lmr}' (Latin Modern Roman), and so on, which are selected with the \cs{fontfamily} command:
\begin{Verbatim}
  \fontfamily{ppl}\selectfont
\end{Verbatim}
In \pkg{fontspec}, the family names are auto-generated based on the fontname of the font; for example, writing |\fontspec{Times New Roman}| for the first time would generate an internal font family name of `\texttt{TimesNewRoman(1)}'.
Please note that 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
\begin{Verbatim}
  \usepackage{fancyvrb}
  \fvset{fontfamily=myverbatimfont}
\end{Verbatim}
To select a font for use in this way in \pkg{fontspec} use the \feat{NFSSFamily} feature:\footnote{Thanks to Luca Fascione for the example and motivation for finally implementing this feature.}
\begin{Verbatim}
  \newfontfamily\verbatimfont[NFSSFamily=myverbatimfont]{Inconsolata}
\end{Verbatim}
It is then possible to write commands such as:
\begin{Verbatim}
  \fontfamily{myverbatimfont}\selectfont
\end{Verbatim}
which is essentially the same as writing |\verbatimfont|, or to go back to the orginal example:
\begin{Verbatim}
  \fvset{fontfamily=myverbatimfont}
\end{Verbatim}
Only use this feature when necessary; the in-built font switching commands that \pkg{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 \pkg{fontspec} programming interface; see the function \cs{fontspec_set_family:Nnn} for details (\vref*{sec:api}).

\subsection{Choosing additional \NFSS\ font faces}

\LaTeX's font selection scheme (\NFSS) is more flexible than the \pkg{fontspec} interface discussed up until this point.
It assigns to each font face a \emph{family} (discussed above), a \emph{series} such as bold or light or condensed, and a \emph{shape} such as italic or slanted or small caps.
The \pkg{fontspec} features such as \feat{BoldFont} and so on all assign faces for the default series and shapes of the \NFSS, but it's not uncommon to have font families that have multiple weights and shapes and so on.

If you set up a regular font family with the `standard four' (upright, bold, italic, and bold italic) shapes and then want to use, say, a light font for a certain document element, many users will be perfectly happy to use \cs{newfontface}\cs{\meta{switch}} and use the resulting font \cs{\meta{switch}}.
In other cases, however, it is more convenient or even necessary to load additional fonts using additional \NFSS\ specifiers.

\cmdbox{
  \texttt{FontFace = }\marg{series}\marg{shape}
     \texttt{\char`\{} \texttt{Font = }\meta{font name} \texttt, \meta{features} \texttt{\char`\}} \\
  \texttt{FontFace = }\marg{series}\marg{shape}\marg{font name}
}

The font thus specified will inherit the font features of the main font, with optional additional \meta{features} as requested.
(Note that the optional \marg{features} argument is still surrounded with curly braces.)
Multiple \feat{FontFace} commands may be used in a single declaration to specify multiple fonts.
As an example:
\begin{Verbatim}
  \setmainfont{font1.otf}[
     FontFace = {c}{\updefault}{ font2.otf } ,
     FontFace = {c}{m}{ Font = font3.otf , Color = red }
    ]
\end{Verbatim}
Writing |\fontseries{c}\selectfont| will result in |font2| being selected, which then followed 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 (|\updefault|, 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 \LaTeXe\ font selection guide\footnote{\texttt{texdoc fntguide}} lists series |m| for medium, |b| for bold, |bx| for bold extended, |sb| for semi-bold, and |c| for condensed.
A far more comprehensive listing is included in Appendix~A of Philipp Lehman's `The Font Installation Guide'\footnote{\texttt{texdoc fontinstallationguide}} covering 14 separate weights and 12 separate widths.

The \feat{FontFace} command also interacts properly with the \feat{SizeFeatures} command as follows: (nonsense set of font selection choices)
\begin{Verbatim}
  FontFace = {c}{n}{
    Font = Times ,
    SizeFeatures = {
      { Size =   -10 , Font = Georgia } ,
      { Size = 10-15}                 , % default "Font = Times"
      { Size = 15-   , Font = Cochin  } ,
    },
  },
\end{Verbatim}
Note that if the first \feat{Font} feature is omitted then each size needs its own inner \feat{Font} declaration.

\subsubsection{An example for \cs{strong}}
\label{sec:strong-example}

If you wanted to set up a font family to allow nesting of the \cs{strong}
to easily access increasing font weights, you might use a declaration along the following lines:
\begin{Verbatim}
\setmonofont{SourceCodePro}[
  Extension = .otf ,
  UprightFont = *-Light ,
  BoldFont = *-Regular ,
  FontFace = {k}{n}{*-Black} ,
]
\strongfontdeclare{\bfseries,\fontseries{k}\selectfont}
\end{Verbatim}

Further `syntactic sugar' is planned to make this process somewhat easier.


\subsection{Math(s) fonts}

When \cmd\setmainfont, \cmd\setsansfont\ and \cmd\setmonofont\ are used in the
preamble, they also define the fonts to be used in maths mode inside the
\cmd\mathrm-type commands. This only occurs in the preamble because \LaTeX\
freezes the maths fonts after this stage of the processing. The \pkg{fontspec}
package must also be loaded after any maths font packages (\eg, \pkg{euler})
to be successful. (Actually, it is \emph{only} \pkg{euler} that is the
problem.\note{Speaking of \pkg{euler}, if you want to use its
\texttt{[mathbf]} option, it won't work, and you'll need to put this after
\pkg{fontspec} is loaded instead:
\ttfamily\cmd\AtBeginDocument\char`\{\cmd\DeclareMathAlphabet\cmd\mathbf\char`\{U\char`\}\char`\{eur\char`\}\char`\{b\char`\}\char`\{n\char`\}})

Note that \pkg{fontspec} will not change the font for general mathematics;
only the upright and bold shapes will be affected.
To change the font used for the mathematical symbols, see either the
\pkg{mathspec} package or the \pkg{unicode-math} package.

Note that you may find that loading some maths packages won't be as smooth as
you expect since \pkg{fontspec} (and \XeTeX\ in general) breaks many of the
assumptions of \TeX\ as to where maths characters and accents can be found.
Contact me if you have troubles, but I can't guarantee to be able to fix any
incompatibilities. The Lucida and Euler maths fonts should be fine; for all
others keep an eye out for problems.

\cmdbox{
  \cmd{\setmathrm}\marg{font name}\oarg{font features} \\
  \cmd{\setmathsf}\marg{font name}\oarg{font features} \\
  \cmd{\setmathtt}\marg{font name}\oarg{font features} \\
  \cmd{\setboldmathrm}\marg{font name}\oarg{font features}
}

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
\cmd\fontspec-like commands) to explicitly state which fonts to use
inside such commands as \cmd\mathrm. Additionally, the
\cmd\setboldmathrm\ command allows you define the font used for
\cmd\mathrm\ when in bold maths mode (which is activated with, among
others, \cmd\boldmath).

For example, if you were using Optima with the Euler maths font, you
might have this in your preamble:
\begin{Verbatim}
  \usepackage{mathpazo}
  \usepackage{fontspec}
  \setmainfont{Optima}
  \setmathrm{Optima}
  \setboldmathrm[BoldFont={Optima ExtraBlack}]{Optima Bold}
\end{Verbatim}
These commands are compatible with the \pkg{unicode-math} package.
Having said that, \pkg{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.


\section{Miscellaneous font selecting details}

\paragraph{The optional argument --- from v2.4}
For the first decade of \pkg{fontspec}'s life, optional font features were selected with a bracketed argument before the font name, as in:
\begin{Verbatim}
  \setmainfont[
    lots and lots ,
    and more and more ,
    an excessive number really ,
    of font features could go here
  ]{myfont.otf}
\end{Verbatim}
This always looked like ugly syntax to me, because the most important detail --- the name of the font --- was tucked away at the end.
The order of these arguments has now been reversed:
\begin{Verbatim}
  \setmainfont{myfont.otf}[
    lots and lots ,
    and more and more ,
    an excessive number really ,
    of font features could go here
  ]
\end{Verbatim}
I hope this doesn't cause any problems.
\begin{enumerate}
 \item Backwards compatibility has been preserved, so either input method works.
 \item In fact, you can write
 \begin{Verbatim}
  \fontspec[Ligatures=Rare]{myfont.otf}[Color=red]
 \end{Verbatim}
 if you really felt like it and both sets of features would be applied.

 \item
 Following standard \pkg{xparse} behaviour, there must be no space before the opening bracket; writing
 \begin{Verbatim*}
\fontspec{myfont.otf} [Color=red]
 \end{Verbatim*}
 will result in |[Color=red]| not being recognised an argument and therefore it will be typeset as text. When breaking over lines, write either of:
 \begin{Verbatim}
   \fontspec{myfont.otf}%        \fontspec{myfont.otf}[
     [Color=red]                    Color=Red]
 \end{Verbatim}

\end{enumerate}

\paragraph{Spaces}
\cmd\fontspec\ and \cmd\addfontfeatures\ ignore trailing spaces as
if it were a `naked' control sequence; \eg, `|M. \fontspec{...} N|' and
`|M. \fontspec{...}N|' are the same.

\end{document}

% /©
% ------------------------------------------------
% The FONTSPEC package  <wspr.io/fontspec>
% ------------------------------------------------
% Copyright  2004-2019  Will Robertson, LPPL "maintainer"
% Copyright  2009-2015  Khaled Hosny
% Copyright  2013       Philipp Gesang
% Copyright  2013-2016  Joseph Wright
% ------------------------------------------------
% This package is free software and may be redistributed and/or modified under
% the conditions of the LaTeX Project Public License, version 1.3c or higher
% (your choice): <http://www.latex-project.org/lppl/>.
% ------------------------------------------------
% ©/