forked from latex3/fontspec
-
Notifications
You must be signed in to change notification settings - Fork 0
/
fontspec.dtx
7453 lines (7355 loc) · 275 KB
/
fontspec.dtx
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
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
% \iffalse
%<*internal>
\begingroup
\input l3docstrip.tex
\keepsilent
\usedir{tex/latex/fontspec}
\let\MetaPrefix\relax
\preamble
_________________________________________
The fontspec package for XeLaTeX/LuaLaTeX
(C) 2004--2013 Will Robertson and Khaled Hosny
License information appended.
\endpreamble
\postamble
Copyright 2004--2013 Will Robertson <[email protected]>
Copyright 2009--2013 Khaled Hosny <[email protected]>
Distributable under the LaTeX Project Public License,
version 1.3c or higher (your choice). The latest version of
this license is at: http://www.latex-project.org/lppl.txt
This work is "author-maintained" by Will Robertson.
This work consists of this file fontspec.dtx
and the derived files fontspec.sty,
fontspec.lua,
fontspec.cfg,
fontspec-xetex.tex,
fontspec-luatex.tex,
and fontspec.pdf.
\endpostamble
\askforoverwritefalse
\def\MetaPrefix{-- }
\generate{\file{fontspec.lua} {\from{fontspec.dtx}{lua}}}
\let\MetaPrefix\DoubleperCent
\generate{\file{fontspec.sty} {\from{fontspec.dtx}{fontspec}}}
\generate{\file{fontspec-xetex.sty} {\from{fontspec.dtx}{fontspec,xetexx}}}
\generate{\file{fontspec-luatex.sty} {\from{fontspec.dtx}{fontspec,luatex}}}
\generate{\file{fontspec-patches.sty} {\from{fontspec.dtx}{patches}}}
\generate{\file{fontspec-testsuite.tex}{\from{fontspec.dtx}{testsuite}}}
\nopreamble\nopostamble
\generate{\file{fontspec.cfg} {\from{fontspec.dtx}{cfg}}}
\generate{\file{fontspec-example.tex} {\from{fontspec.dtx}{example}}}
\def\tmpa{plain}
\ifx\tmpa\fmtname\endgroup\expandafter\bye\fi
\generate{\file{fontspec-style.sty} {\from{fontspec.dtx}{doc-style}}}
\endgroup
%</internal>
%
%<*driver>
\ProvidesFile{fontspec.dtx}
%</driver>
%<fontspec&!xetexx&!luatex>\ProvidesPackage{fontspec}
%<fontspec&xetexx>\ProvidesPackage{fontspec-xetex}
%<fontspec&luatex>\ProvidesPackage{fontspec-luatex}
%<patches>\ProvidesPackage{fontspec-patches}
%<*fontspec|patches>
[2013/03/16 v2.3a Font selection for XeLaTeX and LuaLaTeX]
%</fontspec|patches>
%
%<*driver>
\documentclass[a4paper]{ltxdoc}
\usepackage{fontspec-style}
\EnableCrossrefs
\CodelineIndex
\RecordChanges
%\OnlyDescription
\begin{document}
\DocInput{\jobname.dtx}
\end{document}
%</driver>
%
% \fi
%
% \GetFileInfo{fontspec.dtx}
% \makeatletter ^^A% To document @-cmds
% \errorcontextlines=999 ^^A% Show up all my mistakes
%
% \title{The \textsf{fontspec} package\\Font selection for \XeLaTeX\ and \LuaLaTeX}
% \author{
% \textsc{Will Robertson} and \textsc{Khaled Hosny}\\
% \texttt{[email protected]}
% }
% \date{\filedate \qquad \fileversion}
%
% \maketitle
% \tableofcontents
%
% \section{History}
%
% This package began life as a \LaTeX\ interface to select system-installed
% \MacOSX\ fonts in \name{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 Con\TeX t Mk.\,IV is a
% re-write of his powerful typesetting system, taking 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 \pkg{fontspec} to be adapted for \LaTeX\ when run with the
% \LuaTeX\ engine. Elie Roux and Khaled Hosny have been instrumental and
% invaluable with this development work.
%
% \section{Introduction}
%
% The \pkg{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 \pkg{fontspec}, it is necessary to write cumbersome font definition
% files for \LaTeX, since \LaTeX's font selection scheme (known as the
% `\textsc{nfss}') has a lot going on behind the scenes to allow easy
% commands like \cmd\emph\ or \cmd\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 \pkg{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 \pkg{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 example documents \path{fontspec-xetex.tex} and
% \path{fontspec-luatex.tex} for a complete minimal example with each engine.
%
% \subsection{About this manual}
%
% This document is typeset with pdf\LaTeX\ using pre-compiled examples
% that have been generated by either \XeTeX\ or \LuaTeX. You may regenerate
% the examples by removing the \verb|doc-files/| subdirectory and typesetting the
% manual with the following invocation:
% \begin{Verbatim}
% pdflatex -shell-escape fontspec.dtx
% \end{Verbatim}
% Note that many of the examples use fonts that are not included in \TeX~Live
% or MiKTeX, and some of them are non-free fonts that must be purchased.
%
% I'd like to reduce the number of non-free fonts used in this
% manual. If you know any freely available fonts that could be used
% as alternative to any of the fonts in this document, please suggest them
% to me.
% Finally, if any aspect of the documentation is unclear or you would
% like to suggest more examples that could be made, get in touch.
% (Contributions especially welcome.)
%
% \subsection{Acknowledgements}
%
% This package couldn't be 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\"ohning 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 had been the driving force behind the support for \LuaLaTeX, ultimately leading to version 2.0 of the package.
%
% \section{Package loading and options}
%
% For basic use, no package options are required:
% \begin{Verbatim}
% \usepackage{fontspec}
% \end{Verbatim}
% Package options will be introduced below; some preliminary details are discussed first:
%
% \paragraph{\pkg{xunicode}}
% Ross Moore's \pkg{xunicode} package is now automatically loaded for
% users of both \XeLaTeX\ and \LuaLaTeX.
% This package provides backwards compatibility with \LaTeX's methods for accessing extra
% characters and accents (for example, |\%|, |\$|, |\textbullet|, |\"u|, and
% so on), plus many more Unicode characters.
%
% \paragraph{\XeTeX\ users only}
% The \pkg{xltxtra} package adds some minor extra features to \XeLaTeX, including, via the \pkg{metalogo} package, the
% \cmd\XeTeX\ macro to typeset the \XeTeX\ logo. While this package was
% previously recommended, it serves a much smaller r\^ole nowadays and generally
% will not be required.
% Please consult its documentation to assess whether its features are warranted before loading it.
%
% \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{mkluatexfontdb}, 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.
%
% \paragraph{\pkg{babel}}
% \emph{The \pkg{babel} package is not really supported!} Especially Vietnamese,
% Greek, and Hebrew at least might not work correctly, as far as I can tell.
% There's a better chance with Cyrillic and Latin-based languages,
% however---\pkg{fontspec} ensures at least that fonts should load correctly,
% but hyphenation and other matters aren't guaranteed. Under \XeTeX, the
% \pkg{polyglossia} package is recommended instead as a modern replacement for
% \pkg{babel}. For \LuaTeX, the situation is still unresolved.
%
%
%
% \subsection{Maths fonts adjustments}
% By default, \pkg{fontspec} adjusts \LaTeX's
% default maths setup in order to maintain the correct Computer Modern symbols
% when the roman font changes. However, it will attempt to avoid doing this if
% another maths font package is loaded (such as \pkg{mathpazo} or the
% \pkg{unicode-math} package).
%
% If you find that \pkg{fontspec} is incorrectly changing the maths font when it should be
% leaving well enough alone, apply the |[no-math]| package option to manually
% suppress its maths font.
%
% \subsection{Configuration} If you wish to customise any part of the
% \pkg{fontspec} interface (see later in this manual, \vref{sec:newfeatures}
% and~\ref{sec:aliasfontfeature}), this should be done by creating your own
% \texttt{fontspec.cfg} file,
% which will be automatically loaded if it is found by \XeTeX\ or \LuaTeX. 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; \eg\ in Mac\TeX: \path{~/Library/texmf/tex/latex/}.
% The package option |[no-config]| will suppress this behaviour under all circumstances.
%
% \subsection{Warnings}
% \label{sec:quiet-warnings}
%
% This package can give many warnings that can be harmless if you know what
% you're doing. Use the |[quiet]| package option to write these warnings to the
% transcript (\texttt{.log}) file instead.
%
% Use the |[silent]| package option to completely suppress these warnings if you
% don't even want the |.log| file cluttered up.
%
%
%
%
%
% \part{General font selection}
%
% This section concerns the variety of commands that can be used to select
% fonts.
%
% \cmdbox{%
% \CMD{\string\fontspec} \oarg{font features} \marg{font name}\\
% \CMD{\string\setmainfont} \oarg{font features} \marg{font name}\\
% \CMD{\string\setsansfont} \oarg{font features} \marg{font name}\\
% \CMD{\string\setmonofont} \oarg{font features} \marg{font name}\\
% \CMD{\string\newfontfamily} \meta{cmd} \oarg{font features} \marg{font name}
% }
%
% These are the main font-selecting commands of this package.
% The \cs{fontspec} command selects a font for one-time use; all
% others should be used to define the standard fonts used in a document.
% They will be described later in this section.
%
% The font features argument accepts comma separated
% \meta{font feature}=\meta{option} lists; these are described in 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}
%
% \section{Font selection}
%
% In both \LuaTeX\ and \XeTeX, fonts can be selected either by `font name' or
% by `file name'.
%
% \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.
%
% The simplest example might be something like
% \begin{Verbatim}
% \fontspec[ ... ]{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.
%
% TODO: add explanation for how to find out what the `font name' is.
%
%
% \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/2010/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.
% \begin{quote}\itshape
% \textbf{\XeTeX\ \& Mac users only:}
% Note that \XeTeX\ can only select fonts in this way with the |xdvipdfmx| driver, but \XeTeX\ with the |xdv2pdf| driver can only select system-installed fonts
% by font name and not file name. The |xdvipdfmx| driver is default for \XeTeX, so this is only a problem if you wish to explicitly use
% the |xdv2pdf| driver.
% \end{quote}
% Fonts selected by filename must include bold and italic variants explicitly.
% \begin{Verbatim}
% \fontspec
% [ BoldFont = texgyrepagella-bold.otf ,
% ItalicFont = texgyrepagella-italic.otf ,
% BoldItalicFont = texgyrepagella-bolditalic.otf ]
% {texgyrepagella-regular.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}
% \fontspec
% [ Extension = .otf ,
% BoldFont = texgyrepagella-bold ,
% ... ]
% {texgyrepagella-regular}
% \end{Verbatim}
% If desired, an abbreviation can be applied to the font names based on the
% mandatory `font name' argument:
% \begin{Verbatim}
% \fontspec
% [ Extension = .otf ,
% UprightFont = *-regular ,
% BoldFont = *-bold ,
% ... ]
% {texgyrepagella}
% \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}
% \fontspec
% [ Path = /Users/will/Fonts/ ,
% UprightFont = *-regular ,
% BoldFont = *-bold ,
% ... ]
% {texgyrepagella}
% \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 declaring the font exists in an `|ExternalLocation|':
% \begin{Verbatim}
% \fontspec
% [ ExternalLocation ,
% BoldFont = texgyrepagella-bold ,
% ... ]
% {texgyrepagella-regular}
% \end{Verbatim}
% To be honest, |Path| and |ExternalLocation| are actually the same feature
% with different names. The former can be given without an argument and the
% latter can be given with one; the different names are just for clarity.
%
%
% \section{Default font families}
% \label{sec:setxxfont}
%
% \cmdbox{
% \cmd{\setmainfont} \oarg{font features} \marg{font name} \\
% \cmd{\setsansfont} \oarg{font features} \marg{font name} \\
% \cmd{\setmonofont} \oarg{font features} \marg{font name}
% }
%
% These commands are used to select
% the default font families for the entire document. They take the
% same arguments as \cmd{\fontspec}. See \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.
%
% \begin{Lexample}{fontload}{Loading the default, sans serif, and monospaced fonts.}
% \setmainfont{TeX Gyre Bonum}
% \setsansfont[Scale=MatchLowercase]{Latin Modern Sans}
% \setmonofont[Scale=MatchLowercase]{Inconsolata}
%
% \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{New commands to select font families}
%
% \cmdbox{
% \CMD{\string\newfontfamily} \cs{\meta{font-switch}} \oarg{font features} \marg{font name} \\
% \CMD{\string\newfontface} \cs{\meta{font-switch}} \oarg{font features} \marg{font name}
% }
%
% \noindent 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.
%
% \DescribeMacro{\newfontfamily}
% For this reason, new commands can be created for loading a particular font
% family with the \cmd\newfontfamily\ command, 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}
%
% \DescribeMacro{\newfontface}
% 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
% [Contextuals={WordInitial,WordFinal}]
% {Hoefler Text Italic}
% \fancy where is all the vegemite
% % \emph, \textbf, etc., all don't work
% \end{Xexample}
%
% Comment for advanced users:
% The commands defined by \cs{newfontface} and \cs{newfontfamily} 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}
%
% \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}
% }
%
% 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[BoldFont={Helvetica Neue}]
% {Helvetica Neue UltraLight}
% 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{Input shorthands}
%
% For those cases that the base font name is repeated, you can
% replace it with an asterisk. (This has been shown previously in \vref{sec:by-file-name}.)
% For example,
% some space can be saved instead of writing `\texttt{Baskerville SemiBold}':
% \begin{Verbatim}
% \fontspec[BoldFont={* SemiBold}]{Baskerville}
% \end{Verbatim}
%
% As a matter of fact, this feature can also be used for the upright font too:
% \begin{Verbatim}
% \fontspec[UprightFont={* SemiBold},
% BoldFont={* Bold}]{Baskerville}
% \end{Verbatim}
%
% \subsubsection{Small caps and slanted font shapes}
%
% For the rare situations where a font family will have 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.
%
% Old-fashioned font families used to distribute their 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}
% \fontspec[
% SmallCapsFont={Minion MM Small Caps & Oldstyle Figures}
% ]{Minion MM Roman}
% Roman 123 \\ \textsc{Small caps 456}
% \end{Verbatim}
% In fact, you may specify the small caps font for each individual bold and
% italic shape as in
% \begin{Verbatim}
% \fontspec[
% UprightFeatures = { SmallCapsFont={ <sc> } } ,
% BoldFeatures = { SmallCapsFont={ <bf sc> } } ,
% ItalicFeatures = { SmallCapsFont={ <it sc> } } ,
% BoldItalicFeatures = { SmallCapsFont={ <bf it sc> } } ,
% ]{ <upright> }
% 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, but you may still occasionally find font
% families in which the small caps are in a separate font.
%
% 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
% \begin{Verbatim}
% \fontspec[
% SmallCapsFont={...},
% SmallCapsFeatures={Letters=SmallCaps},
% ]{...}
% \end{Verbatim}
%
% \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} \oarg{font features} \marg{font name} \\
% \cmd{\setmathsf} \oarg{font features} \marg{font name} \\
% \cmd{\setmathtt} \oarg{font features} \marg{font name} \\
% \cmd{\setboldmathrm} \oarg{font features} \marg{font name}
% }
%
% 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,xunicode}
% \setmainfont{Optima}
% \setmathrm{Optima}
% \setboldmathrm[BoldFont={Optima ExtraBlack}]{Optima Bold}
% \end{Verbatim}
%
%
% \subsection{Miscellaneous font selecting details}
%
% \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.
%
% \paragraph{Italic small caps}
% Note that this package redefines the \cs{itshape} and \cs{scshape}
% commands in order to allow them to select italic small caps in
% conjunction.
%
% \paragraph{Emphasis and nested emphasis}
% You may specify the behaviour of the \cs{emph} command by setting the
% \cs{emshape} command. \Eg, for bold emphasis:\par
% \indent|\renewcommand\emshape{\bfseries}|\par\noindent
% Nested emphasis is controlled by the \cs{eminnershape} command.
% For example, for |\emph{\emph{...}}| to produce small caps:\par
% \indent|\renewcommand\eminnershape{\scshape}|\par\noindent
%
%
%
%
%
% \section{Selecting font features}
% \label{sec:selectingfeature}
%
% The commands discussed so far such as \cs{fontspec} each take an optional argument for
% accessing 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 section discusses these options.
%
% \subsection{Default settings} \label{sec:defaults}
%
% \cmdbox{\cmd\defaultfontfeatures \marg{font features}}
%
% It is desirable to define
% options that are applied to every subsequent font selection command:
% a default feature set, so to speak. This may be defined with the
% \cmd{\defaultfontfeatures} command, shown in \exref{dff}.
% New calls of \cs{defaultfontfeatures} overwrite previous ones.
%
% \begin{Xexample}{dff}{A demonstration of the \cs{defaultfontfeatures} command.}
% \fontspec{TeX Gyre Adventor}
% Some default text 0123456789 \\
% \defaultfontfeatures{
% Numbers=OldStyle, Color=888888
% }
% \fontspec{TeX Gyre Adventor}
% Now grey, with old-style figures:
% 0123456789
% \end{Xexample}
%
% \cmdbox{\cmd\defaultfontfeatures \oarg{font name} \marg{font features}}
%
% \textbf{New in v2.3}.
% Default font features can be specified on a per-font and per-face basis
% by using the optional argument to \cs{defaultfontfeatures} as shown.\footnote{Internally, \meta{font name} has all spaces removed and is converted to lowercase.}
% \begin{Verbatim}
% \defaultfontfeatures[TeX Gyre Adventor]{Color=blue}
% \setmainfont{TeX Gyre Adventor}% will be blue
% \end{Verbatim}
%
% Additionally, when a font is first loaded, a configuration file is searched
% for with the name `\meta{fontname}\texttt{.fontspec}'.\footnote{Located in the current folder or within a standard \texttt{texmf} location.}
% The contents of this file can be used to specify default font features without
% having to have this information present within each document.
% \meta{fontname} is stripped of spaces and file extensions are omitted; for
% example, the line above for \TeX\ Gyre Adventor could be placed in a file
% called \texttt{TeXGyreAdventor.fontspec}, or for specifying options for
% \texttt{texgyreadventor-regular.otf} (when loading by filename), the configuration
% file would be \texttt{texgyreadventor-regular.fontspec}.
%
% This mechanism can be used to define custom names or aliases for your font collections.
% If you create a file \texttt{my-charis.fontspec} containing, say,
% \begin{Verbatim}
% \defaultfontfeatures[my-charis]
% {
% Extension = .ttf ,
% UprightFont = CharisSILR,
% BoldFont = CharisSILB,
% ItalicFont = CharisSILI,
% BoldItalicFont = CharisSILBI,
% % <any other desired options>
% }
% \end{Verbatim}
% you can load that family with \verb|\fontspec{my-charis}| and similar.
% The optional argument to \cs{defaultfontfeatures} must match the filename
% else the options won't take effect.
%
% Finally, note that options for 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}
% And such configuration lines can be stored within their own \texttt{.fontspec} files; in this way, \pkg{fontspec} is designed to handle `nested' configuration options as well.
%
% \subsection{Changing the currently selected features}
% \label{sec:addfontfeatures}
%
% \cmdbox{\cmd\addfontfeatures \marg{font features}}
%
% This command allows font features to
% be changed without knowing what features are currently selected or even what
% font is being used. A good example of this could be to add a hook to all
% tabular material to use monospaced numbers, as shown in \exref{aff}.
% Note however that the behaviour in this regard will be unreliable (subject to the font itself) if you attempt to \emph{change} an already selected feature.
% \Eg, this sort of thing can cause troubles:
% \begin{Verbatim}
% \addfontfeature{Numbers=OldStyle}...
% \addfontfeature{Numbers=Lining}...
% 123
% \end{Verbatim}
% With both features active, how will the font render `123'? Depends on the font.
% In the distant future this functionality will be re-written to avoid this issue (giving `\verb|Numbers=OldStyle|' the smarts to know to explicitly de-activate any previous instances of `\verb|Numbers=Lining|', and vice-versa, but as I hope you can imagine this requires a fair degree of elbow grease which I haven't had available for some time now.
%
% \begin{Lexample}{aff}{A demonstration of the \cs{addfontfeatures} command. Note the caveat listed in the text regarding such usage.}
% \fontspec[Numbers={Proportional,OldStyle}]
% {TeX Gyre Adventor}
% `In 1842, 999 people sailed 97 miles in
% 13 boats. In 1923, 111 people sailed 54
% miles in 56 boats.' \bigskip
%
% {\addfontfeatures{Numbers={Monospaced,Lining}}
% \begin{tabular}{@{} cccc @{}}
% Year & People & Miles & Boats \\
% \hline 1842 & 999 & 75 & 13 \\
% 1923 & 111 & 54 & 56
% \end{tabular}}
% \end{Lexample}
%
% \DescribeMacro{\addfontfeature}
% This command may also be executed under the alias \cmd{\addfontfeature}.
%
% \subsection{Priority of feature selection}
% Features defined with \cs{addfontfeatures} override features
% specified by \cs{fontspec}, which in turn override features
% specified by \cs{defaultfontfeatures}. If in doubt, whenever a
% new font is chosen for the first time, an entry is made in the
% transcript (\texttt{.log}) file displaying the font name and the
% features requested.
%
% \subsection{Different features for different font shapes}
% \label{sec:bfit-feat}
%
% \cmdbox{
% \feat{BoldFeatures}\marg{features} \\
% \feat{ItalicFeatures}\marg{features} \\
% \feat{BoldItalicFeatures}\marg{features} \\
% \feat{SlantedFeatures}\marg{features} \\
% \feat{BoldSlantedFeatures}\marg{features} \\
% \feat{SmallCapsFeatures}\marg{features}
% }
%
% It is entirely possible that separate fonts in a family will require
% separate options; \eg, 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 \cmd\fontspec\
% argument are applied to \emph{all} shapes of the family.
% Using \feat{Upright-}, \feat{SmallCaps-}, \feat{Bold-},
% \feat{Italic-}, and \feat{BoldItalicFeatures},
% separate font features may be defined to their respective shapes
% \emph{in addition} to, and with precedence over, the `global' font features.
% See \exref{itfeat}.
%
% \begin{Xexample}{itfeat}{Features for, say, just italics.}
% \fontspec{Hoefler Text} \itshape \scshape
% Attention All Martini Drinkers \\
% \addfontfeature{ItalicFeatures={Alternate = 1}}
% Attention All Martini Drinkers \\
% \end{Xexample}
%
% Combined with the options for selecting arbitrary \emph{fonts} for
% the different shapes, these separate feature options allow the
% selection of arbitrary weights in the Skia typeface, as shown in \exref{bffeat}.
%
% \begin{Xexample}{bffeat}{Multiple Master--like features in AAT fonts.}
% \fontspec[BoldFont={Skia},
% BoldFeatures={Weight=2}]{Skia}
% Skia \\ \bfseries Skia `Bold'
% \end{Xexample}
%
% Note that because most fonts include their small caps glyphs
% within the main font, features specified with \feat{SmallCapsFeatures} are applied \emph{in addition} to
% any other shape-specific features as defined above, and hence \feat{SmallCapsFeatures}
% can be nested within \feat{ItalicFeatures} and friends. Every combination
% of upright, italic, bold and small caps can thus be assigned individual
% features, as shown in the somewhat ludicrous \exref{scfeat}.
%
% \begin{Xexample}{scfeat}{An example of setting the \feat{SmallCapsFeatures}
% separately for each font shape.}
% \fontspec[
% UprightFeatures={Color = 220022,
% SmallCapsFeatures = {Color=115511}},
% ItalicFeatures={Color = 2244FF,
% SmallCapsFeatures = {Color=112299}},
% BoldFeatures={Color = FF4422,
% SmallCapsFeatures = {Color=992211}},
% BoldItalicFeatures={Color = 888844,
% SmallCapsFeatures = {Color=444422}},
% ]{TeX Gyre Termes}
% Upright {\scshape Small Caps}\\
% \itshape Italic {\scshape Italic Small Caps}\\
% \upshape\bfseries Bold {\scshape Bold Small Caps}\\
% \itshape Bold Italic {\scshape Bold Italic Small Caps}
% \end{Xexample}
%
% \subsection{Different features for different font sizes}
% \label{sec:sizefeature}
%
% \cmdbox{
% \ttfamily SizeFeatures = \char`\{\\
% \null\quad...\\
% \null\quad\char`\{~Size =
% \rmfamily\meta{size range}\ttfamily
% ,
% \rmfamily \meta{font features}\ttfamily
% ~\char`\} , \\
% \null\quad\char`\{~Size =
% \rmfamily\meta{size range}\ttfamily
% , Font =
% \rmfamily\meta{font name}\texttt, \meta{font features}\ttfamily
% ~\char`\} , \\
% \null\quad... \\
% \char`\}}
%
% The \feat{SizeFeature} feature is a little more complicated
% than the previous features discussed. It allows different fonts
% and different font features to be selected for a given font
% family as the point size varies.
%
% It takes a comma separated list of braced, comma separated lists of features for each size range.
% Each sub-list must contain the \opt{Size} option
% to declare the size range, and optionally \opt{Font} to change the
% font based on size. Other (regular) fontspec features that are added
% are used on top of the font features that would be used anyway.
% A demonstration to clarify these details is shown in \exref{sizefeat}.
% A less trivial example is shown in the context of optical font sizes
% in \vref{sec:opticalsize}.
%
% \begin{Xexample}{sizefeat}{An example of specifying different font features for different sizes of font with \feat{SizeFeatures}.}
% \fontspec[ SizeFeatures={
% {Size={-8}, Font=TeX Gyre Bonum Italic, Color=AA0000},
% {Size={8-14}, Color=00AA00},
% {Size={14-}, Color=0000AA}} ]{TeX Gyre Chorus}
%
% {\scriptsize Small\par} Normal size\par {\Large Large\par}
% \end{Xexample}
%
% To be precise, the \opt{Size} sub-feature accepts arguments in the form shown in \vref{tab:sizing}.
% Braces around the size range are optional. For an exact font size (|Size=X|)
% font sizes chosen near that size will `snap'. For example, for size definitions
% at exactly 11pt and 14pt, if a 12pt font is requested \emph{actually} the
% 11pt font will be selected. This is a remnant of the past when fonts were designed
% in metal (at obviously rigid sizes) and later when bitmap fonts were similarly
% designed for fixed sizes.
%
% If additional features are only required for a single size, the other sizes
% must still be specified. As in:
% \begin{Verbatim}
% SizeFeatures={
% {Size=-10,Numbers=Uppercase},
% {Size=10-}}
% \end{Verbatim}
% Otherwise, the font sizes greater than 10 won't be defined!
%
% \begin{table}
% \caption{Syntax for specifying the size to apply custom font features.}\label{tab:sizing}
% \centering
% \begin{tabular}{@{}ll@{}}
% \toprule
% Input & Font size, $s$ \\
% \midrule
% |Size = X-| & $s \geq \texttt{X}$ \\
% |Size = -Y| & $s < \texttt{Y}$ \\
% |Size = X-Y| & $\texttt{X} \leq s < \texttt{Y}$ \\
% |Size = X| & $s = \texttt{X}$ \\
% \bottomrule
% \end{tabular}
% \end{table}
%
%
% \section{Font independent options} \label{sec:font-ind-features}
%
% Features introduced in this section may be used with any font.
%
% \subsection{Colour}
%
% \feat{Color} (or \feat{Colour}), also shown in \vref{sec:defaults}
% and elsewhere, uses font specifications to set the colour of
% the text. 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.)
% \begin{Xexample}{color}{Selecting colour with transparency.}
% \fontsize{48}{48}
% \fontspec{TeX Gyre Bonum Bold}
% {\addfontfeature{Color=FF000099}W}\kern-1ex
% {\addfontfeature{Color=0000FF99}S}\kern-0.8ex
% {\addfontfeature{Color=DDBB2299}P}\kern-0.8ex
% {\addfontfeature{Color=00BB3399}R}
% \end{Xexample}
% Transparency is supported by \LuaLaTeX\ and by \XeLaTeX\ with the \texttt{xdv2pdf}
% driver (\MacOSX\ only); \XeLaTeX\ with the \texttt{xdvipdfmx} driver
% does not support this feature.
%
% If you load the \pkg{xcolor} package, you may use any named colour instead
% of writing the colours in hexadecimal.
% \begin{Verbatim}
% \usepackage{xcolor}
% ...
% \fontspec[Color=red]{Verdana} ...
% \definecolor{Foo}{rgb}{0.3,0.4,0.5}
% \fontspec[Color=Foo]{Verdana} ...
% \end{Verbatim}
% The \pkg{color} package is \emph{not} supported; use \pkg{xcolor} instead.
%
% You may specify the transparency with a named colour using the \feat{Opacity}
% feature which takes an decimal from zero to one corresponding to
% transparent to opaque respectively:
% \begin{Verbatim}
% \fontspec[Color=red,Opacity=0.7]{Verdana} ...
% \end{Verbatim}
% It is still possible to specify a colour in six-char hexadecimal form
% while defining opacity in this way, if you like.
%
% \subsection{Scale}
%
% \cmdbox{
% \feat{Scale} = \meta{number} \\
% \feat{Scale} = \opt{MatchLowercase} \\
% \feat{Scale} = \opt{MatchUppercase}
% }
%
% In its explicit form, \feat{Scale} takes a single
% numeric argument for linearly scaling the font, as demonstrated
% in \vref{sec:setxxfont}.
% It is now possible to
% measure the correct dimensions of the fonts loaded and
% calculate values to scale them automatically.
%
% As well as a numerical argument, the \feat{Scale} feature
% also accepts options \opt{MatchLowercase}
% and \opt{MatchUppercase}, which will scale the font being selected to match
% the current default roman font to either the height of the lowercase or
% uppercase letters, respectively; these features are shown in \exref{scale}.
%
% \begin{Xexample}{scale}{Automatically calculated scale values.}
% \setmainfont{Georgia}
% \newfontfamily\lc[Scale=MatchLowercase]{Verdana}
% The perfect match {\lc is hard to find.}\\
% \newfontfamily\uc[Scale=MatchUppercase]{Arial}
% L O G O \uc F O N T
% \end{Xexample}
%
% The amount of scaling used in each instance is reported in the \texttt{.log} file.
% Since there is some subjectivity about the exact scaling to be used, these values
% should be used to fine-tune the results.
%
%
%
%
% \subsection{Interword space}
%
% While the space between words can be varied on an individual
% basis with the \TeX\ primitive \cmd\spaceskip\ command, it is
% more convenient to specify this information when the font is
% first defined.
%
% The space in between words in a paragraph will be chosen automatically,
% and generally will not need to be adjusted. For those
% times when the precise details are important, the \feat{WordSpace}
% feature is
% provided, which takes either a single scaling factor to scale the
% default value, or a triplet of comma-separated