fontspec-doc-api.tex

%%^^A%%  fontspec-doc-api.tex -- part of FONTSPEC <latex3.github.io/fontspec>

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

\part{Customisation and programming interface}

This chapter describes the current interfaces and 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.
\begin{Verbatim}
  \newAATfeature{Alternate}{HoeflerSwash}{17}{1}
  \fontspec{Hoefler Text Italic}[Alternate=HoeflerSwash]
   This is XeTeX by Jonathan Kew.
\end{Verbatim}


\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.
More importantly, this can be used to enable features for which \pkg{fontspec}
does not yet have a user interface to.

\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}

Note that there is no error-checking when using |RawFeature|. Where a \pkg{fontspec}
interface exists to a feature it is generally better to use it. If the font lacks the feature
or if it would clash with another feature, \pkg{fontspec} will attemmpt to warn and/or resolve the issues.


\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{ItalicFont}{IF}
  \aliasfontfeature{ItalicFeatures}{IFF}
  \setmainfont{ EBGaramond-Regular.otf }[
    IF  = EBGaramond-Italic.otf ,
    IFF = {Style=Swash} ,
  ]
   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 variable \cs{g_fontspec_encoding_tl} instead.

\subsection{Functions for loading new fonts and families}

\begin{function}{\fontspec_gset_family:Nnn,\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{function}

\begin{function}{\fontspec_gset_fontface:NNnn,\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{function}


\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{function}{\fontspec_font_if_exist:nTF}
\begin{syntax}
|\fontspec_font_if_exist:nTF| \Arg{font name/file} \Arg{true code} \Arg{false code}
\end{syntax}
Test whether the `font name' (|#1|) exists or is loadable.
\meta{true code} or \meta{false code} is executed accordingly.
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}
The synonym \cs{IfFontExistsTF} is provided for `document authors'.
\end{function}


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


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


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


\subsubsection{Availability of features}

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


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


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


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


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


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


\subsubsection{Currently selected features}

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


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


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

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