%%^^A%% um-doc-main.tex -- part of UNICODE-MATH <wspr.io/unicode-math>

\begin{abstract}
\noindent
This document describes the \pkg{unicode-math} package, which is
intended as an implementation of Unicode
maths for \LaTeX\ using the \XeTeX\ and Lua\TeX\ typesetting engines.
With this package, changing maths fonts is as easy as changing
text fonts --- and there are more and more maths fonts appearing now.
Maths input can also be simplified with Unicode since literal glyphs may be
entered instead of control sequences in your document source.

The package provides support for both \XeTeX\ and Lua\TeX. The different
engines provide differing levels of support for Unicode maths.
Please let us know of any troubles.

Alongside this documentation file, you should be able to find a minimal
example demonstrating the use of the package,
`\texttt{unimath-example.ltx}'. It also comes with a separate document,
`\texttt{unimath-symbols.pdf}',
containing a complete listing of mathematical symbols defined by
\pkg{unicode-math}, including comparisons between different fonts.

Finally, while the STIX fonts may be used with this package, accessing
their alphabets in their `private user area' is not yet supported.
(Of these additional alphabets there is a separate calligraphic design
distinct to the script design already included.)
Better support for the STIX fonts is planned for an upcoming revision of the
package after any problems have been ironed out with the initial version.

\end{abstract}

\newpage
\tableofcontents

\clearpage
\section{Introduction}

This document describes the \pkg{unicode-math} package, which is an
\emph{experimental} implementation of a macro to Unicode glyph encoding for
mathematical characters.

Users who desire to specify maths alphabets only (Greek and Latin letters,
and Arabic numerals)
may wish to use Andrew Moschou's \pkg{mathspec} package instead.
(\XeTeX-only at time of writing.)
Note that \pkg{unicode-math} and \pkg{mathspec} are not compatible with each other.

\section{Acknowledgements}

Many thanks to:
Microsoft for developing the mathematics extension to OpenType as part of
Microsoft Office~2007;
Jonathan Kew for implementing Unicode math support in \XeTeX;
Taco Hoekwater for implementing Unicode math support in \LuaTeX;
Barbara Beeton for her prodigious effort compiling the definitive list of Unicode math
glyphs and their \LaTeX\ names (inventing them where necessary), and also
for her thoughtful replies to my sometimes incessant questions;
Philipp Stephani for extending the package to support \LuaTeX.
Ross Moore and Chris Rowley have provided moral and technical support
from the very early days with great insight into the issues we face trying
to extend and use \TeX\ in the future.
Apostolos Syropoulos, Joel Salomon, Khaled Hosny, and Mariusz Wodzicki
have been fantastic beta testers.

\section{Getting started}

Load \pkg{unicode-math} as a regular \LaTeX\ package.
It should be loaded after any other maths or font-related package in case it needs to overwrite their definitions.
It requires \pkg{amsmath}, which it will automatically load if the user hasn't already done so.
Here's an example using the filename syntax to load the \TeX\ Gyre Pagella Math font: (this works for both \XeLaTeX\ and \LuaLaTeX)
\begin{Verbatim}
\usepackage{amsmath}
\usepackage{unicode-math}
\setmathfont{texgyrepagella-math.otf}
\end{Verbatim}

Once the package is loaded, traditional TFM-based maths fonts are no longer supported;
you can only switch to a different OpenType maths font using the \cs{setmathfont} command.
If you do not load an OpenType maths font before |\begin{document}|, Latin Modern Math will be loaded automatically.


\subsection{New commands}
\LaTeX, since the first version of \LaTeXe, changed the math group
selection from, say, |{\bf x}| to |\mathbf{x}|. It introduced commands
such as |\mathbf|, |\mathit|, |\mathsf|, |\mathtt| and |\mathcal|,
besides |\mathnormal|.  This was not only done to maintain the analogy
with |\textbf|, |\textit| and so on, but with the precise purpose of
loading the needed math groups (or math families) on demand and not
allocating them if not required by the document.

The introduction of \pkg{unicode-math} posed some problems fitting into this design. For
instance, there is a big difference between say |fit| as an operator
name in boldface type and the product of three boldface variables.
With legacy \TeX{} engines, |\mathbf{fit}| would use a ligature and
the same would happen with the input |\mathbf{f}\mathbf{i}\mathbf{t}|.
For the latter case, the user should probably use |\mathbf{f\/}|.

However, there is another important point from a \emph{conceptual}
point of view. A boldface variable name should be printed using the
\emph{math font}, whereas a boldface operator name should be printed
using the \emph{text font}. OpenType math fonts make this distinction
feasible, because they contain several math alphabets. Of course a
boldface text~`x' will not differ much (or at all) from a boldface
math~`x', but this is not the point: they \emph{should} be considered
different, because the former is |U+0078| in Unicode, the latter is
|U+1D431|.

It was clear that \emph{two} different commands are needed: one for using text boldface in math,
one for using math boldface. Only the document's author can know
whether one or the other is needed. The decision was to split off
the two meanings with a command like |\mathbf| for the boldface text font
in math and a command like |\symbf| (for the bold math font).

The five new symbol font commands that behave in this way are: \cs{symup},
\cs{symit}, \cs{symbf}, \cs{symsf}, and \cs{symtt}.
These commands switch to single-letter mathematical symbols
(generally within the same OpenType font).

The legacy \cs{math..} commands switch to text fonts that are set up to behave
correctly in mathematics, and should be used for multi-letter identifiers.  These
could be denoted `text math alphabets'; further details are discussed
in \secref{mathselect}.  Additional similar `text math alphabet'
commands can be defined using the \cs{setmathfontface} command
discussed in \secref{mathselect}.  To control the behaviour of the
default text math alphabet commands to behave in a
backwards-compatible mode, see the package options described in
\secref{textmathlegacy}.


\begin{table}[t!]
  \topcaption{New \pkg{unicode-math} commands which overlap with legacy
  math commands. For new documents the \texttt{sym} versions are recommended.}
  \tablabel{symvsmath}
  \centering
  \begin{tabular}[t]{ll}
    \toprule
    Command & Synonym \\
    \midrule
    \cs{symnormal}  & \cs{mathnormal} \\
    \cs{symliteral} &                 \\
    &  \\
    &  \\
    &  \\
    \cs{symbb}      & \cs{mathbb}     \\
    \cs{symbbit}    & \cs{mathbbit}   \\
    \cs{symcal}     & \cs{mathcal}    \\
    \cs{symscr}     & \cs{mathscr}    \\
    \cs{symfrak}    & \cs{mathfrak}   \\
    \cs{symsfup}    & \cs{mathsfup}   \\
    \cs{symsfit}    & \cs{mathsfit}   \\
    \bottomrule
  \end{tabular}\qquad
  \begin{tabular}[t]{ll}
    \toprule
    Command & Synonym \\
    \midrule
    &  \\
    &  \\
    \cs{symbfsf}    & \cs{mathbfsf}   \\
    \cs{symbfup}    & \cs{mathbfup}   \\
    \cs{symbfit}    & \cs{mathbfit}   \\
    &  \\
    &  \\
    \cs{symbfcal}   & \cs{mathbfcal}  \\
    \cs{symbfscr}   & \cs{mathbfscr}  \\
    \cs{symbffrak}  & \cs{mathbffrak} \\
    \cs{symbfsfup}  & \cs{mathbfsfup} \\
    \cs{symbfsfit}  & \cs{mathbfsfit} \\
    \bottomrule
  \end{tabular}
\end{table}

In addition, \pkg{unicode-math} also provides a number of commands (such as
|\symcal|) to select specific `symbol alphabets' within the unicode
maths font, with usage, e.g., |$\symcal{G}$|${}\to\symcal{G}$.  The
full listing is shown in \Tabref{symvsmath}.  For backwards
compatibility, many of these are also defined with `familiar' synonyms
such as |\mathcal|.  However, where possible the `sym' prefix
commands should be preferred, as certain synonyms may become
deprecated in time. The |\symliteral| command is described in
\secref{math-style}.

Using the |\sym..| commands, the glyphs used to produce PDF output are Unicode-encoded,
and therefore a symbol such as $\symcal{G}$ can be copy-pasted into another programme
(or even into the source of another \LaTeX\ document using \pkg{unicode-math}) without
loss of meaning.
This is an important aspect of Unicode mathematics, but the \pkg{unicode-math} package
is not `pure' in the sense that the package also provides other mechanisms to change
the fonts used in the PDF output; the philosophy of the package is to provide mechanisms
for technical authors to invent and experiment with new syntaxes for their work.


\subsection{Package options}
Package options may be set when the package as loaded or at any later
stage with the \cs{unimathsetup} command. Therefore, the following two
examples are equivalent:
\begin{Verbatim}
\usepackage[math-style=TeX]{unicode-math}
% OR
\usepackage{unicode-math}
\unimathsetup{math-style=TeX}
\end{Verbatim}
Note, however, that some package options affects how maths is initialised
and changing an option such as |math-style| will not take effect until a
new maths font is set up.

Package options may \emph{also} be used when declaring new maths fonts,
passed via options to the \cs{setmathfont} command.
Therefore, the following two examples are equivalent:
\begin{Verbatim}
\unimathsetup{math-style=TeX}
\setmathfont{texgyrepagella-math.otf}
% OR
\setmathfont{texgyrepagella-math.otf}[math-style=TeX]
\end{Verbatim}

A summary list of package options is shown in \tabref{pkgopt}.
See following sections for more information.

\begin{table}\centering
  \topcaption{Package options.}
  \tablabel{pkgopt}
  \begin{tabular}{lll}
    \toprule
    Option & Description & See\dots \\
    \midrule
    |math-style| & Style of letters & \secref*{math-style} \\
    |bold-style| & Style of bold letters & \secref*{bold-style} \\
    |sans-style| & Style of sans serif letters & \secref*{sans-style} \\
    |nabla|      & Style of the nabla symbol & \secref*{nabla} \\
    |partial|    & Style of the partial symbol & \secref*{partial} \\
    |colon| & Behaviour of \cs{colon} & \secref*{colon} \\
    |slash-delimiter| & Glyph to use for `stretchy' slash & \secref*{slash-delimiter} \\
    \bottomrule
  \end{tabular}
\end{table}


\section{Unicode maths font setup}

In the ideal case, a single Unicode font will contain all maths glyphs we
need. The file |unicode-math-table.tex| (based on Barbara Beeton's \STIX\ table)
provides the mapping between Unicode
maths glyphs and macro names (all 3298 — or however many — of them!). A
single command
\codeline{\cmd\setmathfont\marg{font name}\oarg{font features}}
implements this for every every symbol and alphabetic variant.
That means |x| to $x$, |\xi| to $\xi$, |\leq| to $\leq$, etc., |\symscr{H}|
to $\symscr{H}$ and so on, all for Unicode glyphs within a single font.

This package deals well with Unicode characters for maths
input. This includes using literal Greek letters in formulae,
resolving to upright or italic depending on preference.

Font features specific to \pkg{unicode-math} are shown in \tabref{mathfontfeatures}.
Package options (see \tabref{pkgopt}) may also be used.
Other \pkg{fontspec} features are also valid.

\begin{table}\centering
  \topcaption{Maths font options.}
  \tablabel{mathfontfeatures}
  \begin{tabular}{lll}
    \toprule
    Option & Description & See\dots \\
    \midrule
    |range| & Style of letters & \secref{range} \\
    |script-font| & Font to use for sub- and super-scripts & \secref{sscript} \\
    |script-features| & Font features for sub- and super-scripts & \secref{sscript} \\
    |sscript-font| & Font to use for nested sub- and super-scripts & \secref{sscript} \\
    |sscript-features| & Font features for nested sub- and super-scripts & \secref{sscript} \\
    \bottomrule
  \end{tabular}
\end{table}

\subsection{Using multiple fonts}
\seclabel{range}

There will probably be few cases where a single Unicode maths font suffices
(simply due to glyph coverage). The \STIX\ font comes to mind as a
possible exception. It will therefore be necessary to delegate specific
Unicode ranges of glyphs to separate fonts:
  \codeline{\cmd\setmathfont\marg{font name}|[range=|\meta{unicode range}|,|\meta{font features}|]|}
where \meta{unicode range} is a comma-separated list of Unicode slot numbers and ranges such as |{"27D0-"27EB,"27FF,"295B-"297F}|.
Note that \TeX's syntax for accessing the slot number of a character, such as |`\+|, will also work here.
Only numerical slots can be used in ranged declarations.

Note that, for efficiency, the \pkg{unicode-math} package only loads a default maths setup when absolutely necessary.
Before you use the |range| option you must first load a `main' maths font in the standard way.

You may also use the macro for accessing the glyph, such as |range=|\cs{int}, or whole collection of symbols with the same math type, such as |range=\mathopen|, or complete math styles such as |range=\symbb| (or just |range=bb|).

\subsubsection{Control over alphabet ranges}

As discussed earlier, Unicode mathematics consists of a number of `alphabet styles' within a single font. In \pkg{unicode-math}, these ranges are indicated with the following (hopefully self-explanatory) labels:
\begin{quote}\ttfamily
\ExplSyntaxOn
\clist_const:Nn \g__um_named_ranges_clist {
up    ,
it    ,
bb    ,
bbit  ,
scr   ,
cal   ,
bfcal ,
frak  ,
tt    ,
sfup  ,
sfit  ,
bfup  ,
bfit  ,
bfscr ,
bffrak,
bfsfup,
bfsfit,
}
\clist_use:Nn \g__um_named_ranges_clist {\,,\,~}
\ExplSyntaxOff
\end{quote}
Fonts can be selected (for predefined ranges only) using the following syntax, in which case all other maths font setup remains untouched:
\begin{itemize}
\item |[range=bb]| to use the font for `|bb|' letters only.
\item |[range=bfsfit/{greek,Greek}]| for Greek lowercase and uppercase only (also with |latin|, |Latin|, |num| as possible options for Latin lower-/upper-case and numbers, resp.).
\item |[range=up->sfup]| to map to different output styles.
\end{itemize}

A common request is to load numerals only from a specific font. This can be
achieved with an option such as |range=up/{num}|.

Note that `meta-styles' such as `|bf|' and `|sf|' are not included in the list above since they are context dependent. Use |[range=bfup]| and |[range=bfit]| to effect changes to the particular ranges selected by `|bf|' (and similarly for `|sf|').

If a particular math style is not defined in the font, we fall back onto the lower-base plane (i.e., `upright') glyphs.
Therefore, to use an \ascii-encoded fractur font, for example, write
\begin{Verbatim}
  \setmathfont{SomeFracturFont}[range=frak]
\end{Verbatim}
and because the math plane fractur glyphs will be missing, \pkg{unicode-math} will know to use the \ascii\ ones instead.
If necessary this behaviour can be forced with |[range=frak->up]|, since the `|up|' range corresponds to \ascii\ letters.

%If you wanted to swap the maths symbols with sans serif forms, it would be possible to write |[range={up->sfup,it->sfit}]|.
%Note, however, that at present Unicode does not encode glyphs for sans serif Greek (\tabref{mathalphabets}).

Users of the impressive Minion Math fonts (commercial) may use remapping to access the bold glyphs using:
\begin{Verbatim}
  \setmathfont{MinionMath-Regular.otf}
  \setmathfont{MinionMath-Bold.otf}[range={bfup->up,bfit->it}]
\end{Verbatim}
To set up the complete range of optical sizes for these fonts, a font declaration such as the following may be used: (adjust may be desired according to the font size of the document)
\begin{Verbatim}
\setmathfont{Minion Math}[
 SizeFeatures = {
  {Size =      -6.01,  Font = MinionMath-Tiny},
  {Size =  6.01-8.41,  Font = MinionMath-Capt},
  {Size =  8.41-13.01, Font = MinionMath-Regular},
  {Size = 13.01-19.91, Font = MinionMath-Subh},
  {Size = 19.91-,      Font = MinionMath-Disp}
 }]

\setmathfont{Minion Math}[range = {bfup->up,bfit->it},
 SizeFeatures = {
  {Size =      -6.01,  Font = MinionMath-BoldTiny},
  {Size =  6.01-8.41,  Font = MinionMath-BoldCapt},
  {Size =  8.41-13.01, Font = MinionMath-Bold},
  {Size = 13.01-19.91, Font = MinionMath-BoldSubh},
  {Size = 19.91-,      Font = MinionMath-BoldDisp}
 }]
\end{Verbatim}


\subsection{Script and scriptscript fonts/features}
\seclabel{sscript}

Cambria Math uses OpenType font features to activate smaller optical sizes
for scriptsize and scriptscriptsize symbols (the $B$ and $C$, respectively,
in $A_{B_C}$).
Other typefaces (such as Minion Math) may use entirely separate font files.

The features |script-font| and |sscript-font| allow alternate fonts to be
selected for the script and scriptscript sizes, and |script-features| and
|sscript-features| to apply different OpenType features to them.

By default |script-features| is defined as |Style=MathScript| and |sscript-features| is |Style=MathScriptScript|.
These correspond to the two levels of OpenType's |ssty| feature tag.
If the |(s)script-features| options are specified manually, you must
additionally specify the |Style| options as above.


\subsection{Maths `versions'}

\LaTeX\ uses a concept known as `maths versions' to switch math fonts
mid-document.
This is useful because it is more efficient than loading a complete maths
font from scratch every time---especially with thousands of glyphs in the case of Unicode maths!
The canonical example for maths versions is to select a `bold' maths font
which might be suitable for section headings, say.
(Not everyone agrees with this typesetting choice, though; be careful.)

To select a new maths font in a particular version, use the syntax
  \codeline{\cmd\setmathfont\marg{font name}|[version=|\meta{version name}|,|\meta{font features}|]|}
and to switch between maths versions mid-document use the standard \LaTeX\ command
\cmd\mathversion\marg{version name}.

Note there are currently open issues regarding the interaction between the |version|
and the |range| features, so please proceed with caution.

\subsection{Legacy maths `alphabet' commands}
\seclabel{mathselect}

\LaTeX\ traditionally uses \cs{DeclareMathAlphabet} and \cs{SetMathAlphabet} to define document commands such as \cs{mathit}, \cs{mathbf}, and so on.
While these commands can still be used, \pkg{unicode-math} defines a wrapper command to assist with the creation of new such maths alphabet commands.
This command is known as \cs{setmathface} in symmetry with \pkg{fontspec}'s \cs{newfontface} command; it takes syntax:
\begin{quote}
  \cmd\setmathfontface\meta{command}\marg{font name}|[|\meta{font features}|]|

  \makebox[0pt][l]{\cmd\setmathfontface\meta{command}\marg{font name}|[||version=|\meta{version name}|,|\meta{font features}|]|}
\end{quote}
For example, if you want to define a new legacy maths alphabet font \cs{mathittt}:
\begin{verbatim}
  \setmathfontface\mathittt{texgyrecursor-italic.otf}
  ...
  $\mathittt{foo} = \mathittt{a} + \mathittt{b}$
\end{verbatim}


\subsubsection{Default `text math' fonts}

The five `text math' fonts, discussed above, are: \cs{mathrm}, \cs{mathbf}, \cs{mathit}, \cs{mathsf}, and \cs{mathtt}.
These commands are also defined with their original definition under synonyms \cs{mathtextrm}, \cs{mathtextbf}, and so on.
(These definitions hold regardless of package option, in case you need to be sure.)

When selecting document fonts using \pkg{fontspec} commands such as \cs{setmainfont}, \pkg{unicode-math} inserts some additional code into \pkg{fontspec} that keeps the current default fonts `in sync' with their corresponding \cs{mathrm} commands, etc.

For example, in standard \LaTeX, \cs{mathsf} doesn't change even if the main document font is changed using |\renewcommand\sfdefault{...}|. With \pkg{unicode-math} loaded, after writing |\setsansfont{Helvetica}|, \cs{mathsf} will now be set in Helvetica.

If the \cs{mathsf} font is set explicitly at any time in the preamble, this `auto-following' does not occur. The legacy math font switches can be defined either with commands defined by \pkg{fontspec} (|\setmathrm|, |\setmathsf|, etc.) or using the more general |\setmathfontface\mathsf| interface defined by \pkg{unicode-math}.


\subsubsection{Replacing `text math' fonts by symbols}
\seclabel{textmathlegacy}

For certain types of documents that use legacy input syntax, it may be preferable to have |\mathbf| behave as if it were |\symbf| en masse (et cetera respectively).
A series of package options (\tabref{legacyfontswitch}) are provided to facilitate switching the definition of \cs{mathXYZ} for the five legacy text math font definitions.

For example, if in a particular document |\mathbf| is used only for choosing symbols of vectors and matrices, a dedicated symbol font (|\symbf|) will produce better spacing and will better match the main math font.
In that case loading |unicode-math| with the |mathbf=sym| will achieve the desired result.

\begin{table}
  \centering
  \topcaption{Maths text font configuration options. Note that \cs{mathup} and \cs{mathrm} are aliases of each other and cannot be configured separately.}
  \tablabel{legacyfontswitch}
  \begin{tabular}{lll}
    \toprule
    Defaults (from `text' font) & From `maths symbols' \\
    \midrule
    |mathrm=text| &   |mathrm=sym |  \\
    |mathup=text|\rlap{$^\ast$} &   |mathup=sym|{}\rlap{$^\ast$}  \\
    |mathit=text| &   |mathit=sym |  \\
    |mathsf=text| &   |mathsf=sym |  \\
    |mathbf=text| &   |mathbf=sym |  \\
    |mathtt=text| &   |mathtt=sym |  \\
    \bottomrule
  \end{tabular}
\end{table}


\subsubsection{Operator font}

\LaTeX\ defines an internal command \cs{operator@font} for typesetting elements such as |\sin| and |\cos|.
This font is selected from the legacy |operators| NFSS `MathAlphabet', which is no longer relevant in the context of \pkg{unicode-math}.
By default, the \cs{operator@font} command is defined to switch to the \cs{mathrm} font.
You may now change these using the command:
\begin{Verbatim}
\setoperatorfont\mathit
\end{Verbatim}
Or, to select a \pkg{unicode-math} range:
\begin{Verbatim}
\setoperatorfont\symscr
\end{Verbatim}
\setoperatorfont\symscr
For example, after the latter above, |$\sin x$| will produce `$\sin x$'.

\mathversion{normal}
\setoperatorfont\mathrm


\section{Maths input}

\XeTeX's Unicode support allows maths input through two methods. Like
classical \TeX, macros such as \cmd\alpha, \cmd\sum, \cmd\pm, \cmd\leq, and
so on, provide verbose access to the entire repertoire of characters defined
by Unicode. The literal characters themselves may be used instead, for more
readable input files.

\subsection{Math `style'}
\seclabel{math-style}

Classically, \TeX\ uses italic lowercase Greek letters and \emph{upright}
uppercase Greek letters for variables in mathematics. This is contrary to
the \textsc{iso} standards of using italic forms for both upper- and lowercase.
Furthermore, in various historical contexts, often associated with French typesetting, it was common to use upright uppercase \emph{Latin} letters as well as upright
upper- and lowercase Greek, but italic lowercase latin. Finally, it is not unknown to use upright letters
for all characters, as seen in the Euler fonts.

The \pkg{unicode-math} package accommodates these possibilities with the
option \opt{math-style} that takes one of five (case sensitive) arguments:
\opt{TeX}, \opt{ISO}, \opt{french}, \opt{upright}, or \opt{literal}.\footnote{Interface inspired by Walter Schmidt's \pkg{lucimatx} package.}
The \opt{math-style} options' effects are shown in brief in \tabref{math-style}.

The philosophy behind the interface to the mathematical symbols
lies in \LaTeX's attempt of separating content and formatting. Because input
source text may come from a variety of places, the upright and
`mathematical' italic Latin and Greek alphabets are \emph{unified} from the
point of view of having a specified meaning in the source text. That is, to
get a mathematical ‘$x$’, either the \ascii\ (`keyboard') letter |x| may
be typed, or the actual Unicode character may be used. Similarly for Greek
letters. The upright or italic forms are then chosen based on the
|math-style| package option.

If glyphs are desired that do not map as per the package option (for
example, an upright `g' is desired but typing |$g$| yields `$g$'),
\emph{markup} is required to specify this; to follow from the example:
|\symup{g}|.
Maths style commands such as \cmd\symup\ are detailed later.

For compatibility and consistency, however, upright and italic Greek letters
can be `forced` using \verb|up| or \verb|it| prefixes before their names.
For example, \cs{Gamma} will give an upright or italic Gamma depending on the
\opt{math-style}, but \cs{upGamma} and \cs{itGamma} will always give upright
or italic Gammas, respectively.

\paragraph{`Literal' interface}
Some may not like this convention of normalising their input.
For them, an upright |x| is an upright `x' and that's that.
(This will be the case when obtaining source text from copy/pasting PDF or
Microsoft Word documents, for example.)
For these users, the |literal| option to |math-style| will effect this behaviour.
The \cs{symliteral}\marg{syms} command can also be used, regardless of package setting, to force the style to match the literal input characters.
This is a `mirror' to \cs{symnormal}\marg{syms} (also alias \cs{mathnormal}) which `resets' the character mapping in its argument to that originally set up through package options.


\begin{table}
  \centering
  \topcaption{Effects of the \opt{math-style} package option.}
  \tablabel{math-style}
  \begin{tabular}{@{}>{\ttfamily}lcc@{}}
    \toprule
      & \multicolumn{2}{c}{Example} \\
       \cmidrule(l){2-3}
      \rmfamily Package option & Latin & Greek \\
    \midrule
      math-style=ISO & $(a,z,B,X)$ & $\symit{(\alpha,\beta,\Gamma,\Xi)}$ \\
      math-style=TeX & $(a,z,B,X)$ & $(\symit\alpha,\symit\beta,\symup\Gamma,\symup\Xi)$ \\
      math-style=french & $(a,z,\symup B,\symup X)$ & $(\symup\alpha,\symup\beta,\symup\Gamma,\symup\Xi)$ \\
      math-style=upright & $(\symup a,\symup z,\symup B,\symup X)$ & $(\symup\alpha,\symup\beta,\symup\Gamma,\symup\Xi)$ \\
    \bottomrule
  \end{tabular}
\end{table}

\paragraph{`Full-width' letters}
Unicode contains `full-width' versions of ASCII from \unichar{FF01}.
The numerals and latin letters in this range are defined by \pkg{unicode-math}
to map to their standard ASCII counterparts, which are then controlled by the relevant \opt{math-style} setting.
Other full-width symbols are not currently included but can be if there is sufficient need or desire.

\subsection{Bold style}
\seclabel{bold-style}

Similar as in the previous section, ISO standards differ somewhat to \TeX's
conventions (and classical typesetting) for `boldness' in mathematics. In
the past, it has been customary to use bold \emph{upright} letters to denote
things like vectors and matrices. For example, \( \symbfup{M} =
(\mitM_x,\mitM_y,\mitM_z) \). Presumably, this was due to the relatively
scarcity of bold italic fonts in the pre-digital typesetting era.
It has been suggested by some that \emph{italic} bold symbols should be used nowadays instead, but this practise is certainly not widespread.

Bold Greek letters have simply been bold variant glyphs of their regular
weight, as in \( \mbfitxi = (\mitxi_\mitr,\mitxi_\mitphi,\mitxi_\mittheta)
\).
Confusingly, the syntax in \LaTeX\ traditionally has been different for obtaining `normal' bold symbols in Latin and Greek: \cmd\mathbf\ in the former (`$\symbfup{M}$'), and \cmd\bm\ (or
\cmd\boldsymbol, deprecated) in the latter (`$\mbfitxi$').

In \pkg{unicode-math}, the \cmd\symbf\ command works directly with both
Greek and Latin maths characters and depending on package option
either switches to upright for Latin letters (|bold-style=TeX|) as well or
keeps them italic (|bold-style=ISO|).
To match the package options for non-bold characters, with option
|bold-style=upright| all bold characters are upright, and
|bold-style=literal| does not change the upright/italic shape of the letter.
The \opt{bold-style} options' effects are shown in brief in \tabref{bold-style}.

Upright and italic bold mathematical letters input as direct Unicode
characters are normalised with the same rules. For example, with
|bold-style=TeX|, a literal bold italic latin character will be typeset
upright.

Note that \opt{bold-style} is independent of \opt{math-style}, although if
the former is not specified then matching defaults are chosen based on the
latter.

\begin{table}
  \centering
  \topcaption{Effects of the \opt{bold-style} package option.}
  \tablabel{bold-style}
  \begin{tabular}{@{}>{\ttfamily}lcc@{}}
    \toprule
      & \multicolumn{2}{c}{Example} \\
       \cmidrule(l){2-3}
      \rmfamily Package option & Latin & Greek \\
    \midrule
      bold-style=ISO & $(\symbfit a, \symbfit z, \symbfit B, \symbfit X)$ & $(\symbfit\alpha, \symbfit\beta, \symbfit\Gamma, \symbfit\Xi)$ \\
      bold-style=TeX & $(\symbfup a,\symbfup z,\symbfup B,\symbfup X)$ & $(\symbfit\alpha, \symbfit\beta,\symbfup \Gamma,\symbfup \Xi)$ \\
      bold-style=upright & $(\symbfup a,\symbfup z,\symbfup B,\symbfup X)$ & $(\symbfup \alpha,\symbfup \beta,\symbfup \Gamma,\symbfup \Xi)$ \\
    \bottomrule
  \end{tabular}
\end{table}


\subsection{Sans serif style}
\seclabel{sans-style}

Unicode contains upright and italic, medium and bold mathematical style characters.
These may be explicitly selected with the \cs{symsfup}, \cs{symsfit}, \cs{symbfsfup}, and \cs{symbfsfit}
commands discussed in \secref{all-math-alphabets}.

How should the generic \cs{symsf} behave? Unlike bold, sans serif is used much more sparingly
in mathematics. I've seen recommendations to typeset tensors in sans serif italic
or sans serif italic bold (e.g., examples in the \pkg{isomath} and \pkg{mattens} packages).
But \LaTeX's \cs{mathsf} is \textsl{upright} sans serif.

Therefore, the package options |[sans-style=upright]| and |[sans-style=italic]| control the behaviour of \cs{symsf}.
The |upright| style sets up the command to use upright sans serif, including Greek;
the |italic| style switches to using italic in both Latin and Greek.
In other words, this option simply changes the meaning of \cs{symsf} to either \cs{symsfup} or \cs{symsfit}, respectively.
Please let me know if more granular control is necessary here.

There is also a |[sans-style=literal]| setting, set automatically with |[math-style=literal]|, which retains the uprightness of the input characters used when selecting the sans serif output.

\subsubsection{What about bold sans serif?}

While you might want your bold upright and your sans serif italic, I don't believe you'd also want your bold sans serif upright (etc.).
Therefore, bold sans serif follows from the setting for sans serif; it is completely independent of the setting for bold.

In other words, \cs{symbfsf} is either \cs{symbfsfup} or \cs{symbfsfit} based on |[sans-style=upright]| or |[sans-style=italic]|, respectively. And \texttt{[sans-style = literal]} causes \cs{symbfsf} to retain the same italic or upright shape as the input, and turns it bold sans serif.

N.B.: there is no medium-weight sans serif Greek range in Unicode.
Therefore, |\symsf{\alpha}| does not make sense (it produces `$\symsf{\alpha}$'), while |\symbfsf{\alpha}| gives `$\symbfsfup{\alpha}$' or `$\symbfsfit{\alpha}$' according to the |sans-style|.

\subsection{All (the rest) of the mathematical styles}
\seclabel{all-math-alphabets}

Unicode contains separate codepoints for most if not all variations of style
shape one may wish to use in mathematical notation. The complete list is shown
in \tabref{mathalphabets}. Some of these have been covered in the previous sections.

The math font switching commands do not nest; therefore if you want
sans serif bold, you must write |\symbfsf{...}| rather than |\symbf{\symsf{...}}|.
This may change in the future.

\begin{table}
\caption{Mathematical styles defined in Unicode. Closed dots indicate an style exists in the font specified; open dots indicate shapes that should always be taken from the upright font even in the italic style. See main text for description of \cs{mathbbit}.}
\tablabel{mathalphabets}
\centering
\def\Y{\textbullet}
\def\M{\textopenbullet}
\begin{tabular}{@{} lll l ccc @{}}
\toprule
\multicolumn{3}{c}{Font} & & \multicolumn{3}{c}{Alphabet} \\
\cmidrule(r){1-3}
\cmidrule(l){5-7}
Style & Shape & Series & Switch & Latin & Greek & Numerals \\
\midrule
Serif      & Upright & Normal & \cs{symup}     & \Y & \Y & \Y  \\
           &         & Bold   & \cs{symbfup}   & \Y & \Y & \Y  \\
           & Italic  & Normal & \cs{symit}     & \Y & \Y & \M  \\
           &         & Bold   & \cs{symbfit}   & \Y & \Y & \M  \\
Sans serif & Upright & Normal & \cs{symsfup}   & \Y &    & \Y  \\
           &         & Bold   & \cs{symbfsfup} & \Y & \Y & \Y  \\
           & Italic  & Normal & \cs{symsfit}   & \Y &    & \M  \\
           &         & Bold   & \cs{symbfsfit} & \Y & \Y & \M  \\
Typewriter & Upright & Normal & \cs{symtt}     & \Y &    & \Y  \\
Double-struck & Upright & Normal & \cs{symbb}     & \Y &    & \Y  \\
              & Italic  & Normal & \cs{symbbit}   & \Y &    &  \\
Script     & Upright & Normal & \cs{symscr}    & \Y &    &     \\
           &         & Bold   & \cs{symbfscr}  & \Y &    &     \\
Fraktur    & Upright & Normal & \cs{symfrak}   & \Y &    &     \\
           &         & Bold   & \cs{symbffrak} & \Y &    &     \\
\bottomrule
\end{tabular}
\end{table}

\subsubsection{Scope of the functionality of the \cs{sym..} commands}

The \cs{sym..} commands are designed to affect only the following sets of input letters: numerals ($0$--$9$), Latin ($a$--$z$, $A$--$Z$), Greek ($\alpha$--$\omega$, $\Alpha$--$\Omega$,), and the \cs{partial} and \cs{nabla} symbols ($\partial$, $\nabla$).
These are the only symbols for which Unicode defines separate codepoints with varying mathematical style.

There is currently no scope for including other symbols in the \cs{sym..} commands, such as writing |\symbf{\int}| for a bold integral symbol.
Therefore the commands provided by \pkg{unicode-math} should not be compared to those provided by the \pkg{bm} package.

\subsubsection{Double-struck}

The double-struck style (also known as `blackboard bold') consists of
upright Latin letters $\{\symbb{a}$--$\symbb{z}$,$\symbb{A}$$\symbb{Z}\}$,
numerals $\symbb{0}$--$\symbb{9}$, summation symbol $\symbb\sum$, and four
Greek letters only: $\{\symbb{\gamma\pi\Gamma\Pi}\}$.

While |\symbb{\sum}| does produce a double-struck summation symbol,
its limits aren't properly aligned. Therefore,
either the literal character or the control sequence \cs{Bbbsum} are
recommended instead.

There are also five Latin \emph{italic} double-struck letters: $\symbbit{Ddeij}$.
These can be accessed (if not with their literal characters or control sequences)
with the \cs{mathbbit} style switch, but note that only those five letters
will give the expected output.

\subsubsection{Calligraphic vs.\ Script variants}

The Unicode maths encoding contains a style for `Script' letters,
and while by default \cs{symcal} and \cs{symscr}
are synonyms, there are some situations when a
separate `Calligraphic' style is needed as well.

If a font contains alternate glyphs for a separate calligraphic style,
they can be selected explicitly. For example the STIX~Two~Math font
uses the the first stylistic set feature (|ss01|) to map the script
letters to the calligraphic letters.
\begin{Verbatim}
\setmathfont{STIXTwoMath-Regular.otf}
\setmathfont{STIXTwoMath-Regular.otf}[range={cal, bfcal}, StylisticSet=1]
\end{Verbatim}
With the above we can now write
\begin{quote}
\setmathfont{STIXTwoMath-Regular.otf}
\setmathfont{STIXTwoMath-Regular.otf}[range={cal, bfcal}, StylisticSet=1]
|$\symscr{ABCDabcd}$| to get $\symscr{ABCDabcd}$ \\
|$\symcal{ABCDabcd}$| to get $\symcal{ABCDabcd}$
\end{quote}

\subsection{Miscellanea}

\subsubsection{Nabla}
\seclabel{nabla}

 The symbol $\nabla$ comes in the six forms shown in \tabref{nabla}.
 We want an individual option to specify whether we want upright or italic
 nabla by default (when either upright or italic nabla is used in the
 source). \TeX\ classically uses an upright nabla, and \textsc{iso}
 standards agree with this convention.
 The package options |nabla=upright| (default) and
 |nabla=italic| switch between the two choices, and |nabla=literal| respects
 the shape of the input character.
|nabla=literal| is activated automatically after |math-style=literal|.

These settings are then inherited through \cmd\symbf; \cmd\symit\ and \cmd\symup\ can be used to force the shape of the nabla one way or the other.


\begin{table}
  \begin{minipage}[b]{0.49\textwidth}
  \centering
  \topcaption{The various forms of nabla.}
  \tablabel{nabla}
  \let \tmpshow\empty
  \begin{tabular}{@{}llc@{}}
    \toprule
    \multicolumn{2}{@{}l}{Description} & Glyph \\
    \cmidrule(r){1-2}\cmidrule(l){3-3}
    Upright & Serif      & $\symup\nabla$     \\
            & Bold serif & $\symbfup\nabla$   \\
            & Bold sans  & $\symbfsfup\nabla$ \\
    \cmidrule(lr){1-2}\cmidrule(lr){3-3}
    Italic & Serif       & $\symit\nabla$     \\
           & Bold serif  & $\symbfit\nabla$   \\
           & Bold sans   & $\symbfsfit\nabla$ \\
    \bottomrule
  \end{tabular}
  \end{minipage}\hfill
  \begin{minipage}[b]{0.49\textwidth}
  \centering
  \topcaption{The partial differential.}
  \tablabel{partial}
  \begin{tabular}{@{}llc@{}}
    \toprule
    \multicolumn{2}{@{}l}{Description} & Glyph \\
    \cmidrule(r){1-2}\cmidrule(l){3-3}
    Regular   & Upright & $\symup\partial$     \\
              & Italic  & $\symit\partial$     \\
    Bold      & Upright & $\symbfup\partial$   \\
              & Italic  & $\symbfit\partial$   \\
    Sans bold & Upright & $\symbfsfup\partial$ \\
              & Italic  & $\symbfsfit\partial$ \\
    \bottomrule
  \end{tabular}
  \end{minipage}
\end{table}


\subsubsection{Partial}
\seclabel{partial}

The same logic as for nabla applies to the symbols \unichar{2202} partial differential and \unichar{1D715} math italic partial differential.
However, in practice these symbols are often designed identically in an italic style.

If the font you are using supports it, use the |partial=upright| or |partial=italic| (default) package options to specify
which one you would like, or |partial=literal| to have the same character
used in the output as was used for the input.
|partial=literal| is activated following |math-style=literal|.

See \tabref{partial} for the variations on the partial differential symbol.


\subsubsection{Primes}

Primes ($x'$) may be input in several ways. You may use any combination
the \ascii\ straight quote (\texttt{\char`\'}) or the Unicode prime \unichar{2032}
($'$); when multiple primes occur next to each other, they chain
together to form double, triple, or quadruple primes if the font contains
pre-drawn glyphs. The individual prime glyphs are accessed, as usual,
with the \cs{prime} command, and the double-, triple-, and quadruple-prime
glyphs are available with \cs{dprime}, \cs{trprime}, and \cs{qprime},
respectively.

If the font does not contain the pre-drawn glyphs or more than four primes
are used, the single prime glyph is used multiple times with a negative
kern to get the spacing right. There is no user interface to adjust this
negative kern yet (because I haven't decided what it should look like);
if you need to, write something like this:
\begin{Verbatim}
\ExplSyntaxOn
\muskip_gset:Nn \g_@@_primekern_muskip { -\thinmuskip/2 }
\ExplySyntaxOff
\end{Verbatim}
Backwards or reverse primes behave in exactly the same way; use the \ascii\
back tick (\texttt{\char`\`}) or the Unicode reverse prime \unichar{2035}
({\umfont\char"2035}).
The command to access the backprime is \cs{backprime}, and
multiple backwards primes can accessed with \cs{backdprime},
\cs{backtrprime}, and \cs{backqprime}.

In all cases above, no error checking is performed if you attempt to
access a multi-prime glyph in a font that doesn't contain one. For this
reason, it may be safer to write |x''''| instead of |x\qprime|
in general.

If you ever need to enter the straight quote |'| or the backtick |`| in
maths mode, these glyphs can be accessed with \cs{mathstraightquote} and
\cs{mathbacktick}.

\subsubsection{Subscripts and superscripts and symbol alphabets}

In traditional \LaTeX, users have for many years exploited a loophole in the implementation
of |\mathrm| and similar to write expressions such as |x_\mathrm f| to achieve
$x_{\mathrm{f}}$ instead of writing the more correct |x_{\mathrm{f}}|.
Shorthand notation such as |x_\mathrm f| is not officially documented \LaTeX\ syntax,
and due to a particular implementation detail in \pkg{unicode-math} this \emph{incorrect}
syntax is no longer supported.


\subsubsection{Unicode subscripts and superscripts}

You may, if you wish, use Unicode subscripts and superscripts in your
source document. For basic expressions, the use of these characters
can make the input more readable.
Adjacent sub- or super-scripts will be concatenated into a single
expression.

The range of subscripts and superscripts supported by this package
are shown in \figref{superscripts,subscripts}. Please request more if
you think it is appropriate.

\begin{figure}\centering
\fbox{\fontspec{DejaVuSerif.ttf}\Large
A
^^^^2070 ^^^^00b9 ^^^^00b2 ^^^^00b3 ^^^^2074 ^^^^2075 ^^^^2076 ^^^^2077
^^^^2078 ^^^^2079 ^^^^207a ^^^^207b ^^^^207c ^^^^207d ^^^^207e ^^^^2071
^^^^207f ^^^^207f ^^^^02b0 ^^^^02b2 ^^^^02b3 ^^^^02b7 ^^^^02b8
Z}
\caption{
  The Unicode superscripts supported as input characters.
  These are the literal glyphs from the `DejaVu Serif' font,
  not the output seen when used for maths input.
  The `A' and `Z' are to provide context for the size and
  location of the superscript glyphs.
}
\figlabel{superscripts}
\end{figure}

\begin{figure}\centering
\fbox{\fontspec{DejaVuSerif.ttf}\Large
A
^^^^2080 ^^^^2081 ^^^^2082 ^^^^2083 ^^^^2084 ^^^^2085 ^^^^2086 ^^^^2087
^^^^2088 ^^^^2089 ^^^^208a ^^^^208b ^^^^208c ^^^^208d ^^^^208e ^^^^2090
^^^^2091 ^^^^1d62 ^^^^2092 ^^^^1d63 ^^^^1d64 ^^^^1d65 ^^^^2093 ^^^^1d66
^^^^1d67 ^^^^1d68 ^^^^1d69 ^^^^1d6a
Z}
\caption{
  The Unicode subscripts supported as input characters.
  See note from \figref{superscripts}.
}
\figlabel{subscripts}
\end{figure}

\subsubsection{Colon}
\seclabel{colon}

The colon is one of the few confusing characters of Unicode maths.
In \TeX, \texttt{:} is defined as a colon with relation spacing: `$a:b$'.
While \cs{colon} is defined as a colon with punctuation spacing: `$a\colon b$'.

In Unicode, \unichar{003A} {colon} is defined as a punctuation symbol,
while \unichar{2236} {ratio} is the colon-like symbol used in mathematics to denote
ratios and other things.

This breaks the usual straightforward mapping from control sequence to Unicode input character
to (the same) Unicode glyph.

To preserve input compatibility, we remap the \ascii\ input character `\texttt{:}' to \unichar{2236}.
Typing a literal \unichar{2236} char will result in the same output.

The package option |colon=literal| forces \ascii\ input `|:|' to be printed as \cs{mathcolon} instead.


\subsubsection{Slashes and backslashes}
\seclabel{slash-delimiter}

There are several slash-like symbols defined in Unicode.
The complete list is shown in \tabref{slashes}. Unfortunately, font support for these characters/glyphs is rather inconsistent.
Note that \cs{slash} internally uses the \cs{mathslash} mathematical character.
The wrapper \cs{slash} is defined to work correctly in both text and maths mode, as well as in contexts where the slash is acting like a delimiter, such as \verb|\left< a \middle\slash b \right>|.

\begin{table}\centering
\topcaption{Slashes and backslashes.}
\tablabel{slashes}
\begin{tabular}{@{}cl@{}cll@{}}
\toprule
Slot & Name & Glyph & Class & Command  \\
\midrule
\unichar{002F} & \textsc{solidus}                 & \umfont \char"002F & \cs{mathord} & \cs{slash} \\
\unichar{27CB} & \textsc{rising diagonal}         & \umfont \char"27CB & \cs{mathord} & \cs{diagup} \\
\unichar{2044} & \textsc{fraction slash}          & \umfont \char"2044 & \cs{mathbin} & \cs{fracslash} \\
\unichar{2215} & \textsc{division slash}          & \umfont \char"2215 & \cs{mathbin} & \cs{divslash} \\
\unichar{29F8} & \textsc{big solidus}             & \umfont \char"29F8 & \cs{mathop}  & \cs{xsol} \\
\midrule
\unichar{005C} & \textsc{reverse solidus}         & \umfont \char"005C & \cs{mathord} & \cs{backslash} \\
\unichar{27CD} & \textsc{falling diagonal}        & \umfont \char"27CD & \cs{mathord} & \cs{diagdown} \\
\unichar{2216} & \textsc{set minus}               & \umfont \char"2216 & \cs{mathbin} & \cs{setminus} \\
 & \textsc{small set minus}               &  & \cs{mathbin} & \cs{smallsetminus} \\
\unichar{29F5} & \textsc{reverse solidus operator}& \umfont \char"29F5 & \cs{mathbin} & \cs{reversesolidus} \\
\unichar{29F9} & \textsc{big reverse solidus}     & \umfont \char"29F9 & \cs{mathop}  & \cs{xbsol} \\
\bottomrule
\end{tabular}
\end{table}

\paragraph{Slashes}

Of \unichar{2044} {fraction slash}, TR25 says that it is:
\begin{quote}
\dots used to build up simple fractions in running text\dots
however parsers of mathematical texts should be prepared to handle fraction slash
when it is received from other sources.
\end{quote}

\unichar{2215} {division slash} should be used when division is represented
without a built-up fraction; $\pi\approx22/7$, for example.

\unichar{29F8} {big solidus} is a `big operator' (like $\sum$).

\cs{diagup} and \cs{diagdown} are defined with math class \cs{mathord} for consistency with \pkg{amssymb}.
This definition is inconsistent with MathML, which would use \cs{mathrel} instead.

\paragraph{Backslashes}

Of the five backslash characters shown in \tabref{slashes}, only \cs{backslash} and \cs{setminus} are defined consistently across all OpenType math fonts.
(The two glyphs are typically identical, or close to it, with the main difference between them the spacing defined by their math class.)

The \unichar{005C} {reverse solidus} character \cs{backslash} is used for denoting
double cosets: $A\backslash B$. It may be used as a `stretchy' delimiter if supported by the font.

The \unichar{2216} {set minus} character \cs{setminus} defines the relative complement or set difference between two sets: $A\setminus B$.

Presumably, \unichar{29F5} {reverse solidus operator} is intended to
be used in a similar way, but it could also be used to
represent `inverse division': $\pi\approx7\mathbin{\backslash}22$.^^A
\footnote{This is valid syntax in the Octave and Matlab programming languages,
in which it means matrix inverse pre-multiplication. I.e., $A\mathbin{\backslash} B\equiv A^{-1}B$.}

Finally, \unichar{29F9} {big reverse solidus} is a `big operator' (like $\sum$).

\paragraph{Slashes as `delimiters'}

In regular \LaTeX\ we can write \cs{left}\cs{slash}\dots\cs{right}\cs{backslash}
and so on and obtain extensible delimiter-like symbols. Not all of the Unicode slashes
are suitable for this (and do not have the font support to do it).

In Cambria Math, the only slash that grows (say when writing
\[
\left.\left[\begin{array}{cc} a & b \\ c & d\end{array}\right]\middle\slash
      \left[\begin{array}{cc} 1 & 1 \\ 1 & 0\end{array}\right] \right.\quad )
\]
is the \textsc{fraction slash}, which we just established above is
sort of only supposed to be used in text.

Of the slashes, the following commands are the only ones defined to be able to be used as stretchable delimiters after
\cs{left}, \cs{middle}, and \cs{right}:
\begin{itemize}
\item \cs{fracslash};
\item \cs{slash}; and,
\item \cs{backslash} (the only reverse slash).
\end{itemize}

However, for the purpose of implementing this markup, we assume that there is only \emph{one} stretchy slash
in the font; this is assumed by default to be \unichar{002F} {solidus}.
Writing \cs{left/} or \cs{left}\cs{slash} or \cs{left}\cs{fracslash}
will all result in the same stretchy delimiter being used.
The delimiter used can be changed with the |slash-delimiter| package option.
Allowed values are |ascii|, |frac|, and |div|, corresponding to the respective
Unicode slots.

For example: as mentioned above, Cambria Math's stretchy slash is
\unichar{2044} {fraction slash}. When using Cambria Math, then
\pkg{unicode-math} should be loaded with the |slash-delimiter=frac| option.
(This should really be a font option rather than a package option, but this option should only be needed infrequently.)

\paragraph{Set minus characters/glyphs}

Standard \LaTeX\ plus \pkg{amssymb} defines two commands \cs{setminus} and \cs{smallsetminus}.
This package now defines \cs{setminus} to correspond to the Unicode slot \unichar{2216}.
Some fonts may provide smaller sized glyphs either through character variants, private use area encoding, or via one of the less-common backslash slots (covered above).
Since there is currently no consistency in how modern OpenType fonts would access a smaller variant for `set minus', this package simply defines \cs{smallsetminus} to be a constructed glyph, composed of a rotated and shifted minus sign with appropriate \cs{mathbin} spacing.

If variations to this setup are needed, users can redefine the commands to their liking; e.g.:
\begin{verbatim}
    \setmathfont{XITSMath-Regular.otf}
    \AtBeginDocument{
      \let\smallsetminus\setminus
      \let\setminus\reversesolidus
    }
\end{verbatim}


\subsubsection{Behaviour of hyphens in mathematics}
\seclabel{hyphen}

Unicode defines the following related characters:
\begin{itemize}
\item \unichar{0002D}{hyphen-minus}
\item \unichar{02212}{minus sign}
\item \unichar{02010}{hyphen} (\cs{mathhyphen})
\end{itemize}
The first two of these characters in the input will all behave as the binary operator
`minus sign'.
The third is defined by \pkg{unicode-math} as a `math letter' for constructions
like \verb|$R‐\text{Mod}$| ($R‐\text{Mod}$).
If more control is needed surrounding these symbols, additional options can be added to the package;
please get in touch if this is the case for you.


\subsubsection{Growing and non-growing accents}
\seclabel{growing-accents}

There are a few accents for which \TeX\ has both non-growing and growing
versions.  Among these are \cs{hat} and \cs{tilde}; the corresponding growing
versions are called \cs{widehat} and \cs{widetilde}, respectively.

Older versions of \XeTeX\ and \LuaTeX\ did not support this distinction,
however, and \emph{all} accents there were growing automatically. (I.e.,
\cs{hat} and \cs{widehat} are equivalent.) As of \LuaTeX\ v0.65 and \XeTeX\
v0.9998, these wide/non-wide commands will again behave in their expected
manner.


\subsubsection{Negations and the \cs{not} command}
\seclabel{negations}

The \cs{not} command in classic \LaTeXe\ was a mathematical slash modifying glyph that allowed for `negating` maths symbols where pre-built glyphs were not available. While Unicode encodes a slot for this modifying slash, it is only well-supported in \LuaTeX\ and not in \XeTeX.

To provide more flexibility, the \pkg{unicode-math} package defines \cs{not} to search for a predefined `negated' definitions for its argument and use that if available. This method can be used for fine-tuning in cases where spacing needs to be adjusted.

A `negated definition` is any symbol command prefixed by either \verb|n| or \verb|not|. For example, \pkg{unicode-math} by default defines both \cs{leftarrow} ($\leftarrow$) and \cs{nleftarrow} ($\nleftarrow$).

To define custom negated definitions for either symbols (e.g., \verb|\not=|) or commands (e.g., \verb|\not\equal|), use the \cs{NewNotCommand}\marg{symbol or cmd}\marg{definition} command. Its usage is as follows:
\begin{verbatim}
\NewNegationCommand {=} {\neq}
\NewNegationCommand {\equal} {\neq}
\end{verbatim}
If the command has already been defined, an error will result and \verb|\RenewNegationCommand| can be used to overwrite the original definition.


\subsubsection{Pre-drawn fraction characters}

Pre-drawn fractions \unichar{00BC}--\unichar{00BE}, \unichar{2150}--\unichar{215E}
are not suitable for use in mathematics output. However, they can be useful
as input characters to abbreviate common fractions.
\begin{center}
\fontspec{DejaVuSerif.ttf} ^^A available in TeX Live 2012 if not earlier
¼ ½ ¾  ↉ ⅐ ⅑ ⅒ ⅓ ⅔ ⅕ ⅖ ⅗ ⅘ ⅙ ⅚ ⅛ ⅜ ⅝ ⅞
\end{center}
For example, instead of writing `|\tfrac12 x|', you may consider it more readable to have
`|½x|' in the source instead.

By default, the \cs{tfrac} command will be used to typeset the fractions.
The command to use (\cs{tfrac} or \cs{frac}) can be forced with the package
option |active-frac=small| or |active-frac=normalsize|, respectively.

\subsubsection{Circles}

Unicode defines a large number of different types of circles for a variety
of mathematical purposes. There are thirteen alone just considering the
all white and all black ones, shown in \tabref{circles}.

\LaTeX\ defines considerably fewer: \cs{circ} and \cs{bigcirc} for white;
\cs{bullet} for black. This package maps those commands to \cs{vysmwhtcircle},
\cs{mdlgwhtcircle}, and \cs{smblkcircle}, respectively.

\begin{table}\centering
\def\showchar#1#2#3{ \textsc{u}+{\small\ttfamily #1} & \texttt{\string#3} & \umfont \char"#1 \\}
\begin{tabular}{@{}llc@{}}
\toprule
Slot & Command & Glyph \\
\midrule
\showchar{00B7}{centerdot}{\cdotp}
\showchar{22C5}{small middle dot}{\cdot}
\showchar{2219}{bullet operator}{\vysmblkcircle}
\showchar{2022}{round bullet, filled}{\smblkcircle}
\showchar{2981}{z notation spot}{\mdsmblkcircle}
\showchar{26AB}{medium black circle}{\mdblkcircle}
\showchar{25CF}{circle, filled}{\mdlgblkcircle}
\showchar{2B24}{black large circle}{\lgblkcircle}
\bottomrule
\end{tabular}
\def\showchar#1#2#3{ \umfont \char"#1 & \texttt{\string#3} & \textsc{u}+{\small\ttfamily #1} \\}
\begin{tabular}{@{}cll@{}}
\toprule
Glyph & Command & Slot \\
\midrule
\\
\\
\showchar{2218}{composite function (small circle)}{\vysmwhtcircle}
\showchar{25E6}{white bullet}{\smwhtcircle}
\showchar{26AC}{medium small white circle}{\mdsmwhtcircle}
\showchar{26AA}{medium white circle}{\mdwhtcircle}
\showchar{25CB}{large circle}{\mdlgwhtcircle}
\showchar{25EF}{large circle}{\lgwhtcircle}
\bottomrule
\end{tabular}
\caption{Filled and hollow Unicode circles.}
\tablabel{circles}
\end{table}

\subsubsection{Triangles}

While there aren't as many different sizes of triangle as there are circle,
there's some important distinctions to make between a few similar characters. See \tabref{uptriangles} for the full summary.

These triangles all have different intended meanings. Note for backwards
compatibility with \TeX, \unichar{25B3} has \emph{two} different mappings
in \pkg{unicode-math}. \cs{bigtriangleup} is intended as a binary operator
whereas \cs{triangle} is intended to be used as a letter-like symbol.

But you're better off if you're using the latter form to indicate an
increment to use the glyph intended for this purpose, \unichar{2206}: $\increment x$.

Finally, given that $\triangle$ and $\increment$ are provided for you
already, it is better off to only use upright Greek Delta $\Delta$ if you're
actually using it as a symbolic entity such as a variable on its own.

\begin{table}\centering
\begin{tabular}{@{}llcl@{}}
\toprule
Slot & Command & Glyph & Class \\
\midrule
\unichar{25B5} & \cs{vartriangle}      & \umfont \char"25B5 & binary \\
\unichar{25B3} & \cs{bigtriangleup}    & \umfont \char"25B3 & binary \\
\unichar{25B3} & \cs{triangle}         & \umfont \char"25B3 & ordinary \\
\unichar{2206} & \cs{increment}        & \umfont \char"2206 & ordinary \\
\unichar{0394} & \cs{mathup}\cs{Delta} & \umfont \char"0394 & ordinary \\
\bottomrule
\end{tabular}
\caption{Different upwards pointing triangles.}
\tablabel{uptriangles}
\end{table}

\iffalse
\subsubsection{Normalising some input characters}

I believe
all variant forms should be used as legal input that is normalised to
a consistent output glyph, because we want to be fault-tolerant in the input.
Here are the duplicates:
\begin{quote}\obeylines
\unichar {251} {latin small letter alpha}
\unichar {25B} {latin small letter epsilon}
\unichar {263} {latin small letter gamma}
\unichar {269} {latin small letter iota}
\unichar {278} {latin small letter phi}
\unichar {28A} {latin small letter upsilon}
\unichar {190} {latin capital letter epsilon}
\unichar {194} {latin capital letter gamma}
\unichar {196} {latin capital letter iota}
\unichar {1B1} {latin capital letter upsilon}
\end{quote}

(Not yet implemented.)
\fi

\section{Advanced}

\subsection{Warning messages}

This package can produce a number of informational messages to try and inform the user when something might be going wrong due to package conflicts or something else.
As an experimental feature, these can be turn off on an individual basis with the package option |warnings-off| which takes a comma-separated list of warnings to suppress.
A warning will give you its name when printed on the console output; e.g.,
\begin{Verbatim}
  * unicode-math warning: "mathtools-colon"
  *
  * ... <warning message> ...
\end{Verbatim}
This warning could be suppressed by loading the package as follows:
\begin{Verbatim}
  \usepackage[warnings-off={mathtools-colon}]{unicode-math}
\end{Verbatim}

\subsection{How to overwrite a macro}

\pkg{unicode-math} defines the macros by \cs{AtBeginDocument},
namely delays the definition until |\begin{document}| is met.
If you want to overwrite a macro defined by \pkg{unicode-math},
please redefine it in \cs{AtBeginDocument} after loading this package.

\subsection{Programmer's interface}

(Tentative and under construction.)
If you are writing some code that needs to know the current
maths style (\cs{mathbf}, \cs{mathit}, etc.), you can query the
variable \cs{l_@@_mathstyle_tl}. It will contain the maths style
without the leading `math' string; for example,
|\symbf { \show \l_@@_mathstyle_tl }|
will produce `bf'.

\endinput

% /©
%
% ------------------------------------------------
% The UNICODE-MATH package  <wspr.io/unicode-math>
% ------------------------------------------------
% 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): <http://www.latex-project.org/lppl/>.
% ------------------------------------------------
% Copyright 2006-2019  Will Robertson, LPPL "maintainer"
% Copyright 2010-2017  Philipp Stephani
% Copyright 2011-2017  Joseph Wright
% Copyright 2012-2015  Khaled Hosny
% ------------------------------------------------
%
% ©/
