summaryrefslogtreecommitdiff
path: root/macros/latex/contrib/fontspec/fontspec-doc-api.tex
blob: ed85ad9fa5cf86fa6f4285259e2aa78e6f600a2c (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
%%^^A%%  fontspec-doc-api.tex -- part of FONTSPEC <wspr.io/fontspec>

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

\part{Customisation and programming interface}

This is the beginning of some work to provide some hooks that use
\pkg{fontspec} for various macro programming purposes.


\section{Defining new features} \label{sec:newfeatures}
This package cannot hope to contain every possible font
feature. Three commands are provided for selecting font features
that are not provided for out of the box. If you are using
them a lot, chances are I've left something out, so please let me
know.

\DescribeMacro{\newAATfeature}
New \AAT\ features may be created with this command:\par
{\centering\cmd\newAATfeature\marg{feature}\marg{option}\marg{feature code}\marg{selector code}\par}\noindent
Use the \XeTeX\ file \path{AAT-info.tex} to obtain the code numbers.
See \exref{newAATfeat}.

\begin{Xexample}{newAATfeat}{Assigning new \AAT\ features.}
  \newAATfeature{Alternate}{HoeflerSwash}{17}{1}
  \fontspec{Hoefler Text Italic}[Alternate=HoeflerSwash]
   This is XeTeX by Jonathan Kew.
\end{Xexample}


\DescribeMacro{\newopentypefeature}
New OpenType features may be created with this command:\par
{\centering\cmd\newopentypefeature\marg{feature}\marg{option}\marg{feature tag}\par}
The synonym \cs{newICUfeature} is deprecated.

Here's what it would look like in practise:
\begin{Verbatim}
\newopentypefeature{Style}{NoLocalForms}{-locl}
\end{Verbatim}

\DescribeMacro{\newfontfeature}
In case the above commands do not accommodate the desired font feature
(perhaps a new \XeTeX\ feature that \pkg{fontspec} hasn't been updated
to support), a command is provided to pass arbitrary input into the
font selection string:\par
{\centering\cmd{\newfontfeature}\marg{name}\marg{input string}\par}

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:

\begin{Verbatim}
  \newfontfeature{AvoidD}  {Special= Avoid d-collisions}
  \newfontfeature{NoAvoidD}{Special=!Avoid d-collisions}
  \fontspec{Zapfino}[AvoidD,Variant=1]
   sockdolager rubdown               \\
  \fontspec{Zapfino}[NoAvoidD,Variant=1]
   sockdolager rubdown
\end{Verbatim}

The advantage to using the \cmd\newAATfeature\ and \cmd\newopentypefeature\
commands instead of \cs{newfontfeature} is that they check if the selected font actually contains the desired font
feature at load time. By contrast, \cmd\newfontfeature\ will not give a warning
for improper input.


\section{Defining new scripts and languages}
\label{sec:newscriptlang}

\DescribeMacro{\newfontscript}
\DescribeMacro{\newfontlanguage}
While the scripts and languages listed in \ref{tab:ot-scpt} and \ref{tab:ot-lang}
are intended to be comprehensive, there may be some missing; alternatively,
you might wish to use different names to access scripts/languages that are
already listed.
Adding scripts and languages can be performed with the \cmd\newfontscript\
and \cmd\newfontlanguage\ commands. For example,
\begin{Verbatim}
  \newfontscript{Arabic}{arab}
  \newfontlanguage{Zulu}{ZUL}
\end{Verbatim}
The first argument is the \pkg{fontspec} name, the second the OpenType
tag. The advantage to using these commands rather than \cmd\newfontfeature\
(see \vref{sec:newfeatures}) is the error-checking that is performed when
the script or language is requested.

Both commands accept a comma-separated list of OpenType tags in order of preference.
This permits, for example, supporting both new and old versions of a language tag with
a common user interface:
\begin{Verbatim}
  \newfontlanguage{Turkish}{TRK,TUR}
\end{Verbatim}
Here, a font that is requested with \verb|Script=Turkish| will first be checked for the
OpenType language tag \verb|TRK|, which will be selected if available. If not available,
the \verb|TUR| tag will be queried and used if possible as a fallback.


\section{Going behind \pkg{fontspec}'s back}
Expert users may wish not to use \pkg{fontspec}'s feature handling at all,
while still taking advantage of its \LaTeX\ font selection conveniences. The
\feat{RawFeature} font feature allows font feature selection using a literal feature selection string if you happen to have the OpenType feature tag memorised.

\begin{Xexample}{raw}{Using raw font features directly.}
  \fontspec{texgyrepagella-regular.otf}[RawFeature=+smcp]
  Pagella small caps
\end{Xexample}

Multiple features can either be included in a single declaration:\par
{\centering|[RawFeature=+smcp;+onum]|\par}
\noindent or with multiple declarations:\par
{\centering|[RawFeature=+smcp, RawFeature=+onum]|\par}


\section{Renaming existing features \& options}
\label{sec:aliasfontfeature}

\DescribeMacro{\aliasfontfeature}
If you don't like the name of a particular font feature,
it may be aliased to another with the
\cs{aliasfontfeature}\marg{existing name}\marg{new name} command,
such as shown in \exref{alias}.

\begin{Xexample}{alias}{Renaming font features.}
  \aliasfontfeature{ItalicFeatures}{IF}
  \fontspec{Hoefler Text}[IF = {Alternate=1}]
  Roman Letters \itshape And Swash
\end{Xexample}

Spaces in feature (and option names, see below) \emph{are} allowed. (You may have
noticed this already in the lists of OpenType scripts and languages).

\DescribeMacro{\aliasfontfeatureoption}
If you wish to change the name of a font feature option,
it can be aliased to another with the command
\cs{aliasfontfeatureoption}\marg{font feature}\marg{existing name}\marg{new name}, such as shown in \exref{aliasopt}.

\begin{Lexample}{aliasopt}{Renaming font feature options.}
  \aliasfontfeature{VerticalPosition}{Vert Pos}
  \aliasfontfeatureoption{VerticalPosition}{ScientificInferior}{Sci Inf}
  \fontspec{LinLibertine_R.otf}[Vert Pos=Sci Inf]
   Scientific Inferior: 12345
\end{Lexample}

This example demonstrates an important point: when aliasing the feature
options, the \emph{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, \opt{Proportional} can be aliased to \opt{Prop} in the
\feat{Letters} feature, but \opt{550099BB} cannot be substituted for \opt{Purple}
in a \feat{Color} specification. For this type of thing, the \cmd\newfontfeature\
command should be used to declare a new, \eg, \feat{PurpleColor} feature:
\begin{Verbatim}
  \newfontfeature{PurpleColor}{color=550099BB}
\end{Verbatim}
Except that this example was written before support for named colours was
implemented. But you get the idea.




\section{Programming interface}
\label{sec:api}


\subsection{Variables}

\DescribeMacro{\l_fontspec_family_tl}
\DescribeMacro{\l_fontspec_font}
In some cases, it is useful to know what the \LaTeX\ font family
of a specific \pkg{fontspec} font is. After a \cmd\fontspec-like
command, this is stored inside the \cmd\l_fontspec_family_tl\ macro.
Otherwise, \LaTeX's own \cmd\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 \cmd{\l_fontspec_font}.

\DescribeMacro{\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 \texttt{EU1}/\texttt{EU2} to \texttt{TU}, it is best to use the variables \cs{g_fontspec_encoding_tl} or \cs{UTFencname} instead.

\subsection{Functions for loading new fonts and families}

\begin{macro}{\fontspec_gset_family:Nnn}
\begin{macro}{\fontspec_set_family:Nnn}
\darg{\LaTeX\ family}
\darg{fontspec features}
\darg{font name}
Defines a new \NFSS\ family from given \meta{features} and \meta{font},
and stores the family name in the variable \meta{family}.
This font family can then be selected with standard \LaTeX\ commands
\cs{fontfamily}\marg{family}\cs{selectfont}.
See the standard \pkg{fontspec} user commands for applications of this
function.
\end{macro}
\end{macro}

\begin{macro}{\fontspec_gset_fontface:NNnn}
\begin{macro}{\fontspec_set_fontface:NNnn}
\darg{primitive font}
\darg{\LaTeX\ family}
\darg{fontspec features}
\darg{font name}
Variant of the above in which the primitive \TeX\ font command is stored in
the variable \meta{primitive font}.
If a family is loaded (with bold and italic shapes) the primitive font
command will only select the regular face.
This feature is designed for \LaTeX\ programmers who need to
perform subsequent font-related tests on the \meta{primitive font}.
\end{macro}
\end{macro}


\subsection{Conditionals}

The following functions in \pkg{expl3} syntax may be used
for writing code that interfaces with \pkg{fontspec}-loaded fonts.
The following conditionals are all provided in |TF|, |T|, and |F| forms.

\subsubsection{Querying font families}

\begin{macro}{\fontspec_font_if_exist:nTF}
Test whether the `font name' (|#1|) exists or is loadable.
The syntax of |#1| is a restricted/simplified version of \pkg{fontspec}'s usual font loading syntax; 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}
  \fontspec_font_if_exist:nTF {cmr10}{T}{F}
  \fontspec_font_if_exist:nTF {Times~ New~ Roman}{T}{F}
  \fontspec_font_if_exist:nTF {texgyrepagella-regular.otf}{T}{F}
  \fontspec_font_if_exist:nTF {/Users/will/Library/Fonts/CODE2000.TTF}{T}{F}
\end{Verbatim}
\end{macro}
The synonym \cs{IfFontExistsTF} is provided for `document authors'.


\begin{macro}{\fontspec_if_fontspec_font:TF}
Test whether the currently selected font has been loaded by fontspec.
\end{macro}


\begin{macro}{\fontspec_if_opentype:TF}
Test whether the currently selected font is an OpenType font.
Always true for \LuaTeX{} fonts.
\end{macro}


\begin{macro}{\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 \pkg{fontspec} will
merge shapes together (for italic small caps, etc.).
\end{macro}


\subsubsection{Availability of features}

\begin{macro}{\fontspec_if_aat_feature:nnTF}
Test whether the currently selected font contains the \AAT\
feature (|#1|,|#2|).
\end{macro}


\begin{macro}{\fontspec_if_feature:nTF}
Test whether the currently selected font contains the raw OpenType
feature |#1|. E.g.: |\fontspec_if_feature:nTF {pnum} {True} {False}|.
Returns false if the font is not loaded by fontspec or is not an OpenType
font.
\end{macro}


\begin{macro}{\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} {ROM} {pnum} {True} {False}|.
Returns false if the font is not loaded by fontspec or is not an OpenType
font.
\end{macro}


\begin{macro}{\fontspec_if_script:nTF}
Test whether the currently selected font contains the raw OpenType
script |#1|. E.g.: |\fontspec_if_script:nTF {latn} {True} {False}|.
Returns false if the font is not loaded by fontspec or is not an OpenType
font.
\end{macro}


\begin{macro}{\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{macro}


\begin{macro}{\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{macro}


\subsubsection{Currently selected features}

\begin{macro}{\fontspec_if_current_feature:nTF}
Test whether the currently loaded font is using the specified raw
OpenType feature tag |#1|.
The tag string |#1| should be prefixed with |+| to query an active feature, and with a |-| (hyphen) to query a disabled feature.
\end{macro}


\begin{macro}{\fontspec_if_current_script:nTF}
Test whether the currently loaded font is using the specified raw
OpenType script tag |#1|.
\end{macro}


\begin{macro}{\fontspec_if_current_language:nTF}
Test whether the currently loaded font is using the specified raw
OpenType language tag |#1|.
\end{macro}

\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/>.
% ------------------------------------------------
% ©/