diff --git a/fontspec-code-api.dtx b/fontspec-code-api.dtx index 359936d..be63bcc 100644 --- a/fontspec-code-api.dtx +++ b/fontspec-code-api.dtx @@ -1,14 +1,12 @@ %%^^A%% fontspec-code-api.dtx -- part of FONTSPEC -% \section{Programmer's interface} -% % \iffalse % \begin{macrocode} %<*fontspec> % \end{macrocode} % \fi % -% +% \section{Programmer's interface} % % These functions are not used directly by fontspec when defining fonts; % they are designed to be used by other packages who wish to do font-related @@ -23,8 +21,143 @@ % currently selected as a fontspec font. (I.e., via \verb|\fontspec| or % from a \verb|\newfontfamily| macro or from \verb|\setmainfont| and so on.) % -% \begin{macro}{\fontspec_if_fontspec_font:TF} -% Test whether the currently selected font has been loaded by fontspec. +% \section{Overview} +% +% \subsection{Commands} +% +% \begin{function}{\fontspec_gset_family:Nnn,\fontspec_set_family:Nnn} +% \begin{syntax} +% \verb|\fontspec_set_family:Nnn| \meta{family} \Arg{features} \Arg{font name} +% \end{syntax} +% Defines a new NFSS font family from given \meta{features} and \meta{font}, +% and stores the name in the token list variable \meta{family}. +% See the standard \pkg{fontspec} user commands for applications of this +% function. +% \end{function} +% +% \begin{function}{\fontspec_gset_fontface:NNnn,\fontspec_set_fontface:NNnn} +% \begin{syntax} +% \verb|\fontspec_set_fontface:NNnn| \meta{face} \meta{family} \Arg{features} \Arg{font name} +% \end{syntax} +% As for |\fontspec_set_family:Nnn| but with a single font face only. +% (E.g., no bold, italic shapes, etc.) +% The control sequence \meta{face} is a primitive \TeX\ font command. +% \end{function} +% +% \subsection{Conditionals} +% +% \begin{function}[TF]{\fontspec_font_if_exist:n} +% \begin{syntax} +% \verb|\fontspec_font_if_exist:nTF| \Arg{font name} Arg{true code} \Arg{false code} +% \end{syntax} +% Does this font exist? The font name can refer to the `logical' name or to a filename with known font extension. +% \end{function} +% +% \begin{function}[TF]{\fontspec_if_fontspec_font:} +% \begin{syntax} +% \verb|\fontspec_if_fontspec_font:TF| \Arg{true code} \Arg{false code} +% \end{syntax} +% \end{function} +% +% \begin{function}[TF]{\fontspec_if_aat_feature:nn} +% \begin{syntax} +% \verb|\fontspec_if_aat_feature:nnTF| \Arg{true code} \Arg{false code} +% \end{syntax} +% \end{function} +% +% \begin{function}[TF]{\fontspec_if_opentype:} +% \begin{syntax} +% \verb|\fontspec_if_opentype:TF| \Arg{true code} \Arg{false code} +% \end{syntax} +% \end{function} +% +% \begin{function}[TF]{\fontspec_if_feature:n} +% \begin{syntax} +% \verb|\fontspec_if_feature:nTF| \Arg{feat tag} \Arg{true code} \Arg{false code} +% \end{syntax} +% Check if the raw OpenType \meta{feature tag} is available in the current font with +% script and language settings as set up when the font was loaded. +% \end{function} +% +% \begin{function}[TF]{\fontspec_if_feature:nnn} +% \begin{syntax} +% \verb|\fontspec_if_feature:nnnTF| \Arg{script tag} \Arg{lang tag} \Arg{feat tag} \Arg{true code} \Arg{false code}\\ +% |\fontspec_if_feature:nTF {latn} {ROM} {pnum} {True} {False}| +% \end{syntax} +% Test whether the currently selected font with raw OpenType \meta{script tag} and +% raw OpenType \meta{language tag} contains the raw OpenType \meta{feature tag}. +% Returns false if the font is not loaded by fontspec or is not an OpenType +% font. +% \end{function} +% +% \begin{function}[TF]{\fontspec_if_script:n} +% \begin{syntax} +% \verb|\fontspec_if_script:nTF| \Arg{script tag} \Arg{true code} \Arg{false code}\\ +% |\fontspec_if_script:nTF {latn} {True} {False}| +% \end{syntax} +% Test whether the currently selected font contains the raw OpenType +% \meta{script tag}. +% +% Returns false if the font is not loaded by fontspec or is not an OpenType +% font. +% \end{function} +% +% \begin{function}[TF]{\fontspec_if_language:n} +% \begin{syntax} +% \verb|\fontspec_if_language:nTF| \Arg{lang tag} \Arg{true code} \Arg{false code}\\ +% |\fontspec_if_language:nTF {ROM} {True} {False}| +% \end{syntax} +% Check if the raw OpenType \meta{language tag} is available in the current font with +% script settings as set up when the font was loaded. +% \end{function} +% +% \begin{function}[TF]{\fontspec_if_language:nn} +% \begin{syntax} +% \verb|\fontspec_if_language:nnTF| \Arg{script tag} \Arg{lang tag} \Arg{true code} \Arg{false code}\\ +% |\fontspec_if_language:nnTF {cyrl} {SRB} {True} {False}| +% \end{syntax} +% Test whether the currently selected font contains the raw OpenType \meta{language +% tag} in \meta{script tag}. +% +% Returns false if the font is not loaded by fontspec or is not an OpenType font. +% \end{function} +% +% \begin{function}[TF]{\fontspec_if_current_script:n} +% Test whether the currently loaded font has been loaded with the specified raw +% OpenType \meta{script tag}. +% \begin{syntax} +% \verb|\fontspec_if_current_script:nTF| \Arg{script tag} \Arg{true code} \Arg{false code} +% \end{syntax} +% \end{function} +% +% \begin{function}[TF]{\fontspec_if_current_language:n} +% Test whether the currently loaded font has been loaded with the specified raw +% OpenType \meta{language tag}. +% \begin{syntax} +% \verb|\fontspec_if_current_language:nTF| \Arg{lang tag} \Arg{true code} \Arg{false code} +% \end{syntax} +% \end{function} +% +% \begin{function}[TF]{\fontspec_if_current_feature:n} +% \begin{syntax} +% \verb|\fontspec_if_current_feature:nTF| \Arg{feat tag} \Arg{true code} \Arg{false code} +% \end{syntax} +% Test whether the currently loaded font is using the specified raw +% OpenType \meta{feature tag}. +% \end{function} +% +% \begin{function}[TF]{\fontspec_if_small_caps:} +% Test whether the current font has small caps available. +% \begin{syntax} +% \verb|\fontspec_if_small_caps:TF| \Arg{true code} \Arg{false code} +% \end{syntax} +% \end{function} +% +% +% +% \section{Implementation} +% +% \begin{macro}[TF]{\fontspec_if_fontspec_font:} % \begin{macrocode} \prg_new_conditional:Nnn \fontspec_if_fontspec_font: {TF,T,F} { @@ -34,7 +167,7 @@ % \end{macro} % % -% \begin{macro}{\fontspec_if_aat_feature:nnTF} +% \begin{macro}[TF]{\fontspec_if_aat_feature:nn} % Conditional to test if the currently selected font contains the \AAT\ % feature (|#1|,|#2|). % \begin{macrocode} @@ -60,7 +193,7 @@ % \end{macro} % % -% \begin{macro}{\fontspec_if_opentype:TF} +% \begin{macro}[TF]{\fontspec_if_opentype:} % Test whether the currently selected font is an OpenType font. % Always true for LuaTeX fonts. % \begin{macrocode} @@ -78,7 +211,7 @@ % \end{macrocode} % \end{macro} % -% \begin{macro}{\fontspec_if_feature:nTF} +% \begin{macro}[TF]{\fontspec_if_feature:n} % 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 @@ -113,12 +246,10 @@ % \end{macrocode} % \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:nTF {latn} {ROM} {pnum} {True} {False}| -% Returns false if the font is not loaded by fontspec or is not an OpenType -% font. +% \begin{macro}[TF]{\fontspec_if_feature:nnn} +% \darg{script tag} +% \darg{language tag} +% \darg{feature tag} % \begin{macrocode} \prg_new_conditional:Nnn \fontspec_if_feature:nnn {TF,T,F} { @@ -136,11 +267,8 @@ % \end{macrocode} % \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. +% \begin{macro}[TF]{\fontspec_if_script:n} +% \darg{script tag} % \begin{macrocode} \prg_new_conditional:Nnn \fontspec_if_script:n {TF,T,F} { @@ -158,11 +286,8 @@ % \end{macrocode} % \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. +% \begin{macro}[TF]{\fontspec_if_language:n} +% \darg{lang tag} % \begin{macrocode} \prg_new_conditional:Nnn \fontspec_if_language:n {TF,T,F} { @@ -184,11 +309,9 @@ % \end{macrocode} % \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. +% \begin{macro}[TF]{\fontspec_if_language:nn} +% \darg{script tag} +% \darg{lang tag} % \begin{macrocode} \prg_new_conditional:Nnn \fontspec_if_language:nn {TF,T,F} { @@ -207,9 +330,8 @@ % \end{macro} % % -% \begin{macro}{\fontspec_if_current_script:nTF} -% Test whether the currently loaded font is using the specified raw -% OpenType script tag |#1|. +% \begin{macro}[TF]{\fontspec_if_current_script:n} +% \darg{script tag} % \begin{macrocode} \prg_new_conditional:Nnn \fontspec_if_current_script:n {TF,T,F} { @@ -229,9 +351,8 @@ % \end{macrocode} % \end{macro} % -% \begin{macro}{\fontspec_if_current_language:nTF} -% Test whether the currently loaded font is using the specified raw -% OpenType language tag |#1|. +% \begin{macro}[TF]{\fontspec_if_current_language:n} +% \darg{lang tag} % \begin{macrocode} \prg_new_conditional:Nnn \fontspec_if_current_language:n {TF,T,F} { @@ -252,18 +373,10 @@ % \end{macro} % % -% \begin{macro}{\fontspec_set_family:Nnn} +% \begin{macro}{\fontspec_gset_family:Nnn,\fontspec_set_family:Nnn} % \darg{family} % \darg{fontspec features} -% \darg{font name} -% Defines a new font family from given \meta{features} and \meta{font}, -% and stores the name in the variable \meta{family}. -% See the standard \pkg{fontspec} user commands for applications of this -% function. -% -% We want to store the actual name of the font family within the \meta{family} -% variable because the actual \LaTeX\ family name is automatically generated -% by fontspec and it's easier to keep it that way. +% \darg{font} % \begin{macrocode} \cs_new:Nn \@@_tl_new_if_free:N { \tl_if_exist:NF #1 { \tl_new:N #1 } } \cs_new:Nn \@@_set_family:NnnN @@ -286,7 +399,7 @@ % \end{macro} % % -% \begin{macro}{\fontspec_set_fontface:NNnn} +% \begin{macro}{\fontspec_gset_fontface:NNnn,\fontspec_set_fontface:NNnn} % TODO: the round-about approach of using \cs{fontname} % means that settings such as fontdimens will be lost. % (Discovered in unicode-math.) Investigate! @@ -308,7 +421,7 @@ % % % -% \begin{macro}{\fontspec_font_if_exist:n} +% \begin{macro}[TF]{\fontspec_font_if_exist:n} % \begin{macrocode} \prg_new_conditional:Nnn \fontspec_font_if_exist:n {TF,T,F} { @@ -326,9 +439,8 @@ % \end{macrocode} % \end{macro} -% \begin{macro}{\fontspec_if_current_feature:nTF} -% Test whether the currently loaded font is using the specified raw -% OpenType feature tag |#1|. +% \begin{macro}[TF]{\fontspec_if_current_feature:n} +% \darg{feat tag} % \begin{macrocode} \prg_new_conditional:Nnn \fontspec_if_current_feature:n {TF,T,F} { @@ -341,7 +453,7 @@ % \end{macrocode} % \end{macro} % -% \begin{macro}{\fontspec_if_small_caps:TF} +% \begin{macro}[TF]{\fontspec_if_small_caps:} % \begin{macrocode} \prg_new_conditional:Nnn \fontspec_if_small_caps: {TF,T,F} {