%%^^A%% fontspec-doc-api.tex -- part of 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{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 % ------------------------------------------------ % 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): . % ------------------------------------------------ % ©/