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}