summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/source/latex/fontspec/fontspec-user.dtx
diff options
context:
space:
mode:
Diffstat (limited to 'Master/texmf-dist/source/latex/fontspec/fontspec-user.dtx')
-rw-r--r--Master/texmf-dist/source/latex/fontspec/fontspec-user.dtx461
1 files changed, 461 insertions, 0 deletions
diff --git a/Master/texmf-dist/source/latex/fontspec/fontspec-user.dtx b/Master/texmf-dist/source/latex/fontspec/fontspec-user.dtx
new file mode 100644
index 00000000000..f9db2c2d2fc
--- /dev/null
+++ b/Master/texmf-dist/source/latex/fontspec/fontspec-user.dtx
@@ -0,0 +1,461 @@
+% \section{User commands}\label{sec:codeuser}
+%
+% This section contains the definitions of the commands detailed in
+% the user documentation. Only the `top level' definitions of the
+% commands are contained herein; they all use or define macros which
+% are defined or used later on in \vref{sec:codeinternal}.
+%
+% \iffalse
+% \begin{macrocode}
+%<*fontspec&(xetexx|luatex)>
+% \end{macrocode}
+% \fi
+%
+% \subsubsection{Helper macros for argument mangling}
+% \begin{macrocode}
+\cs_new:Nn \@@_pass_args:nnn
+ {
+ \IfNoValueTF {#2}
+ { \@@_post_arg:w {#1} {#3} }
+ { #1 {#2} {#3} }
+ }
+\NewDocumentCommand \@@_post_arg:w { m m O{} }
+ { #1 {#3} {#2} }
+% \end{macrocode}
+%
+% \subsubsection{Font selection}
+% \begin{macro}{\fontspec}
+% This is the main command of the package that
+% selects fonts with various features. It takes two arguments: the
+% font name and the optional requested features of that
+% font. Then this new font family is selected.
+% \begin{macrocode}
+\NewDocumentCommand \fontspec { o m }
+ { \@@_pass_args:nnn \@@_fontspec:nn {#1} {#2} }
+
+\cs_new:Nn \@@_fontspec:nn
+ {
+ \fontspec_set_family:Nnn \f@family {#1} {#2}
+ \fontencoding { \l_@@_nfss_enc_tl }
+ \selectfont
+ \ignorespaces
+ }
+% \end{macrocode}
+% \end{macro}
+%
+% \begin{macro}{\setmainfont}
+% \begin{macro}{\setsansfont}
+% \begin{macro}{\setmonofont}
+% The following three macros perform equivalent operations setting
+% the default font for a
+% particular family: `roman', sans serif, or typewriter
+% (monospaced). I end them with |\normalfont| so that if they're
+% used in the document, the change registers immediately.
+% \begin{macrocode}
+\DeclareDocumentCommand \setmainfont { o m }
+ { \@@_pass_args:nnn \@@_setmainfont:nn {#1} {#2} }
+
+\cs_new:Nn \@@_setmainfont:nn
+ {
+ \fontspec_set_family:Nnn \rmdefault {#1}{#2}
+ \normalfont
+ \ignorespaces
+ }
+
+\DeclareDocumentCommand \setsansfont { o m }
+ { \@@_pass_args:nnn \@@_setsansfont:nn {#1} {#2} }
+
+\cs_new:Nn \@@_setsansfont:nn
+ {
+ \fontspec_set_family:Nnn \sfdefault {#1}{#2}
+ \normalfont
+ \ignorespaces
+ }
+
+\DeclareDocumentCommand \setmonofont { o m }
+ { \@@_pass_args:nnn \@@_setmonofont:nn {#1} {#2} }
+
+\cs_new:Nn \@@_setmonofont:nn
+ {
+ \fontspec_set_family:Nnn \ttdefault {#1}{#2}
+ \normalfont
+ \ignorespaces
+ }
+% \end{macrocode}
+% \end{macro} \end{macro} \end{macro}
+%
+%
+% \begin{macro}{\setromanfont}
+% This is the old name for \cs{setmainfont}, retained
+% for backwards compatibility.
+% \begin{macrocode}
+\cs_set_eq:NN \setromanfont \setmainfont
+% \end{macrocode}
+% \end{macro}
+%
+%
+% \begin{macro}{\setmathrm}
+% \begin{macro}{\setmathsf}
+% \begin{macro}{\setboldmathrm}
+% \begin{macro}{\setmathtt}
+% These commands are analogous to \cmd\setmainfont\ and others,
+% but for selecting the font used for \cmd\mathrm, \etc. They
+% can only be used in the preamble of the
+% document. \cmd\setboldmathrm\ is used for specifying which
+% fonts should be used in \cmd\boldmath.
+% \begin{macrocode}
+\tl_new:N \g_@@_mathrm_tl
+\tl_new:N \g_@@_bfmathrm_tl
+\tl_new:N \g_@@_mathsf_tl
+\tl_new:N \g_@@_mathtt_tl
+\DeclareDocumentCommand \setmathrm { o m }
+ { \@@_pass_args:nnn \@@_setmathrm:nn {#1} {#2} }
+
+\cs_new:Nn \@@_setmathrm:nn
+ {
+ \fontspec_set_family:Nnn \g_@@_mathrm_tl {#1} {#2}
+ }
+
+\DeclareDocumentCommand \setboldmathrm { o m }
+ { \@@_pass_args:nnn \@@_setboldmathrm:nn {#1} {#2} }
+
+\cs_new:Nn \@@_setboldmathrm:nn
+ {
+ \fontspec_set_family:Nnn \g_@@_bfmathrm_tl {#1} {#2}
+ }
+
+\DeclareDocumentCommand \setmathsf { o m }
+ { \@@_pass_args:nnn \@@_setmathsf:nn {#1} {#2} }
+
+\cs_new:Nn \@@_setmathsf:nn
+ {
+ \fontspec_set_family:Nnn \g_@@_mathsf_tl {#1} {#2}
+ }
+
+\DeclareDocumentCommand \setmathtt { o m }
+ { \@@_pass_args:nnn \@@_setmathtt:nn {#1} {#2} }
+
+\cs_new:Nn \@@_setmathtt:nn
+ {
+ \fontspec_set_family:Nnn \g_@@_mathtt_tl {#1} {#2}
+ }
+\@onlypreamble\setmathrm
+\@onlypreamble\setboldmathrm
+\@onlypreamble\setmathsf
+\@onlypreamble\setmathtt
+% \end{macrocode}
+% If the commands above are not executed, then \cmd\rmdefault\ (\etc)
+% will be used.
+% \begin{macrocode}
+\tl_set:Nn \g_@@_mathrm_tl {\rmdefault}
+\tl_set:Nn \g_@@_mathsf_tl {\sfdefault}
+\tl_set:Nn \g_@@_mathtt_tl {\ttdefault}
+% \end{macrocode}
+% \end{macro} \end{macro} \end{macro}
+% \end{macro}
+%
+% \begin{macro}{\newfontfamily}
+% \begin{macro}{\newfontface}
+% This macro takes the arguments of \cs{fontspec} with a prepended
+% \meta{instance cmd}. This command is used
+% when a specific font instance needs to be referred to repetitively
+% (\eg, in a section heading) since continuously calling
+% \cs{fontspec_select:nn} is inefficient because it must parse the
+% option arguments every time.
+%
+% \cs{fontspec_select:nn} defines a font family and saves its name in
+% \cs{l_fontspec_family_tl}. This family is then used in a typical NFSS \cmd\fontfamily\
+% declaration, saved in the macro name specified.
+% \begin{macrocode}
+\DeclareDocumentCommand \newfontfamily { m o m }
+ { \@@_pass_args:nnn { \@@_newfontfamily:Nnn #1 } {#2} {#3} }
+
+\cs_new:Nn \@@_newfontfamily:Nnn
+ {
+ \fontspec_set_family:cnn { g_@@_ \cs_to_str:N #1 _family } {#2} {#3}
+ \use:x
+ {
+ \exp_not:N \DeclareRobustCommand \exp_not:N #1
+ {
+ \exp_not:N \fontfamily { \use:c {g_@@_ \cs_to_str:N #1 _family} }
+ \exp_not:N \fontencoding { \l_@@_nfss_enc_tl }
+ \exp_not:N \selectfont
+ }
+ }
+ }
+% \end{macrocode}
+% \cmd\newfontface\ uses the fact that if the argument to \feat{BoldFont}, etc., is empty (\ie, |BoldFont={}|), then no bold font is searched for.
+% \begin{macrocode}
+\DeclareDocumentCommand \newfontface { m o m }
+ { \@@_pass_args:nnn { \@@_newfontface:Nnn #1 } {#2} {#3} }
+
+\cs_new:Nn \@@_newfontface:Nnn
+ {
+ \newfontfamily #1 [ BoldFont={},ItalicFont={},SmallCapsFont={},#2 ] {#3}
+ }
+% \end{macrocode}
+% \end{macro} \end{macro}
+%
+% \subsubsection{Font feature selection}
+%
+% \begin{macro}{\defaultfontfeatures}
+% This macro takes one argument that consists of all of feature
+% options that will be applied by default to all subsequent
+% \cs{fontspec}, et al., commands. It stores its value in
+% \cs{g_fontspec_default_fontopts_tl} (initialised empty), which is
+% concatenated with the individual macro choices in the
+% [...] macro.
+% \begin{macrocode}
+\clist_new:N \g_@@_default_fontopts_clist
+\prop_new:N \g_@@_fontopts_prop
+% \end{macrocode}
+%
+% \begin{macrocode}
+\DeclareDocumentCommand \defaultfontfeatures { t+ o m }
+ {
+ \IfNoValueTF {#2}
+ { \@@_set_default_features:nn {#1} {#3} }
+ { \@@_set_font_default_features:nnn {#1} {#2} {#3} }
+ \ignorespaces
+ }
+\cs_new:Nn \@@_set_default_features:nn
+ {
+ \IfBooleanTF {#1} \clist_put_right:Nn \clist_set:Nn
+ \g_@@_default_fontopts_clist {#2}
+ }
+% \end{macrocode}
+% The optional argument specifies a font identifier.
+% Branch for either (a)~single token input such as \verb|\rmdefault|, or (b)~otherwise assume its a fontname.
+% In that case, strip spaces and file extensions and lower-case to ensure consistency.
+% \begin{macrocode}
+\cs_new:Nn \@@_set_font_default_features:nnn
+ {
+ \clist_map_inline:nn {#2}
+ {
+ \tl_if_single:nTF {##1}
+ { \tl_set:No \l_@@_tmp_tl { \cs:w g_@@_ \cs_to_str:N ##1 _family\cs_end: } }
+ { \@@_sanitise_fontname:Nn \l_@@_tmp_tl {##1} }
+
+ \IfBooleanTF {#1}
+ {
+ \prop_get:NVNF \g_@@_fontopts_prop \l_@@_tmp_tl \l_@@_tmpb_tl
+ { \tl_clear:N \l_@@_tmpb_tl }
+ \tl_put_right:Nn \l_@@_tmpb_tl {#3,}
+ \prop_gput:NVV \g_@@_fontopts_prop \l_@@_tmp_tl \l_@@_tmpb_tl
+ }
+ {
+ \tl_if_empty:nTF {#3}
+ { \prop_gremove:NV \g_@@_fontopts_prop \l_@@_tmp_tl }
+ { \prop_put:NVn \g_@@_fontopts_prop \l_@@_tmp_tl {#3,} }
+ }
+ }
+ }
+% \end{macrocode}
+%
+% \begin{macro}{\@@_sanitise_fontname:Nn}
+% Assigns font name |#2| to token list variable |#1| and strips extension(s) from it in the case of an external font.
+% We strip spaces for luatex for consistency with luaotfload, although I'm not sure this is necessary any more.
+% At one stage this also lowercased the name, but this step has been removed unless someone can remind me why it was necessary.
+% \begin{macrocode}
+\cs_new:Nn \@@_sanitise_fontname:Nn
+ {
+ \tl_set:Nx #1 {#2}
+%<luatex> \tl_remove_all:Nn #1 {~}
+ \clist_map_inline:Nn \l_@@_extensions_clist
+ {
+ \tl_if_in:NnT #1 {##1}
+ {
+ \tl_remove_once:Nn #1 {##1}
+% \keys_set:nn {fontspec-preparse-external} { Extension = ##1 }
+ \clist_map_break:
+ }
+ }
+ }
+% \end{macrocode}
+% \end{macro}
+% \end{macro}
+%
+%
+%
+% \begin{macro}{\addfontfeatures}
+% In order to be able to extend the feature selection of
+% a given font, two things need to be known: the currently selected
+% features, and the currently selected font. Every time a font
+% family is created, this information is saved inside a control
+% sequence with the name of the font family itself.
+%
+% This macro extracts this information, then appends the requested
+% font features to add to the already existing ones, and calls the
+% font again with the top level \cs{fontspec} command.
+%
+% The default options are \emph{not} applied (which is why
+% \cs{g_fontspec_default_fontopts_tl} is emptied inside the group; this is allowed
+% as \cmd\l_fontspec_family_tl\ is globally defined in \cmd\fontspec_select:nn), so this
+% means that the only added features to the font are strictly those
+% specified by this command.
+%
+% \cs{addfontfeature} is defined as an alias, as I found that I
+% often typed this instead when adding only a single font feature.
+% \begin{macrocode}
+\bool_new:N \l_@@_disable_defaults_bool
+\DeclareDocumentCommand \addfontfeatures {m}
+ {
+ \fontspec_if_fontspec_font:TF
+ {
+ \group_begin:
+ \keys_set_known:nnN {fontspec-addfeatures} {#1} \l_@@_tmp_tl
+ \prop_get:cnN {g_@@_ \f@family _prop} {options} \l_@@_options_tl
+ \prop_get:cnN {g_@@_ \f@family _prop} {fontname} \l_@@_fontname_tl
+ \bool_set_true:N \l_@@_disable_defaults_bool
+ \use:x
+ {
+ \exp_not:N \fontspec_select:nn
+ { \l_@@_options_tl , #1 } {\l_@@_fontname_tl}
+ }
+ \group_end:
+ \fontfamily\l_fontspec_family_tl\selectfont
+ }
+ {
+ \@@_warning:nx {addfontfeatures-ignored} {#1}
+ }
+ \ignorespaces
+ }
+\cs_set_eq:NN \addfontfeature \addfontfeatures
+% \end{macrocode}
+% \end{macro}
+%
+%
+%
+% \subsubsection{Defining new font features}
+%
+% \begin{macro}{\newfontfeature}
+% \cs{newfontfeature} takes two arguments: the name of the feature
+% tag by which to reference it, and the string that is used to
+% select the font feature.
+% \begin{macrocode}
+\DeclareDocumentCommand \newfontfeature {mm}
+ {
+ \keys_define:nn { fontspec }
+ {
+ #1 .code:n =
+ {
+ \@@_update_featstr:n {#2}
+ }
+ }
+ }
+% \end{macrocode}
+% \end{macro}
+%
+%
+% \begin{macro}{\newAATfeature}
+% This command assigns a new AAT feature by its code (|#2|,|#3|) to a new name (|#1|).
+% Better than \cmd\newfontfeature\ because it checks if the feature exists in the
+% font it's being used for.
+% \begin{macrocode}
+\DeclareDocumentCommand \newAATfeature {mmmm}
+ {
+ \keys_if_exist:nnF { fontspec } {#1}
+ { \@@_define_font_feature:n {#1} }
+ \keys_if_choice_exist:nnnT {fontspec} {#1} {#2}
+ { \@@_warning:nxx {feature-option-overwrite} {#1} {#2} }
+ \@@_define_feature_option:nnnnn {#1}{#2}{#3}{#4}{}
+ }
+% \end{macrocode}
+% \end{macro}
+%
+% \begin{macro}{\newopentypefeature}
+% \begin{macro}{\newICUfeature}
+% This command assigns a new OpenType feature by its abbreviation (|#2|) to a new name (|#1|).
+% Better than \cmd\newfontfeature\ because it checks if the feature exists in the
+% font it's being used for.
+% \begin{macrocode}
+\DeclareDocumentCommand \newopentypefeature {mmm}
+ {
+ \keys_if_exist:nnF { fontspec / options } {#1}
+ { \@@_define_font_feature:n {#1} }
+ \keys_if_choice_exist:nnnT {fontspec} {#1} {#2}
+ { \@@_warning:nxx {feature-option-overwrite} {#1} {#2} }
+ \@@_define_feature_option:nnnnn {#1}{#2}{}{}{#3}
+ }
+\cs_set_eq:NN \newICUfeature \newopentypefeature % deprecated
+% \end{macrocode}
+% \end{macro}
+% \end{macro}
+%
+%
+% \begin{macro}{\aliasfontfeature}
+% \begin{macro}{\aliasfontfeatureoption}
+% User commands for renaming font features and font feature options.
+% \begin{macrocode}
+\bool_new:N \l_@@_alias_bool
+\DeclareDocumentCommand \aliasfontfeature {mm}
+ {
+ \bool_set_false:N \l_@@_alias_bool
+
+ \clist_map_inline:nn
+ { fontspec, fontspec-preparse, fontspec-preparse-external,
+ fontspec-preparse-nested, fontspec-renderer }
+ {
+
+ \keys_if_exist:nnT {##1} {#1}
+ {
+ \bool_set_true:N \l_@@_alias_bool
+ \@@_alias_font_feature:nnn {##1} {#1} {#2}
+ }
+ }
+
+ \bool_if:NF \l_@@_alias_bool
+ { \@@_warning:nx {rename-feature-not-exist} {#1} }
+ }
+
+\cs_set:Nn \@@_alias_font_feature:nnn
+ {
+ \keys_define:nn {#1}
+ { #3 .code:n = { \keys_set:nn {#1} { #2 = {##1} } } }
+ }
+
+\DeclareDocumentCommand \aliasfontfeatureoption {mmm}
+ { \keys_define:nn { fontspec / #1 } { #3 .meta:n = {#2} } }
+% \end{macrocode}
+% \end{macro} \end{macro}
+%
+% \begin{macro}{\newfontscript}
+% Mostly used internally, but also possibly useful for users, to define new OpenType
+% `scripts', mapping logical names to OpenType script tags.
+% \begin{macrocode}
+\DeclareDocumentCommand \newfontscript {mm}
+ {
+ \fontspec_new_script:nn {#1} {#2}
+ }
+% \end{macrocode}
+% \end{macro}
+%
+% \begin{macro}{\newfontlanguage}
+% Mostly used internally, but also possibly useful for users, to define new OpenType
+% `languages', mapping logical names to OpenType language tags.
+% \begin{macrocode}
+\DeclareDocumentCommand \newfontlanguage {mm}
+ {
+ \fontspec_new_lang:nn {#1} {#2}
+ }
+% \end{macrocode}
+% \end{macro}
+%
+%
+% \begin{macro}{\DeclareFontsExtensions}
+% \texttt{dfont} would never be uppercase, right?
+% \begin{macrocode}
+\DeclareDocumentCommand \DeclareFontsExtensions {m}
+ {
+ \clist_set:Nn \l_@@_extensions_clist { #1 }
+ \tl_remove_all:Nn \l_@@_extensions_clist {~}
+ }
+\DeclareFontsExtensions{.otf,.ttf,.OTF,.TTF,.ttc,.TTC,.dfont}
+% \end{macrocode}
+% \end{macro}
+%
+% \iffalse
+% \begin{macrocode}
+%</fontspec&(xetexx|luatex)>
+% \end{macrocode}
+% \fi