-
Notifications
You must be signed in to change notification settings - Fork 32
/
fontspec-doc-intro.tex
206 lines (147 loc) · 9.12 KB
/
fontspec-doc-intro.tex
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
%%^^A%% fontspec-doc-intro.tex -- part of FONTSPEC <latex3.github.io/fontspec>
\documentclass[a4paper]{l3doc}
\usepackage{fontspec-doc-style}
\showexamplesfalse
\begin{document}
\part{Getting started}
\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.
\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 documents \path{fontspec-example.tex} for a complete minimal example
to get started quickly.
\subsection{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\"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 was 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.
Package options are setup with the in-built \LaTeX{} keyval options handler. This means
that the package can be loaded more than once with different options without triggering
an option clash error.
\DescribeOption{config}
\DescribeOption{no-config}
The \texttt{config} and \texttt{no-config} option must be used in
the first loading and are ignored later.
\subsection{Font encodings}
The package switches the \textsc{nfss} font encoding to \texttt{TU}.
\texttt{TU} is a new Unicode font encoding, intended for both \XeTeX\ and \LuaTeX\ engines, and automatically contains support for symbols covered by \LaTeX's traditional \texttt{T1} and \texttt{TS1} font encodings (for example, |\%|, |\textbullet|, |\"u|, and so on).
Some additional features are provided by \pkg{fontspec} to customise some encoding details; see Part~\vref{part:enc} for further details.
\DescribeOption{euenc}
\DescribeOption{tuenc}
Pre-2017 behaviour is now obsolete. The \texttt{euenc} and \texttt{tuenc} package options are
ignored. Package authors and users who have referred explicitly to the encoding names \texttt{EU1} or \texttt{EU2} should update their code or documents.
(See internal variable names described in \vref{sec:api} for how to do this properly.)
\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 shouldn't be, apply the \DescribeOption{no-math} |no-math| package option to manually suppress its behaviour here.
\subsection{Configuration}
\label{sec:config}
If you wish to customise any part of the
\pkg{fontspec} interface, 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.
A |fontspec.cfg| file is distributed with \pkg{fontspec} with a small number of defaults set up within it.
To customise \pkg{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; \eg\ in Mac\TeX: \path{~/Library/texmf/tex/latex/}.
\DescribeOption{no-config}
The package option |no-config| will suppress the loading of the |fontspec.cfg| file under all circumstances. Both options must be used the first time \pkg{fontspec} is loaded and are ignored in later calls.
\subsection{Warnings}
\label{sec:quiet-warnings}
This package can give some warnings that can be harmless if you know what
you're doing. Use the \DescribeOption{quiet} |quiet| package option to write these warnings to the
transcript (\texttt{.log}) file instead.
\DescribeOption{silent}
Use the |silent| package option to completely suppress these warnings if you
don't even want the |.log| file cluttered up.
Both options can also be used with \cs{Setkeys} in the document. Use the \DescribeOption{verbose} |verbose| option to get activate the warnings again.
\section{Interaction with \LaTeXe\ and other packages}
This section documents some areas of adjustment that \pkg{fontspec} makes
to improve default behaviour with \LaTeXe\ and third-party packages.
\subsection{Commands for old-style and lining numbers}
\DescribeMacro{\oldstylenums}
\DescribeMacro{\liningnums}
\LaTeX's definition of \cs{oldstylenums} relies on strange font encodings.
We provide a \pkg{fontspec}-compatible alternative and while we're at it
also throw in the reverse option as well. Use \cs{oldstylenums}\marg{text}
to explicitly use old-style (or lowercase) numbers in \meta{text}, and
the reverse for \cs{liningnums}\marg{text}.
\subsection{Italic small caps}
Support now provided by \LaTeXe\ in 2020.
\subsection{Emphasis and nested emphasis}
Support now provided by \LaTeXe\ in 2020.
\subsection{Strong emphasis}
\DescribeMacro{\strong}
\DescribeMacro{\strongenv}
The \cs{strong} macro is used analogously to \cs{emph} but produces variations in weight.
If you need it in environment form, use |\begin{strongenv}...\end{strongenv}|.
As with emphasis, this font-switching command is intended to move through a range
of font weights. For example, if the fonts are set up correctly it allows usage such as
|\strong{...\strong{...}}| in which each nested \cs{strong} macro increases the
weight of the font.
\DescribeMacro{\strongfontdeclare}
Currently this feature set is somewhat experimental and there is no syntactic sugar
to easily define a range of font weights using \pkg{fontspec} commands.
Use, say, the following to define first bold and then black (|k|) font faces for \cs{strong}:
\begin{Verbatim}
\strongfontdeclare{\bfseries,\fontseries{k}\selectfont}
\end{Verbatim}
\DescribeMacro{\strongreset}
If too many levels of \cs{strong} are reached, \cs{strongreset} is inserted.
By default this is a no-op and the font will simply remain the same.
Use \cs{renewcommand}\cs{strongreset}|{\mdseries}| to start again from the beginning if desired.
An example for setting up a font family for use with \cs{strong} is discussed in \vref{sec:strong-example}.
\end{document}
% /©
% ------------------------------------------------
% The FONTSPEC package <latex3.github.io/fontspec>
% ------------------------------------------------
% Copyright 2022-2024 The LaTeX project, LPPL "maintainer"
% Copyright 2004-2022 Will Robertson
% 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/>.
% ------------------------------------------------
% ©/