Debian Codegraph @

texmf-dist/doc/latex/unicode-math/um-doc-main.tex

raw
1 %%^^A%% um-doc-main.tex -- part of UNICODE-MATH <wspr.io/unicode-math>
2
3 \begin{abstract}
4 \noindent
5 This document describes the \pkg{unicode-math} package, which is
6 intended as an implementation of Unicode
7 maths for \LaTeX\ using the \XeTeX\ and Lua\TeX\ typesetting engines.
8 With this package, changing maths fonts is as easy as changing
9 text fonts --- and there are more and more maths fonts appearing now.
10 Maths input can also be simplified with Unicode since literal glyphs may be
11 entered instead of control sequences in your document source.
12
13 The package provides support for both \XeTeX\ and Lua\TeX. The different
14 engines provide differing levels of support for Unicode maths.
15 Please let us know of any troubles.
16
17 Alongside this documentation file, you should be able to find a minimal
18 example demonstrating the use of the package,
19 `\texttt{unimath-example.ltx}'. It also comes with a separate document,
20 `\texttt{unimath-symbols.pdf}',
21 containing a complete listing of mathematical symbols defined by
22 \pkg{unicode-math}, including comparisons between different fonts.
23
24 Finally, while the STIX fonts may be used with this package, accessing
25 their alphabets in their `private user area' is not yet supported.
26 (Of these additional alphabets there is a separate calligraphic design
27 distinct to the script design already included.)
28 Better support for the STIX fonts is planned for an upcoming revision of the
29 package after any problems have been ironed out with the initial version.
30
31 \end{abstract}
32
33 \newpage
34 \tableofcontents
35
36 \clearpage
37 \section{Introduction}
38
39 This document describes the \pkg{unicode-math} package, which is an
40 \emph{experimental} implementation of a macro to Unicode glyph encoding for
41 mathematical characters.
42
43 Users who desire to specify maths alphabets only (Greek and Latin letters,
44 and Arabic numerals)
45 may wish to use Andrew Moschou's \pkg{mathspec} package instead.
46 (\XeTeX-only at time of writing.)
47 Note that \pkg{unicode-math} and \pkg{mathspec} are not compatible with each other.
48
49 \section{Acknowledgements}
50
51 Many thanks to:
52 Microsoft for developing the mathematics extension to OpenType as part of
53 Microsoft Office~2007;
54 Jonathan Kew for implementing Unicode math support in \XeTeX;
55 Taco Hoekwater for implementing Unicode math support in \LuaTeX;
56 Barbara Beeton for her prodigious effort compiling the definitive list of Unicode math
57 glyphs and their \LaTeX\ names (inventing them where necessary), and also
58 for her thoughtful replies to my sometimes incessant questions;
59 Philipp Stephani for extending the package to support \LuaTeX.
60 Ross Moore and Chris Rowley have provided moral and technical support
61 from the very early days with great insight into the issues we face trying
62 to extend and use \TeX\ in the future.
63 Apostolos Syropoulos, Joel Salomon, Khaled Hosny, and Mariusz Wodzicki
64 have been fantastic beta testers.
65
66 \section{Getting started}
67
68 Load \pkg{unicode-math} as a regular \LaTeX\ package.
69 It should be loaded after any other maths or font-related package in case it needs to overwrite their definitions.
70 It requires \pkg{amsmath}, which it will automatically load if the user hasn't already done so.
71 Here's an example using the filename syntax to load the \TeX\ Gyre Pagella Math font: (this works for both \XeLaTeX\ and \LuaLaTeX)
72 \begin{Verbatim}
73 \usepackage{amsmath}
74 \usepackage{unicode-math}
75 \setmathfont{texgyrepagella-math.otf}
76 \end{Verbatim}
77
78 Once the package is loaded, traditional TFM-based maths fonts are no longer supported;
79 you can only switch to a different OpenType maths font using the \cs{setmathfont} command.
80 If you do not load an OpenType maths font before |\begin{document}|, Latin Modern Math will be loaded automatically.
81
82
83 \subsection{New commands}
84 \LaTeX, since the first version of \LaTeXe, changed the math group
85 selection from, say, |{\bf x}| to |\mathbf{x}|. It introduced commands
86 such as |\mathbf|, |\mathit|, |\mathsf|, |\mathtt| and |\mathcal|,
87 besides |\mathnormal|. This was not only done to maintain the analogy
88 with |\textbf|, |\textit| and so on, but with the precise purpose of
89 loading the needed math groups (or math families) on demand and not
90 allocating them if not required by the document.
91
92 The introduction of \pkg{unicode-math} posed some problems fitting into this design. For
93 instance, there is a big difference between say |fit| as an operator
94 name in boldface type and the product of three boldface variables.
95 With legacy \TeX{} engines, |\mathbf{fit}| would use a ligature and
96 the same would happen with the input |\mathbf{f}\mathbf{i}\mathbf{t}|.
97 For the latter case, the user should probably use |\mathbf{f\/}|.
98
99 However, there is another important point from a \emph{conceptual}
100 point of view. A boldface variable name should be printed using the
101 \emph{math font}, whereas a boldface operator name should be printed
102 using the \emph{text font}. OpenType math fonts make this distinction
103 feasible, because they contain several math alphabets. Of course a
104 boldface text~`x' will not differ much (or at all) from a boldface
105 math~`x', but this is not the point: they \emph{should} be considered
106 different, because the former is |U+0078| in Unicode, the latter is
107 |U+1D431|.
108
109 It was clear that \emph{two} different commands are needed: one for using text boldface in math,
110 one for using math boldface. Only the document's author can know
111 whether one or the other is needed. The decision was to split off
112 the two meanings with a command like |\mathbf| for the boldface text font
113 in math and a command like |\symbf| (for the bold math font).
114
115 The five new symbol font commands that behave in this way are: \cs{symup},
116 \cs{symit}, \cs{symbf}, \cs{symsf}, and \cs{symtt}.
117 These commands switch to single-letter mathematical symbols
118 (generally within the same OpenType font).
119
120 The legacy \cs{math..} commands switch to text fonts that are set up to behave
121 correctly in mathematics, and should be used for multi-letter identifiers. These
122 could be denoted `text math alphabets'; further details are discussed
123 in \secref{mathselect}. Additional similar `text math alphabet'
124 commands can be defined using the \cs{setmathfontface} command
125 discussed in \secref{mathselect}. To control the behaviour of the
126 default text math alphabet commands to behave in a
127 backwards-compatible mode, see the package options described in
128 \secref{textmathlegacy}.
129
130
131 \begin{table}[t!]
132 \topcaption{New \pkg{unicode-math} commands which overlap with legacy
133 math commands. For new documents the \texttt{sym} versions are recommended.}
134 \tablabel{symvsmath}
135 \centering
136 \begin{tabular}[t]{ll}
137 \toprule
138 Command & Synonym \\
139 \midrule
140 \cs{symnormal} & \cs{mathnormal} \\
141 \cs{symliteral} & \\
142 & \\
143 & \\
144 & \\
145 \cs{symbb} & \cs{mathbb} \\
146 \cs{symbbit} & \cs{mathbbit} \\
147 \cs{symcal} & \cs{mathcal} \\
148 \cs{symscr} & \cs{mathscr} \\
149 \cs{symfrak} & \cs{mathfrak} \\
150 \cs{symsfup} & \cs{mathsfup} \\
151 \cs{symsfit} & \cs{mathsfit} \\
152 \bottomrule
153 \end{tabular}\qquad
154 \begin{tabular}[t]{ll}
155 \toprule
156 Command & Synonym \\
157 \midrule
158 & \\
159 & \\
160 \cs{symbfsf} & \cs{mathbfsf} \\
161 \cs{symbfup} & \cs{mathbfup} \\
162 \cs{symbfit} & \cs{mathbfit} \\
163 & \\
164 & \\
165 \cs{symbfcal} & \cs{mathbfcal} \\
166 \cs{symbfscr} & \cs{mathbfscr} \\
167 \cs{symbffrak} & \cs{mathbffrak} \\
168 \cs{symbfsfup} & \cs{mathbfsfup} \\
169 \cs{symbfsfit} & \cs{mathbfsfit} \\
170 \bottomrule
171 \end{tabular}
172 \end{table}
173
174 In addition, \pkg{unicode-math} also provides a number of commands (such as
175 |\symcal|) to select specific `symbol alphabets' within the unicode
176 maths font, with usage, e.g., |$\symcal{G}$|${}\to\symcal{G}$. The
177 full listing is shown in \Tabref{symvsmath}. For backwards
178 compatibility, many of these are also defined with `familiar' synonyms
179 such as |\mathcal|. However, where possible the `sym' prefix
180 commands should be preferred, as certain synonyms may become
181 deprecated in time. The |\symliteral| command is described in
182 \secref{math-style}.
183
184 Using the |\sym..| commands, the glyphs used to produce PDF output are Unicode-encoded,
185 and therefore a symbol such as $\symcal{G}$ can be copy-pasted into another programme
186 (or even into the source of another \LaTeX\ document using \pkg{unicode-math}) without
187 loss of meaning.
188 This is an important aspect of Unicode mathematics, but the \pkg{unicode-math} package
189 is not `pure' in the sense that the package also provides other mechanisms to change
190 the fonts used in the PDF output; the philosophy of the package is to provide mechanisms
191 for technical authors to invent and experiment with new syntaxes for their work.
192
193
194 \subsection{Package options}
195 Package options may be set when the package as loaded or at any later
196 stage with the \cs{unimathsetup} command. Therefore, the following two
197 examples are equivalent:
198 \begin{Verbatim}
199 \usepackage[math-style=TeX]{unicode-math}
200 % OR
201 \usepackage{unicode-math}
202 \unimathsetup{math-style=TeX}
203 \end{Verbatim}
204 Note, however, that some package options affects how maths is initialised
205 and changing an option such as |math-style| will not take effect until a
206 new maths font is set up.
207
208 Package options may \emph{also} be used when declaring new maths fonts,
209 passed via options to the \cs{setmathfont} command.
210 Therefore, the following two examples are equivalent:
211 \begin{Verbatim}
212 \unimathsetup{math-style=TeX}
213 \setmathfont{texgyrepagella-math.otf}
214 % OR
215 \setmathfont{texgyrepagella-math.otf}[math-style=TeX]
216 \end{Verbatim}
217
218 A summary list of package options is shown in \tabref{pkgopt}.
219 See following sections for more information.
220
221 \begin{table}\centering
222 \topcaption{Package options.}
223 \tablabel{pkgopt}
224 \begin{tabular}{lll}
225 \toprule
226 Option & Description & See\dots \\
227 \midrule
228 |math-style| & Style of letters & \secref*{math-style} \\
229 |bold-style| & Style of bold letters & \secref*{bold-style} \\
230 |sans-style| & Style of sans serif letters & \secref*{sans-style} \\
231 |nabla| & Style of the nabla symbol & \secref*{nabla} \\
232 |partial| & Style of the partial symbol & \secref*{partial} \\
233 |colon| & Behaviour of \cs{colon} & \secref*{colon} \\
234 |slash-delimiter| & Glyph to use for `stretchy' slash & \secref*{slash-delimiter} \\
235 \bottomrule
236 \end{tabular}
237 \end{table}
238
239
240 \section{Unicode maths font setup}
241
242 In the ideal case, a single Unicode font will contain all maths glyphs we
243 need. The file |unicode-math-table.tex| (based on Barbara Beeton's \STIX\ table)
244 provides the mapping between Unicode
245 maths glyphs and macro names (all 3298 — or however many — of them!). A
246 single command
247 \codeline{\cmd\setmathfont\marg{font name}\oarg{font features}}
248 implements this for every every symbol and alphabetic variant.
249 That means |x| to $x$, |\xi| to $\xi$, |\leq| to $\leq$, etc., |\symscr{H}|
250 to $\symscr{H}$ and so on, all for Unicode glyphs within a single font.
251
252 This package deals well with Unicode characters for maths
253 input. This includes using literal Greek letters in formulae,
254 resolving to upright or italic depending on preference.
255
256 Font features specific to \pkg{unicode-math} are shown in \tabref{mathfontfeatures}.
257 Package options (see \tabref{pkgopt}) may also be used.
258 Other \pkg{fontspec} features are also valid.
259
260 \begin{table}\centering
261 \topcaption{Maths font options.}
262 \tablabel{mathfontfeatures}
263 \begin{tabular}{lll}
264 \toprule
265 Option & Description & See\dots \\
266 \midrule
267 |range| & Style of letters & \secref{range} \\
268 |script-font| & Font to use for sub- and super-scripts & \secref{sscript} \\
269 |script-features| & Font features for sub- and super-scripts & \secref{sscript} \\
270 |sscript-font| & Font to use for nested sub- and super-scripts & \secref{sscript} \\
271 |sscript-features| & Font features for nested sub- and super-scripts & \secref{sscript} \\
272 \bottomrule
273 \end{tabular}
274 \end{table}
275
276 \subsection{Using multiple fonts}
277 \seclabel{range}
278
279 There will probably be few cases where a single Unicode maths font suffices
280 (simply due to glyph coverage). The \STIX\ font comes to mind as a
281 possible exception. It will therefore be necessary to delegate specific
282 Unicode ranges of glyphs to separate fonts:
283 \codeline{\cmd\setmathfont\marg{font name}|[range=|\meta{unicode range}|,|\meta{font features}|]|}
284 where \meta{unicode range} is a comma-separated list of Unicode slot numbers and ranges such as |{"27D0-"27EB,"27FF,"295B-"297F}|.
285 Note that \TeX's syntax for accessing the slot number of a character, such as |`\+|, will also work here.
286 Only numerical slots can be used in ranged declarations.
287
288 Note that, for efficiency, the \pkg{unicode-math} package only loads a default maths setup when absolutely necessary.
289 Before you use the |range| option you must first load a `main' maths font in the standard way.
290
291 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|).
292
293 \subsubsection{Control over alphabet ranges}
294
295 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:
296 \begin{quote}\ttfamily
297 \ExplSyntaxOn
298 \clist_const:Nn \g__um_named_ranges_clist {
299 up ,
300 it ,
301 bb ,
302 bbit ,
303 scr ,
304 cal ,
305 bfcal ,
306 frak ,
307 tt ,
308 sfup ,
309 sfit ,
310 bfup ,
311 bfit ,
312 bfscr ,
313 bffrak,
314 bfsfup,
315 bfsfit,
316 }
317 \clist_use:Nn \g__um_named_ranges_clist {\,,\,~}
318 \ExplSyntaxOff
319 \end{quote}
320 Fonts can be selected (for predefined ranges only) using the following syntax, in which case all other maths font setup remains untouched:
321 \begin{itemize}
322 \item |[range=bb]| to use the font for `|bb|' letters only.
323 \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.).
324 \item |[range=up->sfup]| to map to different output styles.
325 \end{itemize}
326
327 A common request is to load numerals only from a specific font. This can be
328 achieved with an option such as |range=up/{num}|.
329
330 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|').
331
332 If a particular math style is not defined in the font, we fall back onto the lower-base plane (i.e., `upright') glyphs.
333 Therefore, to use an \ascii-encoded fractur font, for example, write
334 \begin{Verbatim}
335 \setmathfont{SomeFracturFont}[range=frak]
336 \end{Verbatim}
337 and because the math plane fractur glyphs will be missing, \pkg{unicode-math} will know to use the \ascii\ ones instead.
338 If necessary this behaviour can be forced with |[range=frak->up]|, since the `|up|' range corresponds to \ascii\ letters.
339
340 %If you wanted to swap the maths symbols with sans serif forms, it would be possible to write |[range={up->sfup,it->sfit}]|.
341 %Note, however, that at present Unicode does not encode glyphs for sans serif Greek (\tabref{mathalphabets}).
342
343 Users of the impressive Minion Math fonts (commercial) may use remapping to access the bold glyphs using:
344 \begin{Verbatim}
345 \setmathfont{MinionMath-Regular.otf}
346 \setmathfont{MinionMath-Bold.otf}[range={bfup->up,bfit->it}]
347 \end{Verbatim}
348 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)
349 \begin{Verbatim}
350 \setmathfont{Minion Math}[
351 SizeFeatures = {
352 {Size = -6.01, Font = MinionMath-Tiny},
353 {Size = 6.01-8.41, Font = MinionMath-Capt},
354 {Size = 8.41-13.01, Font = MinionMath-Regular},
355 {Size = 13.01-19.91, Font = MinionMath-Subh},
356 {Size = 19.91-, Font = MinionMath-Disp}
357 }]
358
359 \setmathfont{Minion Math}[range = {bfup->up,bfit->it},
360 SizeFeatures = {
361 {Size = -6.01, Font = MinionMath-BoldTiny},
362 {Size = 6.01-8.41, Font = MinionMath-BoldCapt},
363 {Size = 8.41-13.01, Font = MinionMath-Bold},
364 {Size = 13.01-19.91, Font = MinionMath-BoldSubh},
365 {Size = 19.91-, Font = MinionMath-BoldDisp}
366 }]
367 \end{Verbatim}
368
369
370 \subsection{Script and scriptscript fonts/features}
371 \seclabel{sscript}
372
373 Cambria Math uses OpenType font features to activate smaller optical sizes
374 for scriptsize and scriptscriptsize symbols (the $B$ and $C$, respectively,
375 in $A_{B_C}$).
376 Other typefaces (such as Minion Math) may use entirely separate font files.
377
378 The features |script-font| and |sscript-font| allow alternate fonts to be
379 selected for the script and scriptscript sizes, and |script-features| and
380 |sscript-features| to apply different OpenType features to them.
381
382 By default |script-features| is defined as |Style=MathScript| and |sscript-features| is |Style=MathScriptScript|.
383 These correspond to the two levels of OpenType's |ssty| feature tag.
384 If the |(s)script-features| options are specified manually, you must
385 additionally specify the |Style| options as above.
386
387
388 \subsection{Maths `versions'}
389
390 \LaTeX\ uses a concept known as `maths versions' to switch math fonts
391 mid-document.
392 This is useful because it is more efficient than loading a complete maths
393 font from scratch every time---especially with thousands of glyphs in the case of Unicode maths!
394 The canonical example for maths versions is to select a `bold' maths font
395 which might be suitable for section headings, say.
396 (Not everyone agrees with this typesetting choice, though; be careful.)
397
398 To select a new maths font in a particular version, use the syntax
399 \codeline{\cmd\setmathfont\marg{font name}|[version=|\meta{version name}|,|\meta{font features}|]|}
400 and to switch between maths versions mid-document use the standard \LaTeX\ command
401 \cmd\mathversion\marg{version name}.
402
403 Note there are currently open issues regarding the interaction between the |version|
404 and the |range| features, so please proceed with caution.
405
406 \subsection{Legacy maths `alphabet' commands}
407 \seclabel{mathselect}
408
409 \LaTeX\ traditionally uses \cs{DeclareMathAlphabet} and \cs{SetMathAlphabet} to define document commands such as \cs{mathit}, \cs{mathbf}, and so on.
410 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.
411 This command is known as \cs{setmathface} in symmetry with \pkg{fontspec}'s \cs{newfontface} command; it takes syntax:
412 \begin{quote}
413 \cmd\setmathfontface\meta{command}\marg{font name}|[|\meta{font features}|]|
414
415 \makebox[0pt][l]{\cmd\setmathfontface\meta{command}\marg{font name}|[||version=|\meta{version name}|,|\meta{font features}|]|}
416 \end{quote}
417 For example, if you want to define a new legacy maths alphabet font \cs{mathittt}:
418 \begin{verbatim}
419 \setmathfontface\mathittt{texgyrecursor-italic.otf}
420 ...
421 $\mathittt{foo} = \mathittt{a} + \mathittt{b}$
422 \end{verbatim}
423
424
425 \subsubsection{Default `text math' fonts}
426
427 The five `text math' fonts, discussed above, are: \cs{mathrm}, \cs{mathbf}, \cs{mathit}, \cs{mathsf}, and \cs{mathtt}.
428 These commands are also defined with their original definition under synonyms \cs{mathtextrm}, \cs{mathtextbf}, and so on.
429 (These definitions hold regardless of package option, in case you need to be sure.)
430
431 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.
432
433 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.
434
435 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}.
436
437
438 \subsubsection{Replacing `text math' fonts by symbols}
439 \seclabel{textmathlegacy}
440
441 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).
442 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.
443
444 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.
445 In that case loading |unicode-math| with the |mathbf=sym| will achieve the desired result.
446
447 \begin{table}
448 \centering
449 \topcaption{Maths text font configuration options. Note that \cs{mathup} and \cs{mathrm} are aliases of each other and cannot be configured separately.}
450 \tablabel{legacyfontswitch}
451 \begin{tabular}{lll}
452 \toprule
453 Defaults (from `text' font) & From `maths symbols' \\
454 \midrule
455 |mathrm=text| & |mathrm=sym | \\
456 |mathup=text|\rlap{$^\ast$} & |mathup=sym|{}\rlap{$^\ast$} \\
457 |mathit=text| & |mathit=sym | \\
458 |mathsf=text| & |mathsf=sym | \\
459 |mathbf=text| & |mathbf=sym | \\
460 |mathtt=text| & |mathtt=sym | \\
461 \bottomrule
462 \end{tabular}
463 \end{table}
464
465
466 \subsubsection{Operator font}
467
468 \LaTeX\ defines an internal command \cs{operator@font} for typesetting elements such as |\sin| and |\cos|.
469 This font is selected from the legacy |operators| NFSS `MathAlphabet', which is no longer relevant in the context of \pkg{unicode-math}.
470 By default, the \cs{operator@font} command is defined to switch to the \cs{mathrm} font.
471 You may now change these using the command:
472 \begin{Verbatim}
473 \setoperatorfont\mathit
474 \end{Verbatim}
475 Or, to select a \pkg{unicode-math} range:
476 \begin{Verbatim}
477 \setoperatorfont\symscr
478 \end{Verbatim}
479 \setoperatorfont\symscr
480 For example, after the latter above, |$\sin x$| will produce `$\sin x$'.
481
482 \mathversion{normal}
483 \setoperatorfont\mathrm
484
485
486 \section{Maths input}
487
488 \XeTeX's Unicode support allows maths input through two methods. Like
489 classical \TeX, macros such as \cmd\alpha, \cmd\sum, \cmd\pm, \cmd\leq, and
490 so on, provide verbose access to the entire repertoire of characters defined
491 by Unicode. The literal characters themselves may be used instead, for more
492 readable input files.
493
494 \subsection{Math `style'}
495 \seclabel{math-style}
496
497 Classically, \TeX\ uses italic lowercase Greek letters and \emph{upright}
498 uppercase Greek letters for variables in mathematics. This is contrary to
499 the \textsc{iso} standards of using italic forms for both upper- and lowercase.
500 Furthermore, in various historical contexts, often associated with French typesetting, it was common to use upright uppercase \emph{Latin} letters as well as upright
501 upper- and lowercase Greek, but italic lowercase latin. Finally, it is not unknown to use upright letters
502 for all characters, as seen in the Euler fonts.
503
504 The \pkg{unicode-math} package accommodates these possibilities with the
505 option \opt{math-style} that takes one of five (case sensitive) arguments:
506 \opt{TeX}, \opt{ISO}, \opt{french}, \opt{upright}, or \opt{literal}.\footnote{Interface inspired by Walter Schmidt's \pkg{lucimatx} package.}
507 The \opt{math-style} options' effects are shown in brief in \tabref{math-style}.
508
509 The philosophy behind the interface to the mathematical symbols
510 lies in \LaTeX's attempt of separating content and formatting. Because input
511 source text may come from a variety of places, the upright and
512 `mathematical' italic Latin and Greek alphabets are \emph{unified} from the
513 point of view of having a specified meaning in the source text. That is, to
514 get a mathematical ‘$x$’, either the \ascii\ (`keyboard') letter |x| may
515 be typed, or the actual Unicode character may be used. Similarly for Greek
516 letters. The upright or italic forms are then chosen based on the
517 |math-style| package option.
518
519 If glyphs are desired that do not map as per the package option (for
520 example, an upright `g' is desired but typing |$g$| yields `$g$'),
521 \emph{markup} is required to specify this; to follow from the example:
522 |\symup{g}|.
523 Maths style commands such as \cmd\symup\ are detailed later.
524
525 For compatibility and consistency, however, upright and italic Greek letters
526 can be `forced` using \verb|up| or \verb|it| prefixes before their names.
527 For example, \cs{Gamma} will give an upright or italic Gamma depending on the
528 \opt{math-style}, but \cs{upGamma} and \cs{itGamma} will always give upright
529 or italic Gammas, respectively.
530
531 \paragraph{`Literal' interface}
532 Some may not like this convention of normalising their input.
533 For them, an upright |x| is an upright `x' and that's that.
534 (This will be the case when obtaining source text from copy/pasting PDF or
535 Microsoft Word documents, for example.)
536 For these users, the |literal| option to |math-style| will effect this behaviour.
537 The \cs{symliteral}\marg{syms} command can also be used, regardless of package setting, to force the style to match the literal input characters.
538 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.
539
540
541 \begin{table}
542 \centering
543 \topcaption{Effects of the \opt{math-style} package option.}
544 \tablabel{math-style}
545 \begin{tabular}{@{}>{\ttfamily}lcc@{}}
546 \toprule
547 & \multicolumn{2}{c}{Example} \\
548 \cmidrule(l){2-3}
549 \rmfamily Package option & Latin & Greek \\
550 \midrule
551 math-style=ISO & $(a,z,B,X)$ & $\symit{(\alpha,\beta,\Gamma,\Xi)}$ \\
552 math-style=TeX & $(a,z,B,X)$ & $(\symit\alpha,\symit\beta,\symup\Gamma,\symup\Xi)$ \\
553 math-style=french & $(a,z,\symup B,\symup X)$ & $(\symup\alpha,\symup\beta,\symup\Gamma,\symup\Xi)$ \\
554 math-style=upright & $(\symup a,\symup z,\symup B,\symup X)$ & $(\symup\alpha,\symup\beta,\symup\Gamma,\symup\Xi)$ \\
555 \bottomrule
556 \end{tabular}
557 \end{table}
558
559 \paragraph{`Full-width' letters}
560 Unicode contains `full-width' versions of ASCII from \unichar{FF01}.
561 The numerals and latin letters in this range are defined by \pkg{unicode-math}
562 to map to their standard ASCII counterparts, which are then controlled by the relevant \opt{math-style} setting.
563 Other full-width symbols are not currently included but can be if there is sufficient need or desire.
564
565 \subsection{Bold style}
566 \seclabel{bold-style}
567
568 Similar as in the previous section, ISO standards differ somewhat to \TeX's
569 conventions (and classical typesetting) for `boldness' in mathematics. In
570 the past, it has been customary to use bold \emph{upright} letters to denote
571 things like vectors and matrices. For example, \( \symbfup{M} =
572 (\mitM_x,\mitM_y,\mitM_z) \). Presumably, this was due to the relatively
573 scarcity of bold italic fonts in the pre-digital typesetting era.
574 It has been suggested by some that \emph{italic} bold symbols should be used nowadays instead, but this practise is certainly not widespread.
575
576 Bold Greek letters have simply been bold variant glyphs of their regular
577 weight, as in \( \mbfitxi = (\mitxi_\mitr,\mitxi_\mitphi,\mitxi_\mittheta)
578 \).
579 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
580 \cmd\boldsymbol, deprecated) in the latter (`$\mbfitxi$').
581
582 In \pkg{unicode-math}, the \cmd\symbf\ command works directly with both
583 Greek and Latin maths characters and depending on package option
584 either switches to upright for Latin letters (|bold-style=TeX|) as well or
585 keeps them italic (|bold-style=ISO|).
586 To match the package options for non-bold characters, with option
587 |bold-style=upright| all bold characters are upright, and
588 |bold-style=literal| does not change the upright/italic shape of the letter.
589 The \opt{bold-style} options' effects are shown in brief in \tabref{bold-style}.
590
591 Upright and italic bold mathematical letters input as direct Unicode
592 characters are normalised with the same rules. For example, with
593 |bold-style=TeX|, a literal bold italic latin character will be typeset
594 upright.
595
596 Note that \opt{bold-style} is independent of \opt{math-style}, although if
597 the former is not specified then matching defaults are chosen based on the
598 latter.
599
600 \begin{table}
601 \centering
602 \topcaption{Effects of the \opt{bold-style} package option.}
603 \tablabel{bold-style}
604 \begin{tabular}{@{}>{\ttfamily}lcc@{}}
605 \toprule
606 & \multicolumn{2}{c}{Example} \\
607 \cmidrule(l){2-3}
608 \rmfamily Package option & Latin & Greek \\
609 \midrule
610 bold-style=ISO & $(\symbfit a, \symbfit z, \symbfit B, \symbfit X)$ & $(\symbfit\alpha, \symbfit\beta, \symbfit\Gamma, \symbfit\Xi)$ \\
611 bold-style=TeX & $(\symbfup a,\symbfup z,\symbfup B,\symbfup X)$ & $(\symbfit\alpha, \symbfit\beta,\symbfup \Gamma,\symbfup \Xi)$ \\
612 bold-style=upright & $(\symbfup a,\symbfup z,\symbfup B,\symbfup X)$ & $(\symbfup \alpha,\symbfup \beta,\symbfup \Gamma,\symbfup \Xi)$ \\
613 \bottomrule
614 \end{tabular}
615 \end{table}
616
617
618 \subsection{Sans serif style}
619 \seclabel{sans-style}
620
621 Unicode contains upright and italic, medium and bold mathematical style characters.
622 These may be explicitly selected with the \cs{symsfup}, \cs{symsfit}, \cs{symbfsfup}, and \cs{symbfsfit}
623 commands discussed in \secref{all-math-alphabets}.
624
625 How should the generic \cs{symsf} behave? Unlike bold, sans serif is used much more sparingly
626 in mathematics. I've seen recommendations to typeset tensors in sans serif italic
627 or sans serif italic bold (e.g., examples in the \pkg{isomath} and \pkg{mattens} packages).
628 But \LaTeX's \cs{mathsf} is \textsl{upright} sans serif.
629
630 Therefore, the package options |[sans-style=upright]| and |[sans-style=italic]| control the behaviour of \cs{symsf}.
631 The |upright| style sets up the command to use upright sans serif, including Greek;
632 the |italic| style switches to using italic in both Latin and Greek.
633 In other words, this option simply changes the meaning of \cs{symsf} to either \cs{symsfup} or \cs{symsfit}, respectively.
634 Please let me know if more granular control is necessary here.
635
636 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.
637
638 \subsubsection{What about bold sans serif?}
639
640 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.).
641 Therefore, bold sans serif follows from the setting for sans serif; it is completely independent of the setting for bold.
642
643 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.
644
645 N.B.: there is no medium-weight sans serif Greek range in Unicode.
646 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|.
647
648 \subsection{All (the rest) of the mathematical styles}
649 \seclabel{all-math-alphabets}
650
651 Unicode contains separate codepoints for most if not all variations of style
652 shape one may wish to use in mathematical notation. The complete list is shown
653 in \tabref{mathalphabets}. Some of these have been covered in the previous sections.
654
655 The math font switching commands do not nest; therefore if you want
656 sans serif bold, you must write |\symbfsf{...}| rather than |\symbf{\symsf{...}}|.
657 This may change in the future.
658
659 \begin{table}
660 \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}.}
661 \tablabel{mathalphabets}
662 \centering
663 \def\Y{\textbullet}
664 \def\M{\textopenbullet}
665 \begin{tabular}{@{} lll l ccc @{}}
666 \toprule
667 \multicolumn{3}{c}{Font} & & \multicolumn{3}{c}{Alphabet} \\
668 \cmidrule(r){1-3}
669 \cmidrule(l){5-7}
670 Style & Shape & Series & Switch & Latin & Greek & Numerals \\
671 \midrule
672 Serif & Upright & Normal & \cs{symup} & \Y & \Y & \Y \\
673 & & Bold & \cs{symbfup} & \Y & \Y & \Y \\
674 & Italic & Normal & \cs{symit} & \Y & \Y & \M \\
675 & & Bold & \cs{symbfit} & \Y & \Y & \M \\
676 Sans serif & Upright & Normal & \cs{symsfup} & \Y & & \Y \\
677 & & Bold & \cs{symbfsfup} & \Y & \Y & \Y \\
678 & Italic & Normal & \cs{symsfit} & \Y & & \M \\
679 & & Bold & \cs{symbfsfit} & \Y & \Y & \M \\
680 Typewriter & Upright & Normal & \cs{symtt} & \Y & & \Y \\
681 Double-struck & Upright & Normal & \cs{symbb} & \Y & & \Y \\
682 & Italic & Normal & \cs{symbbit} & \Y & & \\
683 Script & Upright & Normal & \cs{symscr} & \Y & & \\
684 & & Bold & \cs{symbfscr} & \Y & & \\
685 Fraktur & Upright & Normal & \cs{symfrak} & \Y & & \\
686 & & Bold & \cs{symbffrak} & \Y & & \\
687 \bottomrule
688 \end{tabular}
689 \end{table}
690
691 \subsubsection{Scope of the functionality of the \cs{sym..} commands}
692
693 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$).
694 These are the only symbols for which Unicode defines separate codepoints with varying mathematical style.
695
696 There is currently no scope for including other symbols in the \cs{sym..} commands, such as writing |\symbf{\int}| for a bold integral symbol.
697 Therefore the commands provided by \pkg{unicode-math} should not be compared to those provided by the \pkg{bm} package.
698
699 \subsubsection{Double-struck}
700
701 The double-struck style (also known as `blackboard bold') consists of
702 upright Latin letters $\{\symbb{a}$--$\symbb{z}$,$\symbb{A}$$\symbb{Z}\}$,
703 numerals $\symbb{0}$--$\symbb{9}$, summation symbol $\symbb\sum$, and four
704 Greek letters only: $\{\symbb{\gamma\pi\Gamma\Pi}\}$.
705
706 While |\symbb{\sum}| does produce a double-struck summation symbol,
707 its limits aren't properly aligned. Therefore,
708 either the literal character or the control sequence \cs{Bbbsum} are
709 recommended instead.
710
711 There are also five Latin \emph{italic} double-struck letters: $\symbbit{Ddeij}$.
712 These can be accessed (if not with their literal characters or control sequences)
713 with the \cs{mathbbit} style switch, but note that only those five letters
714 will give the expected output.
715
716 \subsubsection{Calligraphic vs.\ Script variants}
717
718 The Unicode maths encoding contains a style for `Script' letters,
719 and while by default \cs{symcal} and \cs{symscr}
720 are synonyms, there are some situations when a
721 separate `Calligraphic' style is needed as well.
722
723 If a font contains alternate glyphs for a separate calligraphic style,
724 they can be selected explicitly. For example the STIX~Two~Math font
725 uses the the first stylistic set feature (|ss01|) to map the script
726 letters to the calligraphic letters.
727 \begin{Verbatim}
728 \setmathfont{STIXTwoMath-Regular.otf}
729 \setmathfont{STIXTwoMath-Regular.otf}[range={cal, bfcal}, StylisticSet=1]
730 \end{Verbatim}
731 With the above we can now write
732 \begin{quote}
733 \setmathfont{STIXTwoMath-Regular.otf}
734 \setmathfont{STIXTwoMath-Regular.otf}[range={cal, bfcal}, StylisticSet=1]
735 |$\symscr{ABCDabcd}$| to get $\symscr{ABCDabcd}$ \\
736 |$\symcal{ABCDabcd}$| to get $\symcal{ABCDabcd}$
737 \end{quote}
738
739 \subsection{Miscellanea}
740
741 \subsubsection{Nabla}
742 \seclabel{nabla}
743
744 The symbol $\nabla$ comes in the six forms shown in \tabref{nabla}.
745 We want an individual option to specify whether we want upright or italic
746 nabla by default (when either upright or italic nabla is used in the
747 source). \TeX\ classically uses an upright nabla, and \textsc{iso}
748 standards agree with this convention.
749 The package options |nabla=upright| (default) and
750 |nabla=italic| switch between the two choices, and |nabla=literal| respects
751 the shape of the input character.
752 |nabla=literal| is activated automatically after |math-style=literal|.
753
754 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.
755
756
757 \begin{table}
758 \begin{minipage}[b]{0.49\textwidth}
759 \centering
760 \topcaption{The various forms of nabla.}
761 \tablabel{nabla}
762 \let \tmpshow\empty
763 \begin{tabular}{@{}llc@{}}
764 \toprule
765 \multicolumn{2}{@{}l}{Description} & Glyph \\
766 \cmidrule(r){1-2}\cmidrule(l){3-3}
767 Upright & Serif & $\symup\nabla$ \\
768 & Bold serif & $\symbfup\nabla$ \\
769 & Bold sans & $\symbfsfup\nabla$ \\
770 \cmidrule(lr){1-2}\cmidrule(lr){3-3}
771 Italic & Serif & $\symit\nabla$ \\
772 & Bold serif & $\symbfit\nabla$ \\
773 & Bold sans & $\symbfsfit\nabla$ \\
774 \bottomrule
775 \end{tabular}
776 \end{minipage}\hfill
777 \begin{minipage}[b]{0.49\textwidth}
778 \centering
779 \topcaption{The partial differential.}
780 \tablabel{partial}
781 \begin{tabular}{@{}llc@{}}
782 \toprule
783 \multicolumn{2}{@{}l}{Description} & Glyph \\
784 \cmidrule(r){1-2}\cmidrule(l){3-3}
785 Regular & Upright & $\symup\partial$ \\
786 & Italic & $\symit\partial$ \\
787 Bold & Upright & $\symbfup\partial$ \\
788 & Italic & $\symbfit\partial$ \\
789 Sans bold & Upright & $\symbfsfup\partial$ \\
790 & Italic & $\symbfsfit\partial$ \\
791 \bottomrule
792 \end{tabular}
793 \end{minipage}
794 \end{table}
795
796
797 \subsubsection{Partial}
798 \seclabel{partial}
799
800 The same logic as for nabla applies to the symbols \unichar{2202} partial differential and \unichar{1D715} math italic partial differential.
801 However, in practice these symbols are often designed identically in an italic style.
802
803 If the font you are using supports it, use the |partial=upright| or |partial=italic| (default) package options to specify
804 which one you would like, or |partial=literal| to have the same character
805 used in the output as was used for the input.
806 |partial=literal| is activated following |math-style=literal|.
807
808 See \tabref{partial} for the variations on the partial differential symbol.
809
810
811 \subsubsection{Primes}
812
813 Primes ($x'$) may be input in several ways. You may use any combination
814 the \ascii\ straight quote (\texttt{\char`\'}) or the Unicode prime \unichar{2032}
815 ($'$); when multiple primes occur next to each other, they chain
816 together to form double, triple, or quadruple primes if the font contains
817 pre-drawn glyphs. The individual prime glyphs are accessed, as usual,
818 with the \cs{prime} command, and the double-, triple-, and quadruple-prime
819 glyphs are available with \cs{dprime}, \cs{trprime}, and \cs{qprime},
820 respectively.
821
822 If the font does not contain the pre-drawn glyphs or more than four primes
823 are used, the single prime glyph is used multiple times with a negative
824 kern to get the spacing right. There is no user interface to adjust this
825 negative kern yet (because I haven't decided what it should look like);
826 if you need to, write something like this:
827 \begin{Verbatim}
828 \ExplSyntaxOn
829 \muskip_gset:Nn \g_@@_primekern_muskip { -\thinmuskip/2 }
830 \ExplySyntaxOff
831 \end{Verbatim}
832 Backwards or reverse primes behave in exactly the same way; use the \ascii\
833 back tick (\texttt{\char`\`}) or the Unicode reverse prime \unichar{2035}
834 ({\umfont\char"2035}).
835 The command to access the backprime is \cs{backprime}, and
836 multiple backwards primes can accessed with \cs{backdprime},
837 \cs{backtrprime}, and \cs{backqprime}.
838
839 In all cases above, no error checking is performed if you attempt to
840 access a multi-prime glyph in a font that doesn't contain one. For this
841 reason, it may be safer to write |x''''| instead of |x\qprime|
842 in general.
843
844 If you ever need to enter the straight quote |'| or the backtick |`| in
845 maths mode, these glyphs can be accessed with \cs{mathstraightquote} and
846 \cs{mathbacktick}.
847
848 \subsubsection{Subscripts and superscripts and symbol alphabets}
849
850 In traditional \LaTeX, users have for many years exploited a loophole in the implementation
851 of |\mathrm| and similar to write expressions such as |x_\mathrm f| to achieve
852 $x_{\mathrm{f}}$ instead of writing the more correct |x_{\mathrm{f}}|.
853 Shorthand notation such as |x_\mathrm f| is not officially documented \LaTeX\ syntax,
854 and due to a particular implementation detail in \pkg{unicode-math} this \emph{incorrect}
855 syntax is no longer supported.
856
857
858 \subsubsection{Unicode subscripts and superscripts}
859
860 You may, if you wish, use Unicode subscripts and superscripts in your
861 source document. For basic expressions, the use of these characters
862 can make the input more readable.
863 Adjacent sub- or super-scripts will be concatenated into a single
864 expression.
865
866 The range of subscripts and superscripts supported by this package
867 are shown in \figref{superscripts,subscripts}. Please request more if
868 you think it is appropriate.
869
870 \begin{figure}\centering
871 \fbox{\fontspec{DejaVuSerif.ttf}\Large
872 A
873 ^^^^2070 ^^^^00b9 ^^^^00b2 ^^^^00b3 ^^^^2074 ^^^^2075 ^^^^2076 ^^^^2077
874 ^^^^2078 ^^^^2079 ^^^^207a ^^^^207b ^^^^207c ^^^^207d ^^^^207e ^^^^2071
875 ^^^^207f ^^^^207f ^^^^02b0 ^^^^02b2 ^^^^02b3 ^^^^02b7 ^^^^02b8
876 Z}
877 \caption{
878 The Unicode superscripts supported as input characters.
879 These are the literal glyphs from the `DejaVu Serif' font,
880 not the output seen when used for maths input.
881 The `A' and `Z' are to provide context for the size and
882 location of the superscript glyphs.
883 }
884 \figlabel{superscripts}
885 \end{figure}
886
887 \begin{figure}\centering
888 \fbox{\fontspec{DejaVuSerif.ttf}\Large
889 A
890 ^^^^2080 ^^^^2081 ^^^^2082 ^^^^2083 ^^^^2084 ^^^^2085 ^^^^2086 ^^^^2087
891 ^^^^2088 ^^^^2089 ^^^^208a ^^^^208b ^^^^208c ^^^^208d ^^^^208e ^^^^2090
892 ^^^^2091 ^^^^1d62 ^^^^2092 ^^^^1d63 ^^^^1d64 ^^^^1d65 ^^^^2093 ^^^^1d66
893 ^^^^1d67 ^^^^1d68 ^^^^1d69 ^^^^1d6a
894 Z}
895 \caption{
896 The Unicode subscripts supported as input characters.
897 See note from \figref{superscripts}.
898 }
899 \figlabel{subscripts}
900 \end{figure}
901
902 \subsubsection{Colon}
903 \seclabel{colon}
904
905 The colon is one of the few confusing characters of Unicode maths.
906 In \TeX, \texttt{:} is defined as a colon with relation spacing: `$a:b$'.
907 While \cs{colon} is defined as a colon with punctuation spacing: `$a\colon b$'.
908
909 In Unicode, \unichar{003A} {colon} is defined as a punctuation symbol,
910 while \unichar{2236} {ratio} is the colon-like symbol used in mathematics to denote
911 ratios and other things.
912
913 This breaks the usual straightforward mapping from control sequence to Unicode input character
914 to (the same) Unicode glyph.
915
916 To preserve input compatibility, we remap the \ascii\ input character `\texttt{:}' to \unichar{2236}.
917 Typing a literal \unichar{2236} char will result in the same output.
918
919 The package option |colon=literal| forces \ascii\ input `|:|' to be printed as \cs{mathcolon} instead.
920
921
922 \subsubsection{Slashes and backslashes}
923 \seclabel{slash-delimiter}
924
925 There are several slash-like symbols defined in Unicode.
926 The complete list is shown in \tabref{slashes}. Unfortunately, font support for these characters/glyphs is rather inconsistent.
927 Note that \cs{slash} internally uses the \cs{mathslash} mathematical character.
928 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>|.
929
930 \begin{table}\centering
931 \topcaption{Slashes and backslashes.}
932 \tablabel{slashes}
933 \begin{tabular}{@{}cl@{}cll@{}}
934 \toprule
935 Slot & Name & Glyph & Class & Command \\
936 \midrule
937 \unichar{002F} & \textsc{solidus} & \umfont \char"002F & \cs{mathord} & \cs{slash} \\
938 \unichar{27CB} & \textsc{rising diagonal} & \umfont \char"27CB & \cs{mathord} & \cs{diagup} \\
939 \unichar{2044} & \textsc{fraction slash} & \umfont \char"2044 & \cs{mathbin} & \cs{fracslash} \\
940 \unichar{2215} & \textsc{division slash} & \umfont \char"2215 & \cs{mathbin} & \cs{divslash} \\
941 \unichar{29F8} & \textsc{big solidus} & \umfont \char"29F8 & \cs{mathop} & \cs{xsol} \\
942 \midrule
943 \unichar{005C} & \textsc{reverse solidus} & \umfont \char"005C & \cs{mathord} & \cs{backslash} \\
944 \unichar{27CD} & \textsc{falling diagonal} & \umfont \char"27CD & \cs{mathord} & \cs{diagdown} \\
945 \unichar{2216} & \textsc{set minus} & \umfont \char"2216 & \cs{mathbin} & \cs{setminus} \\
946 & \textsc{small set minus} & & \cs{mathbin} & \cs{smallsetminus} \\
947 \unichar{29F5} & \textsc{reverse solidus operator}& \umfont \char"29F5 & \cs{mathbin} & \cs{reversesolidus} \\
948 \unichar{29F9} & \textsc{big reverse solidus} & \umfont \char"29F9 & \cs{mathop} & \cs{xbsol} \\
949 \bottomrule
950 \end{tabular}
951 \end{table}
952
953 \paragraph{Slashes}
954
955 Of \unichar{2044} {fraction slash}, TR25 says that it is:
956 \begin{quote}
957 \dots used to build up simple fractions in running text\dots
958 however parsers of mathematical texts should be prepared to handle fraction slash
959 when it is received from other sources.
960 \end{quote}
961
962 \unichar{2215} {division slash} should be used when division is represented
963 without a built-up fraction; $\pi\approx22/7$, for example.
964
965 \unichar{29F8} {big solidus} is a `big operator' (like $\sum$).
966
967 \cs{diagup} and \cs{diagdown} are defined with math class \cs{mathord} for consistency with \pkg{amssymb}.
968 This definition is inconsistent with MathML, which would use \cs{mathrel} instead.
969
970 \paragraph{Backslashes}
971
972 Of the five backslash characters shown in \tabref{slashes}, only \cs{backslash} and \cs{setminus} are defined consistently across all OpenType math fonts.
973 (The two glyphs are typically identical, or close to it, with the main difference between them the spacing defined by their math class.)
974
975 The \unichar{005C} {reverse solidus} character \cs{backslash} is used for denoting
976 double cosets: $A\backslash B$. It may be used as a `stretchy' delimiter if supported by the font.
977
978 The \unichar{2216} {set minus} character \cs{setminus} defines the relative complement or set difference between two sets: $A\setminus B$.
979
980 Presumably, \unichar{29F5} {reverse solidus operator} is intended to
981 be used in a similar way, but it could also be used to
982 represent `inverse division': $\pi\approx7\mathbin{\backslash}22$.^^A
983 \footnote{This is valid syntax in the Octave and Matlab programming languages,
984 in which it means matrix inverse pre-multiplication. I.e., $A\mathbin{\backslash} B\equiv A^{-1}B$.}
985
986 Finally, \unichar{29F9} {big reverse solidus} is a `big operator' (like $\sum$).
987
988 \paragraph{Slashes as `delimiters'}
989
990 In regular \LaTeX\ we can write \cs{left}\cs{slash}\dots\cs{right}\cs{backslash}
991 and so on and obtain extensible delimiter-like symbols. Not all of the Unicode slashes
992 are suitable for this (and do not have the font support to do it).
993
994 In Cambria Math, the only slash that grows (say when writing
995 \[
996 \left.\left[\begin{array}{cc} a & b \\ c & d\end{array}\right]\middle\slash
997 \left[\begin{array}{cc} 1 & 1 \\ 1 & 0\end{array}\right] \right.\quad )
998 \]
999 is the \textsc{fraction slash}, which we just established above is
1000 sort of only supposed to be used in text.
1001
1002 Of the slashes, the following commands are the only ones defined to be able to be used as stretchable delimiters after
1003 \cs{left}, \cs{middle}, and \cs{right}:
1004 \begin{itemize}
1005 \item \cs{fracslash};
1006 \item \cs{slash}; and,
1007 \item \cs{backslash} (the only reverse slash).
1008 \end{itemize}
1009
1010 However, for the purpose of implementing this markup, we assume that there is only \emph{one} stretchy slash
1011 in the font; this is assumed by default to be \unichar{002F} {solidus}.
1012 Writing \cs{left/} or \cs{left}\cs{slash} or \cs{left}\cs{fracslash}
1013 will all result in the same stretchy delimiter being used.
1014 The delimiter used can be changed with the |slash-delimiter| package option.
1015 Allowed values are |ascii|, |frac|, and |div|, corresponding to the respective
1016 Unicode slots.
1017
1018 For example: as mentioned above, Cambria Math's stretchy slash is
1019 \unichar{2044} {fraction slash}. When using Cambria Math, then
1020 \pkg{unicode-math} should be loaded with the |slash-delimiter=frac| option.
1021 (This should really be a font option rather than a package option, but this option should only be needed infrequently.)
1022
1023 \paragraph{Set minus characters/glyphs}
1024
1025 Standard \LaTeX\ plus \pkg{amssymb} defines two commands \cs{setminus} and \cs{smallsetminus}.
1026 This package now defines \cs{setminus} to correspond to the Unicode slot \unichar{2216}.
1027 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).
1028 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.
1029
1030 If variations to this setup are needed, users can redefine the commands to their liking; e.g.:
1031 \begin{verbatim}
1032 \setmathfont{XITSMath-Regular.otf}
1033 \AtBeginDocument{
1034 \let\smallsetminus\setminus
1035 \let\setminus\reversesolidus
1036 }
1037 \end{verbatim}
1038
1039
1040 \subsubsection{Behaviour of hyphens in mathematics}
1041 \seclabel{hyphen}
1042
1043 Unicode defines the following related characters:
1044 \begin{itemize}
1045 \item \unichar{0002D}{hyphen-minus}
1046 \item \unichar{02212}{minus sign}
1047 \item \unichar{02010}{hyphen} (\cs{mathhyphen})
1048 \end{itemize}
1049 The first two of these characters in the input will all behave as the binary operator
1050 `minus sign'.
1051 The third is defined by \pkg{unicode-math} as a `math letter' for constructions
1052 like \verb|$R‐\text{Mod}$| ($R‐\text{Mod}$).
1053 If more control is needed surrounding these symbols, additional options can be added to the package;
1054 please get in touch if this is the case for you.
1055
1056
1057 \subsubsection{Growing and non-growing accents}
1058 \seclabel{growing-accents}
1059
1060 There are a few accents for which \TeX\ has both non-growing and growing
1061 versions. Among these are \cs{hat} and \cs{tilde}; the corresponding growing
1062 versions are called \cs{widehat} and \cs{widetilde}, respectively.
1063
1064 Older versions of \XeTeX\ and \LuaTeX\ did not support this distinction,
1065 however, and \emph{all} accents there were growing automatically. (I.e.,
1066 \cs{hat} and \cs{widehat} are equivalent.) As of \LuaTeX\ v0.65 and \XeTeX\
1067 v0.9998, these wide/non-wide commands will again behave in their expected
1068 manner.
1069
1070
1071 \subsubsection{Negations and the \cs{not} command}
1072 \seclabel{negations}
1073
1074 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.
1075
1076 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.
1077
1078 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$).
1079
1080 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:
1081 \begin{verbatim}
1082 \NewNegationCommand {=} {\neq}
1083 \NewNegationCommand {\equal} {\neq}
1084 \end{verbatim}
1085 If the command has already been defined, an error will result and \verb|\RenewNegationCommand| can be used to overwrite the original definition.
1086
1087
1088 \subsubsection{Pre-drawn fraction characters}
1089
1090 Pre-drawn fractions \unichar{00BC}--\unichar{00BE}, \unichar{2150}--\unichar{215E}
1091 are not suitable for use in mathematics output. However, they can be useful
1092 as input characters to abbreviate common fractions.
1093 \begin{center}
1094 \fontspec{DejaVuSerif.ttf} ^^A available in TeX Live 2012 if not earlier
1095 ¼ ½ ¾ ↉ ⅐ ⅑ ⅒ ⅓ ⅔ ⅕ ⅖ ⅗ ⅘ ⅙ ⅚ ⅛ ⅜ ⅝ ⅞
1096 \end{center}
1097 For example, instead of writing `|\tfrac12 x|', you may consider it more readable to have
1098 `|½x|' in the source instead.
1099
1100 By default, the \cs{tfrac} command will be used to typeset the fractions.
1101 The command to use (\cs{tfrac} or \cs{frac}) can be forced with the package
1102 option |active-frac=small| or |active-frac=normalsize|, respectively.
1103
1104 \subsubsection{Circles}
1105
1106 Unicode defines a large number of different types of circles for a variety
1107 of mathematical purposes. There are thirteen alone just considering the
1108 all white and all black ones, shown in \tabref{circles}.
1109
1110 \LaTeX\ defines considerably fewer: \cs{circ} and \cs{bigcirc} for white;
1111 \cs{bullet} for black. This package maps those commands to \cs{vysmwhtcircle},
1112 \cs{mdlgwhtcircle}, and \cs{smblkcircle}, respectively.
1113
1114 \begin{table}\centering
1115 \def\showchar#1#2#3{ \textsc{u}+{\small\ttfamily #1} & \texttt{\string#3} & \umfont \char"#1 \\}
1116 \begin{tabular}{@{}llc@{}}
1117 \toprule
1118 Slot & Command & Glyph \\
1119 \midrule
1120 \showchar{00B7}{centerdot}{\cdotp}
1121 \showchar{22C5}{small middle dot}{\cdot}
1122 \showchar{2219}{bullet operator}{\vysmblkcircle}
1123 \showchar{2022}{round bullet, filled}{\smblkcircle}
1124 \showchar{2981}{z notation spot}{\mdsmblkcircle}
1125 \showchar{26AB}{medium black circle}{\mdblkcircle}
1126 \showchar{25CF}{circle, filled}{\mdlgblkcircle}
1127 \showchar{2B24}{black large circle}{\lgblkcircle}
1128 \bottomrule
1129 \end{tabular}
1130 \def\showchar#1#2#3{ \umfont \char"#1 & \texttt{\string#3} & \textsc{u}+{\small\ttfamily #1} \\}
1131 \begin{tabular}{@{}cll@{}}
1132 \toprule
1133 Glyph & Command & Slot \\
1134 \midrule
1135 \\
1136 \\
1137 \showchar{2218}{composite function (small circle)}{\vysmwhtcircle}
1138 \showchar{25E6}{white bullet}{\smwhtcircle}
1139 \showchar{26AC}{medium small white circle}{\mdsmwhtcircle}
1140 \showchar{26AA}{medium white circle}{\mdwhtcircle}
1141 \showchar{25CB}{large circle}{\mdlgwhtcircle}
1142 \showchar{25EF}{large circle}{\lgwhtcircle}
1143 \bottomrule
1144 \end{tabular}
1145 \caption{Filled and hollow Unicode circles.}
1146 \tablabel{circles}
1147 \end{table}
1148
1149 \subsubsection{Triangles}
1150
1151 While there aren't as many different sizes of triangle as there are circle,
1152 there's some important distinctions to make between a few similar characters. See \tabref{uptriangles} for the full summary.
1153
1154 These triangles all have different intended meanings. Note for backwards
1155 compatibility with \TeX, \unichar{25B3} has \emph{two} different mappings
1156 in \pkg{unicode-math}. \cs{bigtriangleup} is intended as a binary operator
1157 whereas \cs{triangle} is intended to be used as a letter-like symbol.
1158
1159 But you're better off if you're using the latter form to indicate an
1160 increment to use the glyph intended for this purpose, \unichar{2206}: $\increment x$.
1161
1162 Finally, given that $\triangle$ and $\increment$ are provided for you
1163 already, it is better off to only use upright Greek Delta $\Delta$ if you're
1164 actually using it as a symbolic entity such as a variable on its own.
1165
1166 \begin{table}\centering
1167 \begin{tabular}{@{}llcl@{}}
1168 \toprule
1169 Slot & Command & Glyph & Class \\
1170 \midrule
1171 \unichar{25B5} & \cs{vartriangle} & \umfont \char"25B5 & binary \\
1172 \unichar{25B3} & \cs{bigtriangleup} & \umfont \char"25B3 & binary \\
1173 \unichar{25B3} & \cs{triangle} & \umfont \char"25B3 & ordinary \\
1174 \unichar{2206} & \cs{increment} & \umfont \char"2206 & ordinary \\
1175 \unichar{0394} & \cs{mathup}\cs{Delta} & \umfont \char"0394 & ordinary \\
1176 \bottomrule
1177 \end{tabular}
1178 \caption{Different upwards pointing triangles.}
1179 \tablabel{uptriangles}
1180 \end{table}
1181
1182 \iffalse
1183 \subsubsection{Normalising some input characters}
1184
1185 I believe
1186 all variant forms should be used as legal input that is normalised to
1187 a consistent output glyph, because we want to be fault-tolerant in the input.
1188 Here are the duplicates:
1189 \begin{quote}\obeylines
1190 \unichar {251} {latin small letter alpha}
1191 \unichar {25B} {latin small letter epsilon}
1192 \unichar {263} {latin small letter gamma}
1193 \unichar {269} {latin small letter iota}
1194 \unichar {278} {latin small letter phi}
1195 \unichar {28A} {latin small letter upsilon}
1196 \unichar {190} {latin capital letter epsilon}
1197 \unichar {194} {latin capital letter gamma}
1198 \unichar {196} {latin capital letter iota}
1199 \unichar {1B1} {latin capital letter upsilon}
1200 \end{quote}
1201
1202 (Not yet implemented.)
1203 \fi
1204
1205 \section{Advanced}
1206
1207 \subsection{Warning messages}
1208
1209 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.
1210 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.
1211 A warning will give you its name when printed on the console output; e.g.,
1212 \begin{Verbatim}
1213 * unicode-math warning: "mathtools-colon"
1214 *
1215 * ... <warning message> ...
1216 \end{Verbatim}
1217 This warning could be suppressed by loading the package as follows:
1218 \begin{Verbatim}
1219 \usepackage[warnings-off={mathtools-colon}]{unicode-math}
1220 \end{Verbatim}
1221
1222 \subsection{How to overwrite a macro}
1223
1224 \pkg{unicode-math} defines the macros by \cs{AtBeginDocument},
1225 namely delays the definition until |\begin{document}| is met.
1226 If you want to overwrite a macro defined by \pkg{unicode-math},
1227 please redefine it in \cs{AtBeginDocument} after loading this package.
1228
1229 \subsection{Programmer's interface}
1230
1231 (Tentative and under construction.)
1232 If you are writing some code that needs to know the current
1233 maths style (\cs{mathbf}, \cs{mathit}, etc.), you can query the
1234 variable \cs{l_@@_mathstyle_tl}. It will contain the maths style
1235 without the leading `math' string; for example,
1236 |\symbf { \show \l_@@_mathstyle_tl }|
1237 will produce `bf'.
1238
1239 \endinput
1240
1241 % /©
1242 %
1243 % ------------------------------------------------
1244 % The UNICODE-MATH package <wspr.io/unicode-math>
1245 % ------------------------------------------------
1246 % This package is free software and may be redistributed and/or modified under
1247 % the conditions of the LaTeX Project Public License, version 1.3c or higher
1248 % (your choice): <http://www.latex-project.org/lppl/>.
1249 % ------------------------------------------------
1250 % Copyright 2006-2019 Will Robertson, LPPL "maintainer"
1251 % Copyright 2010-2017 Philipp Stephani
1252 % Copyright 2011-2017 Joseph Wright
1253 % Copyright 2012-2015 Khaled Hosny
1254 % ------------------------------------------------
1255 %
1256 % ©/