%%
%% This is file `mathfont-user-guide.tex',
%% generated with the docstrip utility.
%%
%% The original source files were:
%%
%% mathfont-code.dtx  (with options: `user')
%% 
%% This file is from version 3.0 of the free and open-source
%% LaTeX package "mathfont," released January 2026, to be used
%% with the XeTeX or LuaTeX engines. (As of version 2.0, LuaTeX
%% is recommended.)
%% 
%% Copyright 2018, 2019, 2021-2023, 2025, 2026 Conrad Kosowsky
%% 
%% This Work may be used, distributed, and modified under the
%% terms of the LaTeX Public Project License, version 1.3c or
%% any later version. The most recent version of this license
%% is available online at
%% 
%%           https://www.latex-project.org/lppl/.
%% 
%% This Work has the LPPL status "maintained," and the current
%% maintainer is the package author, Conrad Kosowsky. He can
%% be reached at kosowsky.latex@gmail.com.
%% 
%% PLEASE KNOW THAT THIS FREE SOFTWARE IS PROVIDED WITHOUT
%% ANY WARRANTY. SPECIFICALLY, THE "NO WARRANTY" SECTION OF
%% THE LATEX PROJECT PUBLIC LICENSE STATES THE FOLLOWING:
%% 
%% THERE IS NO WARRANTY FOR THE WORK. EXCEPT WHEN OTHERWISE
%% STATED IN WRITING, THE COPYRIGHT HOLDER PROVIDES THE WORK
%% `AS IS’, WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED
%% OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
%% WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
%% PURPOSE. THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE
%% OF THE WORK IS WITH YOU. SHOULD THE WORK PROVE DEFECTIVE,
%% YOU ASSUME THE COST OF ALL NECESSARY SERVICING, REPAIR, OR
%% CORRECTION.
%% 
%% IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED
%% TO IN WRITING WILL THE COPYRIGHT HOLDER, OR ANY AUTHOR
%% NAMED IN THE COMPONENTS OF THE WORK, OR ANY OTHER PARTY
%% WHO MAY DISTRIBUTE AND/OR MODIFY THE WORK AS PERMITTED
%% ABOVE, BE LIABLE TO YOU FOR DAMAGES, INCLUDING ANY GENERAL,
%% SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING OUT
%% OF ANY USE OF THE WORK OR OUT OF INABILITY TO USE THE WORK
%% (INCLUDING, BUT NOT LIMITED TO, LOSS OF DATA, DATA BEING
%% RENDERED INACCURATE, OR LOSSES SUSTAINED BY ANYONE AS A
%% RESULT OF ANY FAILURE OF THE WORK TO OPERATE WITH ANY
%% OTHER PROGRAMS), EVEN IF THE COPYRIGHT HOLDER OR SAID
%% AUTHOR OR SAID OTHER PARTY HAS BEEN ADVISED OF THE
%% POSSIBILITY OF SUCH DAMAGES.
%% 
%% For more information, see the LaTeX Project Public License.
%% Derivative works based on this package may come with their
%% own license or terms of use, and the package author is not
%% responsible for any third-party software.
%% 
%% For more information, see mathfont-code.dtx. Happy TeXing!
%% 
\documentclass[12pt]{article}
\makeatletter
\usepackage[margin=72.27pt]{geometry}
\usepackage[factor=700,stretch=14,shrink=14,step=1]{microtype}
\usepackage[bottom]{footmisc}
\usepackage{booktabs}
\usepackage{graphicx}
\usepackage{tabularx}
\usepackage{multirow}
\usepackage[implicit=false,colorlinks=true,allcolors=blue]{hyperref}
\usepackage{enumitem}
\SetEnumitemKey{special}{topsep=\smallskipamount,
  itemsep=\smallskipamount,
  parsep=\z@,partopsep=\z@}
\setlist{special}
\usepackage{doc}[=v2]
\MakeShortVerb{|}

\protected\def\bigskip{\vskip\bigskipamount}
\protected\def\medskip{\vskip\medskipamount}
\protected\def\smallskip{\vskip\smallskipamount}

\def\link#1{\href{#1}{\nolinkurl{#1}}}
\newcount\fig
\fig=1\relax
\c@topnumber\@ne

\def\labelfig#1{\immediate\write\@auxout{\string\makelabel{#1}{\the\fig}}}
\def\makelabel#1#2{\expandafter\gdef\csname fig@#1\endcsname{#2}}

\begin{document}
\def\ref#1{\csname fig@#1\endcsname}

\def\documentname{User Guide}
\def\showabstract{1}
\input mathfont-heading.tex

\baselineskip=\the\baselineskip minus 0.5pt

\noindent Handling fonts in \TeX\ and \LaTeX\ is a notoriously difficult task because fonts are complicated.\footnote{The last few decades have seen huge advances in loading fonts with \TeX. Donald Knuth originally designed \TeX\ to load only fonts created with Metafont, and more recent engines such as Jonathan Kew's \XeTeX\ and Hans Hagen, et al.'s Lua\TeX\ have extended \TeX's font-loading capabilities to Unicode. \XeTeX\ supports OpenType and TrueType fonts natively, and Lua\TeX\ can load OpenType fonts through the \hbox{\textsf{luaotfload}} package. Information on \XeTeX\ is available at \link{https://tug.org/xetex/}, and information on Lua\TeX\ is available at the official website for Lua\TeX: \link{http://www.luatex.org/}. See also Ulrike Fischer, et al., ``\textsf{luaotfload}---OpenType `loader' for Plain \TeX\ and \LaTeX,'' \link{https://ctan.org/pkg/luaotfload}. For discussion of fonts generally, see Yannis Haralambous, \textit{Fonts \& Encodings} (Sebastopol: O'Reilly Media, Inc., 2007).} The \textsf{mathfont} package addresses this situation by providing tools to use TrueType and OpenType fonts in math mode and in the main text, and this user guide explains how to operate \textsf{mathfont}. For version history and code implementation, see |mathfont-code.pdf|, and for a list of all symbols accessible with \textsf{mathfont}, see |mathfont-symbol-list.pdf|. Those two pdf files, this user guide, and four example files are included in the \textsf{mathfont} installation and are available on \textsc{ctan}. Because Unicode text fonts are plentiful, I hope that this package expands the possibilities for typesetting math in \LaTeX.

\section{Loading and Basic Functionality}

Loading\vadjust{\penalty-9999} fonts for math typesetting is more complicated than for regular text. First, selecting fonts for math mode, both in plain \TeX\ and in the \textsc{nfss}, involves additional macros above and beyond what we need to load text fonts. Second, \TeX\ expects fonts for math to contain extra information for formatting equations.\footnote{Specifically, this extra information is a set of large variants, math-specific parameter values associated with individual characters, and a MathConstants table. Also, math fonts often use slightly wider bounding boxes for letters in math mode---the Computer Modern $f$ is a well-known example. (Compare math-mode {\fboxsep=0pt\fbox{$f$}} and italic {\fboxsep=0pt\fbox{\textit f}}. Without italic correction, we have {\fboxsep=0pt\fbox{\itshape f}}.) For this reason, \textsf{mathfont} provides an interface to enlarge the bounding boxes of most Unicode characters when they appear in math mode. See section~5 for details.} Broadly speaking, we say that a \textit{math font} contains this extra information, whereas a \textit{text font} does not, and typesetting math with glyphs from one or more text fonts may yield messier equations than using a properly prepared math font. The functionality of \textsf{mathfont} then is twofold: (1) provide a wrapper around the \textsc{nfss} commands for math typesetting that serves as a high-level interface; and (2) implement Lua\TeX\ callbacks that artificially convert text fonts into math fonts at loading.\footnote{Values for MathConstants table are different from but inspired by Ulrik Vieth, ``Understanding the \AE sthetics of Math Typesetting,'' (Bacho\TeX\ Conference, 2008) and Ulrik Vieth ``OpenType Math Illuminated,'' \textit{TUGboat} 30 (2009): 22--31. See also Bogus\l aw Jackowski, ``Appendix G Illuminated,'' \textit{TUGboat} 27 (2006): 83--90.} Although \textsf{mathfont} tries its best to get your fonts right, it may run into trouble when picking fonts to load. If this happens, you should declare your font family and shapes in the \textsc{nfss} before setting any fonts with \textsf{mathfont}.

\begin{figure}[t]\labelfig{packages}
\centerline{\bfseries Table \the\fig: Comparison of General Font-Loading Packages\strut}
\global\advance\fig\@ne
\begin{tabular*}{\textwidth}{@{\extracolsep{\fill}}lll}\toprule
& Text font & Math font\\\cmidrule{2-3}
Traditional \TeX\ font & \textsf{mathastext} & No general package\\
Unicode font (for math typesetting) & \textsf{mathfont} or \textsf{mathspec} & \textsf{unicode-math}\\
Unicode font (for text only) & \textsf{fontspec} & \textsf{fontspec} \\\bottomrule
\end{tabular*}
\end{figure}

You must use one of \XeLaTeX\ or Lua\LaTeX\ to typeset a document with \textsf{mathfont}. You can load \textsf{mathfont} with the standard |\usepackage| syntax, and the package accepts five optional arguments. If you use Lua\TeX, the options |adjust| or |no-adjust| will manually specify whether \textsf{mathfont} should adapt text fonts for math mode, and \textsf{mathfont} selects |adjust| by default. If you use \XeTeX, \textsf{mathfont} cannot adjust any font objects with Lua callbacks, and either of these package options will cause an error.\footnote{With \XeLaTeX, \textsf{mathfont} does not add big operators or resizable delimiters to the font. This means you will have to use the Computer Modern defaults, load a separate math font for resizable characters, or end up with a document where large operators and delimiters do not scale like they do normally.} For this reason, using Lua\TeX\ with \textsf{mathfont} is recommended as of version 2.0. The options |default-loader| and |fontspec-loader| determine which font-loading code \textsf{mathfont} uses. If you load the package with the |default-loader| option, \textsf{mathfont} uses a built-in font-loader, and if you load the package with |fontspec-loader|, \textsf{mathfont} uses the font-loader from \textsf{fontspec}. If you load \textsf{mathfont} with any other optional argument, the package will interpret it as a font name and call |\documentfont| (described in the next section) on your argument. Doing so selects that font for the text of your document and for the character classes in the upper portion of Table~\ref{Keywords}.

\begin{figure}[t]\labelfig{commands}
\centerline{\bfseries Table \the\fig: Main User-Level Control Sequences Provided by \textsf{mathfont}\strut}
\global\advance\fig\@ne
\tabcolsep\z@
\begin{tabular*}{\textwidth}{@{\extracolsep{\fill}}llp{1in}<{\raggedright\arraybackslash}}\toprule
Control Sequence & Use & Engine\\\midrule
\vrb\documentfont & Set font for text and math & \multirow{6}{*}{\vbox{\XeTeX\ and Lua\TeX}}\\
\vrb\mainfont & Set font for text &\\
\vrb\mathfont & Set font for math &\\
\vrb\mathfontshapes & Declare font shapes in the preamble &\\
\vrb\newmath\meta{specifier} & Create local font-change command for math &\\
\vrb\mathfontcommands & Create several local font-change commands &\\\midrule
\vrb\mathconstantsfont & Select MathConstants table for use &\multirow{8}{*}{Lua\TeX\ only}\\
\vrb\charmline & Enlarge bounding box; change size of extensibles &\\
\vrb\charmfile & Call \vrb\charmline\ on each line from a file &\\
\vrb\charminfo & Print charm information of a character &\\
\vrb\charmtype & Print type of a character for charm purposes &\\
\vrb\hsurdfactor & Move overline for square root horizontally &\\
\vrb\vsurdfactor & Move overline for square root vertically &\\
\vrb\rulethicknessfactor & Set rule thickness for square root, fractions &\\
\bottomrule
\end{tabular*}
\end{figure}

\begin{figure}[t]\labelfig{Keywords}
\centerline{\bfseries Table \the\fig: Character Classes\strut}
\global\advance\fig by 1\relax
\tabcolsep\z@
\begin{tabular*}{\textwidth}{@{\extracolsep{\fill}}lllc}\toprule
Keyword & Meaning & Default Shape Identifier & Alphabetic?\\\midrule
|upper| & Upper-Case Latin & |italic| & Yes\\
|lower| & Lower-Case Latin & |italic| & Yes\\
|diacritics| & Diacritics & |upright| & Yes\\
|greekupper| & Upper-Case Greek & |upright| & Yes\\
|greeklower| & Lower-Case Greek & |italic| & Yes\\
|digits| & Arabic Numerals & |upright| & Yes\\
|operator| & Operator Font & |upright*| & N/A\rlap{\textsuperscript\dag}\\
|delimiters| & Delimiter & |upright| & No\\
|radical| & Square Root Symbol & |upright| & No\\
|symbols| & Basic Math Symbols & |upright| & No\\
|bigops| & Big Operators & |upright| & No\\\midrule
|agreekupper| & Upper-Case Ancient Greek & |upright| & Yes\\
|agreeklower| & Lower-Case Ancient Greek & |italic| & Yes\\
|cyrillicupper| & Upper-Case Cyrillic & |upright| & Yes\\
|cyrilliclower| & Lower-Case Cyrillic & |italic| & Yes\\
|hebrew| & Hebrew & |upright| & Yes\\
|extsymbols| & Extended Math Symbols & |upright| & No\\
|arrows| & Arrows & |upright| & No\\
|extbigops| & Extended Big Operators & |upright| & No\\
|bb| & Blackboard Bold (double-struck) & |upright| & No\\
|cal| & Caligraphic & |upright| & No\\
|frak| & Fraktur & |upright| & No\\
|bcal| & Bold Caligraphic & |upright| & No\\
|bfrak| & Bold Fraktur & |upright| & No\\
\bottomrule
\end{tabular*}
\smallskip\footnotesize
\noindent\strut\textsuperscript\dag Technically |opererator| is not a class of symbols but rather is a local font-change instruction similar to what is described in section~3 of this user guide.
\end{figure}

\begin{figure}[t]\labelfig{Shape-Identifiers}
\centerline{\bfseries Table \the\fig: Shape Identifiers\strut}
\global\advance\fig by 1\relax
\begin{tabular*}{\textwidth}{@{\extracolsep{\fill}}lllll}\toprule
Identifier & Series & Uses \textsc{nfss} Series & Shape & Uses \textsc{nfss} Shape\\\midrule
|upright| & medium & \vrb\mddefault & upright & \vrb\shapedefault\\
|italic| & medium & \vrb\mddefault & italic & \vrb\itdefault\\
|bold| & bold & \vrb\bfdefault & upright & \vrb\shapedefault\\
|bolditalic| & bold & \vrb\bfdefault & italic & \vrb\itdefault\\
\meta{series}|/|\meta{shape} && \meta{series} && \meta{shape}\\
\bottomrule
\end{tabular*}
\end{figure}

The \textsf{mathfont} package is closely related to several other \LaTeX\ packages. The functionality is closest to that of \textsf{mathspec} by Andrew Gilbert Moschou.\footnote{Andrew Gilbert Moschou, ``\textsf{mathspec}---Specify arbitrary fonts for mathematics in \XeTeX,'' \link{https://ctan.org/pkg/mathspec}.} That package is compatible with \XeTeX\ only and loads text fonts for use in math. The \textsf{unicode-math} package is a main \LaTeX\ package for loading actual Unicode math fonts, and if you have a Unicode font with proper math support, rather than a text font that you want to use for equations, consider using that package instead of \textsf{mathfont}.\footnote{Will Robertson, et al., ``\textsf{unicode-math}---Unicode mathematics support for XeTeX and LuaTeX,'' \link{https://ctan.org/pkg/unicode-math}.} Users who want a text font for math with pdf\LaTeX\ should consider Jean-Fran\c cois Burnol's \textsf{mathastext} because \textsf{mathfont} is incompatible with pdf\TeX.\footnote{Jean-Fran\c cois Burnol, ``\textsf{mathastext}---Use the text font in maths mode,'' \link{https://ctan.org/pkg/mathastext}. In several previous versions of this documentation, I mischaracterized the approach of \textsf{mathastext} to \TeX's internal mathematics spacing. In fact, \textsf{mathastext} preserves and in some cases extends rules for space between various math-mode characters.} Finally, you may be better off using \textsf{fontspec} if your document does not contain any math.\footnote{Will Robertson and Khaled Hosny, ``\textsf{fontspec}---Advanced font selection in \XeLaTeX\ and Lua\LaTeX,'' \link{https://ctan.org/pkg/fontspec}.} The \textsf{fontspec} package is designed to load TrueType and OpenType fonts for text and provides a high-level interface for selecting OpenType font features. Table~\ref{packages} summarizes this information.

\section{Setting the Default Font}

The \textsf{mathfont} package provides three commands for setting fonts in your document. The |\mathfont| command sets the font for various classes of characters when they appear in math mode, and after you call |\mathfont| on any class of characters, you can use Unicode input for that class of characters in math mode. The |\mainfont| command sets the font outside of equations. The control sequence |\documentfont| calls both |\mainfont| and |\mathfont|, calls |\mathconstantsfont| if the engine is Lua\TeX, and calls |\mathfontcommands| if in the document preamble. Each of these three commands accepts one optional argument and one mandatory argument, so the full syntax is
\begin{code}
|\documentfont[|\meta{\textup{\ttfamily rm}, \textup{\ttfamily sf}, \textup{\ttfamily tt}, or empty}|]{|\meta{font name}|}|\\
|\mainfont[|\meta{\textup{\ttfamily rm}, \textup{\ttfamily sf}, \textup{\ttfamily tt}, or empty}|]{|\meta{font name}|}|\\
|\mathfont[|\meta{keywords}|]{|\meta{font name}|}|
\end{code}
More recent calls to any of these commands will override previous instructions, and all font changes through these macros are local. \textit{This is a backwards-incompatible change in version 3.0.} For context, \LaTeX\ classifies fonts into family (what most users typically think of as a ``font''), series (the weight, usually medium or bold), and shape (the appearance, usually upright or italic). The mandatory argument of these three commands specifies a font family, and the optional argument of |\mathfont| specifies font series and shape. To choose a series and shape outside of math mode, you should use the standard commands from the kernel.\footnote{Specifically,\vadjust{\penalty-1000} \vrb\fontseries\ and \vrb\fontshape\ locally select arbitrary series and shapes from the \textsc{nfss}, and the kernel provides macros that reformat their argument such as \vrb\textbf\ and \vrb\textit.}

The optional argument for |\mainfont| and |\documentfont| determines how \textsf{mathfont} stores the font information. Using |rm|, |sf|, or |tt| will prompt \textsf{mathfont} to set both |\familydefault| and one of |\rmdefault|, |\sfdefault|, or |\ttdefault| respectively to the requested \textsc{nfss} family. The corresponding |\rmfamily|, |\sffamily|, or |\ttfamily| command will switch to the font family thereafter. Providing an empty optional argument instructs \textsf{mathfont} to switch to the font family without saving the font name, and in this case, you will see no change in the effects of |\rmfamily| and friends. If you do not provide an optional argument, \textsf{mathfont} uses |rm|.

The optional argument for |\mathfont| should be a comma-separated list of keywords from Table~\ref{Keywords}, and it determines which math-mode characters will undergo a font change. When you use this command, \textsf{mathfont} sets the font family for every character in those keywords when in math mode to the mandatory argument. For a list of characters associated with the different keywords, see |mathfont_symbol_list.pdf|. If you do not specify an optional argument, |\mathfont| uses all keywords from the upper half of Table~\ref{Keywords} (but not including |delimiters|, |radical|, or |bigops| characters in \XeTeX), so calling |\mathfont| with no optional argument is a fast way to change the font for most common math characters.

Characters in math mode often appear in different series or shapes from the same font family, and \textsf{mathfont} allows users to request particular series and shape combinations by using the shape identifiers in Table~\ref{Shape-Identifiers}. By default, the characters in a \meta{keyword} will follow the shape identifier stored in |\|\meta{keyword}|default|, so for example, |\upperdefault| is initially defined to be the character string |italic|. Table~\ref{Keywords} contains the initial value of each default setting. To change the series and shape, you can redefine any |\|\meta{keyword}|default| macro to a different shape identifier, or you can request a different shape identifier in the optional argument of |\mathfont|. If you say |=|\meta{shape identifier} immediately after a keyword and before the following comma, the package will apply your requested \meta{shape identifier} to that keyword. For example, if you say
\begin{code}
|\mathfont[upper=upright, lower=upright]{Baskerville}|
\end{code}
you will see Latin letters appear in upright Baskerville in your equations.

You may include |*| character immediately after the shape identifier if you want \textsf{mathfont} to use unmodified characters from the font. This option is most appropriate for situations such as math operators where you want to use regular text in your equations and do not need enlarged bounding boxes. For example, the command
\begin{code}
|\mathfont[upper, lower, operator=italic*]{Times New Roman}|
\end{code}
changes all Latin letters to italic Times New Roman and switches math operators to the same italic text that you would see if you use Times New Roman outside of math. This feature does not do anything in \XeTeX.

The mandatory argument of all three font-setting commands should be a system font name or an \textsc{nfss} font family name. If you use a system font, you can select OpenType features by putting a colon after the font name and following it with the appropriate tags.\footnote{By default, \textsf{mathfont} enables standard ligatures, traditional \TeX\ ligatures, and lining numbers. The package sets |smcp| to |true| or |false| depending on whether it is attempting to load a small-caps font. For the full list of OpenType features, see \link{https://docs.microsoft.com/en-us/typography/opentype/spec/featurelist}.} The syntax for specifying features depends on the font-loader: with the built-in font-loader, you should use the standard ``|+|\meta{tag}'' or ``|-|\meta{tag}'' syntax, and when using \textsf{fontspec} as the font-loader, you should use that package's high-level interface, as described in the \textsf{fontspec} documentation. For example, suppose you want math with oldstyle numbers. With the built-in font-loader, you should add ``|+onum|,'' or if using \textsf{fontspec}, you should add |Numbers=OldStyle| to your |\mathfont| command. So to load Adobe Garamond Pro with oldstyle numbering, you would say
\begin{code}
|\mathfont{Adobe Garamond Pro:+onum}|
\end{code}
with the built-in font-loader or
\begin{code}
|\mathfont{Adobe Garamond Pro: Numbers=OldStyle}|
\end{code}
if using \textsf{fontspec}. With the built-in font-loader, you should separate OpenType tags with semi-colons, and for \textsf{fontspec}, you should use commas.

When the mandatory argument of a font-changing command is an \textsc{nfss} family name, \textsf{mathfont} uses that font family. When the engine is \XeTeX, you don't have to do anything special and can ignore the rest of this paragraph. When the engine is Lua\TeX, \textsf{mathfont} expects the \textsc{nfss} to contain a second entry for the same font family that uses base mode for loading.\footnote{The \textsf{luaotfload} package supports three modes for loading fonts: |node|, |base|, and |harf|. The default setting is |node| mode. It supports full OpenType features in text but none for math, whereas |base| mode supports fewer OpenType features, but they work in both text and math. Loading a font with |harf| mode engages HarfBuzz, a font shaper that arranges characters in potentially complicated layouts but also provides no access to OpenType features in math.} If \meta{name} is the mandatory argument, you should tell \textsf{mathfont} the family name for the base-mode version by storing it in the control sequence |\|\meta{name}|-base|. If you do not do this, you will see an error message. My intention is that the first font family is for text, and the base-mode font family is for math---using two different loading options provides the greatest access to OpenType font features throughout your document.

You can access blackboard-bold, calligraphic, or fraktur letters in three ways. First, the Unicode standard contains encoding slots for these types of letters, and the last five keywords in Table~\ref{Keywords} access this portion of the Unicode table.\footnote{The Math Alphanumeric Symbols block is U+1D400--U+1D7FF. Most blackboard-bold, calligraphic, and fraktur letters live in this portion of the Unicode table, although a few live in other places.} If you call |\mathfont| on one of these \meta{keyword}s, the package defines the macro
\begin{code}
|\math|\meta{keyword}|{|\meta{text}|}|
\end{code}
which behaves like a local font-change command from the next section and converts Latin letters into \meta{keyword} style. For example,
\begin{code}
|\mathfont[bb]{STIXGeneral}|
\end{code}
defines |\mathbb| to typeset blackboard-bold letters using the glyphs from STIXGeneral. Second, you may have a Unicode font where the normal Latin letters are themselves double struck, calligraphic, or fraktur, and in that case, you should declare a local font-change command using the tools in the next section. Third, \textsf{mathfont} should play nicely with (local) font-changing macros from other packages, so you should have no problem using, for example, \textsf{amssymb} with \textsf{mathfont}.\footnote{American Mathematical Society, ``\textsf{amssymb}.'' See also American Mathematical Society, ``\textsf{amsfonts}---\TeX\ fonts from the American Mathematical Society,'' \link{https://ctan.org/pkg/amsfonts}.}

\begin{figure}[t]
\labelfig{MathAlpha}
\centerline{\bfseries Table \the\fig: Macros to Create Local Font-Change Commands with Preset Shapes\strut}
\global\advance\fig by 1\relax
\tabcolsep\z@
\begin{tabular*}{\textwidth}{@{\extracolsep{\fill}}lllll}\toprule
Command & Series & Uses \textsc{nfss} Series & Shape & Uses \textsc{nfss} Shape\\\midrule
|\newmathrm| & Medium & |\mddefault| & Upright & |\shapedefault|\\
|\newmathit| & Medium & |\mddefault| & Italic & |\itdefault|\\
|\newmathbf| & Bold & |\bfdefault| & Upright & |\shapedefault|\\
|\newmathbfit| & Bold & |\bfdefault| & Italic & |\itdefault|\\
|\newmathsc| & Medium & |\mddefault| & Small Caps & |\scdefault|\\
|\newmathscit| & Medium & |\mddefault| & Italic Small Caps & |\scdefault\itdefault|\\
|\newmathbfsc| & Bold & |\bfdefault| & Small Caps & |\scdefault|\\
|\newmathbfscit| & Bold & |\bfdefault| & Italic Small Caps & |\scdefault\itdefault|\\\bottomrule
\end{tabular*}
\end{figure}

\section{Local Font Changes}

With \textsf{mathfont}, it is possible to create commands that locally change the font for math alphabet characters, i.e.\ those marked as alphabetic in Table~\ref{Keywords}. (I am slightly abusing notation. In this section, I mean local as in acting on a small portion of the document, not local with respect to grouping. All font-change commands from \textsf{mathfont} are local in that regard.) The commands from this section should appear only in the preamble. The eight commands in Table~\ref{MathAlpha} accept a \meta{control sequence} as their first mandatory argument and a \meta{font name} as the second, so for example, the macro |\newmathrm| looks like
\begin{code}
|\newmathrm{|\meta{control sequence}|}{|\meta{font name}|}|
\end{code}
You can specify OpenType features as part of the \meta{font name} the same way as in the previous section. The macros in Table~\ref{MathAlpha} define the control sequence in their first argument to accept a string of characters and convert it to the font family in the second argument. The series and shape information depend on the command used. For example, writing
\begin{code}
|\newmathrm{\matharial}{Arial}|
\end{code}
creates the macro
\begin{code}
|\matharial{|\meta{argument}|}|
\end{code}
which can be used only in math mode and which converts the math alphabet characters in its \meta{argument} into the Arial font with upright shape and medium weight.

The macro |\mathfontcommands| accepts a single font name as its argument. It calls each |\newmath|\meta{specifier} command from Table~\ref{MathAlpha} to define |\math|\meta{specifier} using the font family from its argument. For example,
\begin{code}
|\mathfontcommands{Helvetica}|
\end{code}
makes the standard font-changing commands such as |\mathrm| and |\mathit| use Helvetica instead of Computer Modern.

In traditional \LaTeX, |\mathrm| and friends do not change the font for Greek characters. That remains the case until you call |\mathfont| for |greeklower| or |greekupper| characters, and then any local font-change commands from this section will work on lower-case or upper-case Greek letters respectively. Similarly, the local font-change commands will affect Cyrillic and Hebrew characters after you call |\mathfont| for those keywords.

These nine control sequences provide tools for most local font changes, but they won't be able to address everything. Accordingly, \textsf{mathfont} provides general |\newmathfontcommand| macro. Its argument structure is
\begin{code}
|\newmathfontcommand{|\meta{control sequence}|}{|\meta{font name}|}{|\meta{series}|}{|\meta{shape}|}|
\end{code}
where the \meta{control sequence} in the first argument again becomes the macro that changes characters to the \meta{font name}. You are welcome to use a system font name when you call |\newmathfontcommand|, but my intention behind this command is that you can use an \textsc{nfss} family name for the \meta{font name}. Then the series and shape values can correspond to more obscure font faces from the \textsc{nfss} family that you would be otherwise unable to access. As with |\mathfont|, if you are using Lua\TeX\ and the \meta{font name} is an \textsc{nfss} family, you should make sure that you defined |\|\meta{font name}|-base|, or you will see an error.

\section{Default Math Parameters}

Lua\TeX\ uses the MathConstants table from the most recent font assigned for use in math mode, and this means that in a document with multiple math fonts, the choice of MathConstants table can depend on the order of font declaration and be unpredictable. To avoid potential problems from using the wrong MathConstants table, \textsf{mathfont} provides
\begin{code}
|\mathconstantsfont[|\meta{shape identifier}|]{|\meta{font name}|}|
\end{code}
where \meta{shape identifier} is a shape identifier from Table~\ref{Shape-Identifiers} and \meta{font name} is a font name as in the previous two sections. By default, |\mathconstantsfont| uses |upright| for the optional argument. This macro forces Lua\TeX\ to use the MathConstants table from the requested font face, and once again, if you use an \textsc{nfss} family name for \meta{font name} with Lua\TeX, make sure to define |\|\meta{font name}|-base| appropriately. You don't need to set the MathConstants table when you use |\documentfont| or pass a font name to \textsf{mathfont} at loading because the package calls |\mathconstantsfont| automatically in this case. This command does not do anything in \XeTeX.

\section{Declaring Font Shapes}

You\vadjust{\penalty-9999} are welcome to use the commands from sections~2 and 4 after |\begin{document}|, but you are limited in what fonts you can use. \LaTeX\ prohibits new font declarations after the preamble, and at that point, \textsf{mathfont} will only use font faces that already exist in the \textsc{nfss} or that it used for any purpose previously. What this means in practical terms: if you want to use |\mathfont| or |\mainfont| after |\begin{document}|, you probably have to use a font that \textsf{mathfont} handled in some capacity in the preamble. This makes it nonobvious how to use a font after the preamble if you do not want to set that font for any characters in the preamble.

To address this situation, \textsf{mathfont} provides the command |\mathfontshapes|. The purpose of this macro is to declare font shapes before |\begin{document}| without using them for anything. It accepts one optional argument and one mandatory argument, so the syntax is
\begin{code}
|\mathfontshapes[|\meta{shape identifiers}|]{|\meta{font name}|}|
\end{code}
The optional argument should be a comma-separated list of shape identifiers, and by default, the macro uses |upright|, |upright*|, |italic|, and |bold|. The mandatory argument should be a font name like in the previous sections.

After you use |\mathfontshapes|, you should have no problem using the same font family for |\mainfont|. You will also be able to use the font family for |\mathfont| or |\mathconstantsfont| provided that you stick to shape identifiers that appeared in the optional argument of |\mathfontshapes|. For example, if you say
\begin{code}
|\mathfontshapes{Didot}|
\end{code}
in your preamble, you can include
\begin{code}
|\mathfont{Didot}|
\end{code}
after the preamble (even if you didn't have it in the preamble), but if you type
\begin{code}
|\mathfont[operator=italic*]{Didot}|
\end{code}
you will run into problems because |\mathfontshapes| does not normally use the shape identifier |italic*|. You should instead say
\begin{code}
|\mathfontshapes[italic*]{Didot}|
\end{code}
in your preamble to avoid any issues.

\section{Lua Font Adjustments}

When Lua\TeX\ reads in a font file, \textsf{mathfont} makes the font object in memory appear to be a math font rather than a text font. Most of this process happen behind the scenes, but \textsf{mathfont} provides control sequences that allow you to customize some modifications. With the exception of the read-only control sequences |\charminfo| and |\charmtype|, their wrapped equivalents, and the count variables, all macros from this section should appear in the preamble only.

The main macro for doing so is |\charmline|. (Charm stands for ``character metric.'') It accepts one mandatory argument, so the syntax is
\begin{code}
|\charmline{|\meta{charm information}|}|
\end{code}
The \meta{charm information} should be a sequence of entries separated by a comma and/or space, where entry means one or two numbers or asterisks. If an entry is two numbers, two asterisks, or one of each, you must separate them with a slash, and the first entry in \meta{charm information} should be a single integer between 0 and 1,114,111. The command fully expands its argument, and you may see strange errors if \meta{charm information} contains unexpandable control sequences. Processing uses |tonumber()| from Lua, so your input can include anything that Lua recognizes as a number. In particular, you can specify hexadecimal numbers by prefixing them with |0x|.

This macro controls how \textsf{mathfont} adjusts bounding boxes, accent placement, and large variants. The first entry in \meta{charm information} corresponds to an entry in the Unicode table, and \textsf{mathfont} references the remaining entries when it alters properties of the character in that encoding slot during font loading. For purposes of charm information, a character can have one of two types: |a| for ``alphabetic'' or |e| for ``extensible.''\footnote{Alphabetic is something of a misnomer that I kept for historical reasons.} Any character that resizes, such as delimiters, big operators, and the surd character has type |e|, and you should specify 33 additional entries after the encoding slot. All other characters have type |a|, and you should specify 4 additional entries after the encoding slot. If you specify too few charm values, \textsf{mathfont} will raise an error, and if you provide too many, \textsf{mathfont} ignores the extras and prints a warning on the terminal. Version 3.0 eliminates type |u| and requires an extra entry for type |e| characters, and \textit{these are backwards-incompatible changes.} If you call |\charmline| for an encoding slot that does not have any charm information, \textsf{mathfont} assumes that character should be type |a|. You can change a character to type |e| by including an |!| symbol immediately after the first entry, and you can change a character to type |a| by including a |?| symbol immediately after the first entry.

\begin{figure}[t]
\labelfig{Charm}
\centerline{\bfseries Table \the\fig: Number of Entries Required in \vrb\charmline\strut}
\global\advance\fig by 1\relax
\begin{tabularx}\textwidth{Xcl}\toprule
Character & Type & \hfil Total Number of Entries\\\midrule
Everything Else & |a| & \hfil5\\
Delimiters, Radical (Surd Character), Big Operators & |e| & \hfil34\\
\bottomrule
\end{tabularx}
\end{figure}

When \textsf{mathfont} parses \meta{charm information}, the order of the entries determines their purpose. As is standard in \TeX, \textsf{mathfont} divides all numbers in |\charmline| by 1000 to form floats before using them in calculations. For type |a| characters, the second and third entries tell Lua\TeX\ how much to stretch the left and right sides of the glyph's bounding box when it appears in math mode, and the third entry determines horizontal placement of top math accents. The final entry determines the |bot_accent| attribute for that character in the font object, although Lua\TeX\ does not use this piece of information for formatting equations.\footnote{See Hans Hagen and Mikael P. Sundqvist, ``On Bottom Accents in OpenType Math,'' \textit{TUGBoat} 44 (2023): 207--208. See also two threads from the Lua\TeX\ developer mailing list from 2012, available at
\edef\temp{http://mailman.ntg.nl/archives/list/dev-luatex@ntg.nl/thread/3SDPLVHQYLVHHOBUA3DWROTWLMUBUQI5/\string#WX432F6M52MUIK4WE5I3W7YSJOWDIA4G}%
\edef\tempurl{http:\break//mailman.ntg.nl/archives/list/dev-luatex@ntg.nl/thread/3SDPLVHQYLVHHOBUA3DWROTWLMUBUQI5/\hfil\break\string#WX432F6M52MUIK4WE5I3W7YSJOWDIA4G}%
\@onelevel@sanitize\temp
\href{\temp}{\texttt{\tempurl}} and
\edef\temp{https://mailman.ntg.nl/archives/list/dev-luatex@ntg.nl/thread/PU2VYNG7XBWVBBUY4VIPJOS75NNZM7UE/\string#PU2VYNG7XBWVBBUY4VIPJOS75NNZM7UE}%
\@onelevel@sanitize\temp\expandafter\link\expandafter{\temp}.}
If the Unicode value corresponds to a type |e| character, \textsf{mathfont} interprets the first 30 entries after the encoding slot as 15 successive pairs of horizontal and vertical scale factors that determine the size of large variants. For example, the second and third entries in \meta{charm information} are the horizontal and vertical scale factors for the first large variant. The last three entries determine, respectively,\vadjust{\penalty-1000} horizontal placement of top accents, the |bot_accent| attribute, and the character's italic correction.

Asterisks and subentries affect how \textsf{mathfont} uses charm information in memory. Writing an asterisk tells \textsf{mathfont} to use whatever value it has saved in memory, either the default value or the value from the most recent call to |\charmline| or |\charmfile|. When an entry contains two subentries, \textsf{mathfont} uses the first subentry for unslanted fonts and the second subentry for slanted or italic fonts. If an entry is a single number or asterisk, \textsf{mathfont} uses that input for both slanted and unslanted fonts.

If you want to store charm information in a file instead of your document preamble, you should use the control sequence |\charmfile|. This command accepts one mandatory argument, so the syntax is
\begin{code}
|\charmfile{|\meta{file name}|}|
\end{code}
It reads in a file and calls |\charmline| individually on each line from the file.

The default settings are decent, so for most applications, you can probably ignore charm information altogether. However, if you find bounding boxes or accent placement to be off slightly in your equations or if you want to change the scaling for a delimiter or big operator, you should try calling |\charmline| with different values to see what works. For a given character, the scale for changes is the width of that character's unmodified bounding box.\footnote{For type |a|, it's technically the unmodified bounding box width plus italic correction because \textsf{mathfont} incorporates the italic correction into the character width.} For example,
\begin{code}
|\charmline{0x61, 200, -100, *, 50}|
\end{code}
tells \textsf{mathfont} to take the lower-case ``a'' (U+61, i.e.\ encoding slot number 97), increase the bounding box on the left side by 20\% of the character width, decrease the bounding box on the right side by 10\% of the character width, do nothing to the top accent, and shift the |bot_accent| attribute right by 5\% of the character width. There is no general formula for what charm values to use for a given font! Rather, you will need to make a design choice based on what looks best, and if you regularly use a specific font, consider making a custom set of charm values and uploading it to \textsc{ctan}.

The package provides two commands to query charm information in memory, namely |\charminfo| and |\charmtype|. These macros are weird in that they don't take an argument. Rather, they scan (and remove) the next integer from the input stream in the same manner as a |\count| variable, so the syntax is
\begin{code}
|\charminfo|\meta{integer}\\
|\charmtype|\meta{integer}
\end{code}
Both macros are fully expandable and work outside the document preamble. If \textsf{mathfont} has charm information in memory for the Unicode encoding slot \meta{integer}, |\charmtype| expands to |a| or |e| depending on the type of that character, and |\charminfo| expands to a space-separated lists of charm entries. The results of |\charminfo| look exactly like the input of |\charmline|, so typing
\begin{code}
|\charmline{|\meta{encoding slot}|,\charminfo|\meta{encoding slot}|}|
\end{code}
is valid syntax and reassigns the charm information for \meta{encoding slot} to itself. If \meta{integer} is not the encoding slot for a character with charm information, both macros expand to |none|.

Three count variables affect equation formatting with \textsf{mathfont}. Their default value is 1000, and \textsf{mathfont} divides\vadjust{\penalty-1000} their value by 1000 to convert them to floats before using them. The first two, |\hsurdfactor| and |\vsurdvactor|, affect the positioning of the overline in square root expressions. Specifically, changing either count scales the bounding box for the surd (square root) character by the corresponding float value. Larger values of |\hsurdvactor| therefore shift the overline to the right, and smaller values do the opposite. Larger values of |\vsurdfactor| raise the overline. The third count, |\rulethicknessfactor|, determines the thickness of horizontal rules such as the overline in square root expressions or the fraction bar. You will probably want to increase |\rulethicknessfactor| for fonts with heavier weight and decrease it for fonts with lighter weight. Please be aware that \textsf{mathfont} uses the value of each count only once per font when \TeX\ loads the font for math typesetting. This typically happens the first time the user enters math mode.

The package provides user-friendly versions of each control sequence in this section. The macros |\CharmInfo| and |\CharmType| accept an integer as a single mandatory argument and print the results of |\charminfo| and |\charmtype| to the terminal. The macros |\SurdHorizontalFactor|, |\SurdVerticalFactor|, and |\RuleThicknessFactor| similarly accept a single integer as a mandatory argument and set the corresponding count variable to that value. Additionally, |\IntegralItalicFactor| accepts an integer as its argument and divides the argument by 1000 to form a float. When \TeX\ loads a font, it increases the italic correction of the integral symbol by that fraction of the symbol's width, which affects positioning of limits. For parity in macro names and backwards compatibility, |\CharmLine| and |\CharmFile| are defined to do the same thing as their lower-case counterparts.

\begin{figure}[t]
\labelfig{Callbacks}
\centerline{\bfseries Table \the\fig: Lua Callbacks Created by \textsf{mathfont}\strut}
\global\advance\fig by 1\relax
\newbox\mybox
\setbox\mybox\vbox{\raggedright
  \hsize0.9in\relax If base mode\break and |nomath|}
\begin{tabularx}\textwidth{lXl}\toprule
Callback Name & What It Does By Default & Called?\\\midrule
|"mathfont.inspect_font"| &  Nothing & Always\\\midrule
|"mathfont.pre_adjust"| & Nothing & \multirow{7}{*}{\copy\mybox}\\
|"mathfont.disable_nomath"| & Set font attribute |nomath| to false &\\
|"mathfont.add_math_constants"| &  Create a MathConstants table &\\
|"mathfont.fix_character_metrics"|&  \raggedright\arraybackslash Adjust bounding boxes, add character-specific math fields, create large variants &\\
|"mathfont.post_adjust"| &  Nothing &\\\midrule
|"mathfont.finishing_touches"| & Nothing & Always\\
\bottomrule
\end{tabularx}
\end{figure}

Advanced users who want to interact with the font adjustment process directly should use the seven callbacks in Table~\ref{Callbacks}. When \textsf{luaotfload} loads a font, \textsf{mathfont} (1) always calls |mathfont.inspect_font|; (2) calls the middle five callbacks in the order that they appear in Table~\ref{Callbacks} if the font object contains |nomath=true| and was loaded with |base| mode; and (3) always calls |mathfont.finishing_touches|. Functions added to these callbacks should accept a font object as a single argument and return nothing. Further, please be careful when loading functions in |disable_nomath|, |add_math_constants|, and |fix_character_metrics|. If you add a function there, Lua\TeX\ will not carry out the default behavior associated with the callback, so do not mess with these three callbacks unless you are duplicating the default behavior or you really know what you're doing. Otherwise, you risk breaking the package. See |mathfont-code.pdf| for more information.

\end{document}
\endinput
%%
%% End of file `mathfont-user-guide.tex'.
