Undocumented use of the `BoldFont` option?

[Zeta611]

Description

BoldFont = options seems to work, but the documentation does not mention about it. Is this working as intended, or should not work properly?

Add info or delete as appropriate:

I see that there are people do use this option, e.g., here.

Minimal example demonstrating the issue

\documentclass{article}
\usepackage{unicode-math}
\setmathfont{XITSMath-Regular.otf}[
  BoldFont = XITSMath-Bold.otf,
]
\begin{document}
\[
  a = b
\]
\end{document}

does this work the same as the following?

\documentclass{article}
\usepackage{unicode-math}
\setmathfont{XITSMath-Regular.otf}
\setmathfont{XITSMath-Bold.otf}[range={bfup->up,bfit->it}]
\begin{document}
\[
  a = b
\]
\end{document}

Further details

Only the latter use-case is described in the documentation.

[khaledhosny]

BoldFont works with \mathversion[bold], in cases where all the math formula should be bold not only the alphabetic symbols.

[Zeta611]

@khaledhosny Thank you for the reply! Are you saying that the bold font specified by BoldFont is only used when the \mathversion{bold} is invoked, and will not be used with commands like \symbf?

[khaledhosny]

Exactly (and \boldmath which I think is a shortcut for \mathversion{bold}). \symbf switch to the Unicode bold math alphabets, so works only on characters that have encoded bold versions.

[hvoss49]

\documentclass{article}
\usepackage{unicode-math}
\setmathfont{XITSMath-Regular.otf}
\setmathfont{XITSMath-Bold.otf}[version=bold]
\begin{document}
	\[ a = b \]

	\[ \symbf{a = b} \]

	\[ \symbfit{a = b} \]
	
\mathversion{bold}
	\[ a = b \]
\end{document}

[jfbu]

I was going to open some new issue but will cuckoo here. (for reasons explained at the end, I may be not os eager for my issue to be solved).

The bold math version default appears to not be coherent.

\documentclass{article}
\usepackage{fontspec}
\setmainfont{TeX Gyre Termes}
\usepackage{unicode-math}
\setmathfont{XITS Math}
\begin{document}
\makeatletter
\meaning\mv@normal

\meaning\mv@bold

\clearpage
$a \mathrm{a} \mathbf{a}$

\mathversion{bold}

$a \mathrm{a} \mathbf{a}$

\thispagestyle{empty}
\showoutput
\end{document}
% Local variables:
% TeX-engine: xetex
% End:

(my system has symlinks targeting the texmfdist/fonts to help xetex find fonts)

We see in math version normal:

\install@mathalphabet \mathrm {\select@group \mathrm \M@TU \TU/TeXGyreTermes(0)/m/n }
\install@mathalphabet \mathbf {\select@group \mathbf \M@TU \TU/TeXGyreTermes(0)/b/n }

versus in math version bold

\install@mathalphabet \mathrm {\select@group \mathrm \M@OT1 \TU/XITSMath(1)/b/n }
\install@mathalphabet \mathbf {\select@group \mathbf \M@OT1 \OT1/cmr/bx/n }

This makes for very surprising behavior of \boldsymbol.

Now discovering the BoldFont option in this issue I obtain in math version bold, using

\setmathfont{XITSMath-Regular.otf}
\setmathfont{XITSMath-Bold.otf}[version=bold]

the following:

\install@mathalphabet \mathrm {\select@group \mathrm \M@OT1 \TU/XITSMath-Bold.otf(1)/m/n }
\install@mathalphabet \mathbf {\select@group \mathbf \M@OT1 \OT1/cmr/bx/n }

and is \TU/XITSMath-Bold.otf(1)/m/n really different from \TU/XITSMath(1)/b/n ?

Also I don't know if the \M@OT1 pieces are worrrying.

My pre-conception (maybe from having done mathastext for pdflatex ten years ago) is that any change to \mv@normal must be paired if possible with a change in \mv@bold so this why I feel the \mv@bold is wrong.

On the other hand it gives a me a trick to solve some problems with hat accent. Try

\[\hat{a}_r, \mathrm{\hat{a}_s}, \mathbf{\hat{a}_t}, \boldsymbol{\hat{a}_u},
\boldsymbol{\mathrm{\hat{a}_s}}\]

(in normal math version)

So here I am abusing the fact that in the bold math version the effect of \mathrm will be for input a to become MATHEMATICAL BOLD SMALL A, which is upright. And the hat is correctly positioned.

With lualatex things look better (which surprised me, I will explain next why):

I was very surprised but turns out my real-life original had

\usepackage{polyglossia}
\setmainlanguage{english}

which causes the following output:

xelatex:

lualatex