Trouble with `documentation` library and superiors

[dbitouze]

Users may wish to use:

• superiors and inferiors (specially-drawn glyphs for superscript and subscript text), provided by more and more OpenType fonts (and this is possible with (La)TeX thanks to the realscript package),
• the documentation tcolorbox's library and, among others, its \refCom command.

They'll be in trouble since real superiors provided are generally only digits and lowercase letters (and in particular not arrows, capitals nor dots), as the following MCE points out:

\documentclass[varwidth]{standalone}
\usepackage{fontspec}
\usepackage{tcolorbox}
\usepackage{realscripts}

\tcbuselibrary{documentation}

\begin{document}
\begin{itemize}
\item The \refCom{foo} command is an interesting one!\footnote{Here Latin Modern
    font which doesn't provide superiors.}
  %
  \setmainfont{STIXTwoText-Regular.otf}
\item The \refCom{foo} command is an interesting one!\footnote{Here STIX 2 font
    which provides superiors.}
\end{itemize}

\setcounter{page}{2}

\begin{docCommand}{foo}{}
Foo.
\end{docCommand}
\end{document}

As a (poor man's) workaround, one could detect realscripts at \begin{document} and in this case use, not \textsuperscript, but its \fakesuperscript command.

[muzimuzhi]

Exposing the \textsuperscript as a new formatter option (for example /tcb/page ref formatter=<formatter command>) could be an alternative.

% !TeX program = xelatex
\documentclass[margin=10pt, varwidth]{standalone}
\usepackage{fontspec}
\usepackage{tcolorbox}
\usepackage{realscripts}

\tcbuselibrary{documentation}
\hypersetup{colorlinks}

\makeatletter
\tcbset{
  page ref formatter/.code={\let\kvtcb@doc@format@page=#1},
  page ref formatter=\textsuperscript
}

\RenewDocumentCommand\tcb@ref@doc{msm}{%
  \hyperref[{#1:#3}]{\texttt{\ref*{#1:#3}}%
  \IfBooleanTF{#2}{}{%
    \ifnum\getpagerefnumber{#1:#3}=\thepage\relax%
    \else%
      \kvtcb@doc@format@page{{\fontfamily{pzd}\fontencoding{U}\fontseries{m}\fontshape{n}\selectfont\char213}%
      \,\kvtcb@text@pageshort\,\pageref*{#1:#3}}%
    \fi}}%
}
\makeatother

\begin{document}

\texttt{/tcb/page ref formatter=\string\textsuperscript\space(default)}
\begin{itemize}
\item The \refCom{foo} command is an interesting one!\footnote{Here Latin Modern
    font which doesn't provide superiors.}
  %
  \setmainfont{STIXTwoText-Regular.otf}
\item The \refCom{foo} command is an interesting one!\footnote{Here STIX 2 font
    which provides superiors.}
\end{itemize}

\texttt{/tcb/page ref formatter=\string\fakesuperscript}
\tcbset{page ref formatter=\fakesuperscript}
\begin{itemize}
\item The \refCom{foo} command is an interesting one!
  %
  \setmainfont{STIXTwoText-Regular.otf}
\item The \refCom{foo} command is an interesting one!
\end{itemize}

\setcounter{page}{2}

\begin{docCommand}{foo}{}
Foo.
\end{docCommand}
\end{document}

I'd say the effect of redefined \textsuperscript in realscripts is not as smart as expected. But that needs the ability to check if the glyph of some character will be influenced by specific OpenType feature and I doubt if that's possible in XeTeX (should be possible in LuaTeX). Even so the possibly alternating result won't please everyone.

Here \textsuperscript/\realsuperscript uses fontspec option VerticalPosition=Superior which then sets OpenType feature sups or sinf (or corresponding AAT feature) if such feature exists in current font.

[dbitouze]

What about a semi-automatic page ref formatter, like this:

\tcbset{
  page ref formatter/.code={\let\kvtcb@doc@format@page=#1}
}
\ltx@ifpackageloaded{realscripts}{%
  \tcbset{page ref formatter=\fakesuperscript}
}{
  \tcbset{page ref formatter=\textsuperscript}
}

[T-F-S]

I think the introduction of a page ref formatter is a good idea. Maybe, the formatter should also be responsible for the arrow symbol? A drawback would be that you have to add the arrow code when changing the formatter, but you gain freedom to use another symbol...

I am not familiar with realscripts, but from a glance into its documentation I figure that \textsuperscript is not overwritten (otherwise the issue would not be there) for some reason. So, I would also hesitate to an automatic or semi-automatic replacement and would go for the manual formatting approach.

[muzimuzhi]

realscripts does overwrite \textsuperscript{<text>}, but when setting fontspec option, it only checks if the underlying font feature exists in current font, no matter whether each character in <text> would be influenced by such feature or not.

So for \setmainfont{STIXTwoText-Regular.otf} \textsuperscript{<arrow>\,P.\,2}, although only the number 2 would be affected, since STIX 2 font provides the required feature, \textsuperscript expands to \realsuperscript which leaves <arror>\,P.\, in normal size, on normal baseline. In this sense, the use cases of realscripts are quite limited and sensitive to the fonts in use.

[dbitouze]

In this sense, the use cases of realscripts are quite limited and sensitive to the fonts in use.

One use case in kpfonts when used with (xe|lua)latex: it automatically loads realscripts.

[muzimuzhi]

@dbitouze That's unfortunate. It's kpfonts-otf that loads realscripts when it's configured to setup text fonts.

You may want to disable loading of realscripts (before loading kpfonts(-otf)) by using either the classic trick (see for example TeX-SX question #212499 asked in 2014)

\expandafter\csname realscripts.sty@ver\endcsname{}

or more recent \disable@package@load{<package>}{<alternate-code>} which is introduced in LaTeX2e 2020-10-01 and documented in texdoc ltfilehook-doc. (Update: I opened https://github.com/latex3/latex2e/issues/1292 in latex2e to ask its/their usability.)

Although documented in section 1.6 "Internal interfaces for LaTeX", according to its doc I infer \disable@package@load can be used by third-party classes.

[dbitouze]

@dbitouze That's unfortunate. It's kpfonts-otf that loads realscripts when it's configured to setup text fonts.

But, as I said above, more generally users may wish to use:

• superiors and inferiors when provided by the used OpenType font (and AFAIK, with (La)TeX, this is possible only thanks to the realscripts package),
• the documentation tcolorbox's library.