summaryrefslogtreecommitdiff
path: root/macros/unicodetex/latex/fontspec/fontspec-code-api.dtx
diff options
context:
space:
mode:
authorNorbert Preining <norbert@preining.info>2024-04-28 03:00:59 +0000
committerNorbert Preining <norbert@preining.info>2024-04-28 03:00:59 +0000
commit6ed42a56797a9b75307dcebfd82f2d69767e1b97 (patch)
treea3a53cbc357c9bd13040bede870d9b1801293eb4 /macros/unicodetex/latex/fontspec/fontspec-code-api.dtx
parent71f3eefe319b1194e0470ee83dd8723b3288f8d4 (diff)
CTAN sync 202404280300
Diffstat (limited to 'macros/unicodetex/latex/fontspec/fontspec-code-api.dtx')
-rw-r--r--macros/unicodetex/latex/fontspec/fontspec-code-api.dtx223
1 files changed, 168 insertions, 55 deletions
diff --git a/macros/unicodetex/latex/fontspec/fontspec-code-api.dtx b/macros/unicodetex/latex/fontspec/fontspec-code-api.dtx
index e8a8878e66..be63bcc056 100644
--- a/macros/unicodetex/latex/fontspec/fontspec-code-api.dtx
+++ b/macros/unicodetex/latex/fontspec/fontspec-code-api.dtx
@@ -1,14 +1,12 @@
-%%^^A%% fontspec-code-api.dtx -- part of FONTSPEC <wspr.io/fontspec>
+%%^^A%% fontspec-code-api.dtx -- part of FONTSPEC <latex3.github.io/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,22 +373,15 @@
% \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
{
+%<debug>\typeout{::::::~fontspec_set_family:Nnn}
\tl_set:Nn \l_@@_fontface_cs_tl {\l_fontspec_font} % reset
\tl_set:Nn \l_@@_family_label_tl {#1}
\@@_select_font_family:nn {#2} {#3}
@@ -285,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!
@@ -307,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}
{
@@ -325,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}
{
@@ -340,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}
{
@@ -376,10 +489,10 @@
% /©
% ------------------------------------------------
-% The FONTSPEC package <wspr.io/fontspec>
+% The FONTSPEC package <latex3.github.io/fontspec>
% ------------------------------------------------
-% Copyright 2022-2023 The LaTeX project
-% Copyright 2004-2022 Will Robertson, LPPL "maintainer"
+% 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