Referring to other packages when using tcolorbox/documentation

[mikkelee]

I'm writing docs for one of my packages & have found a need to refer to other packages. I don't see a standard way of doing this in the tcolorbox documentation section, so I cooked up the below by copying the reference format from tcbdocumentation.code.tex line 915. Perhaps others find it useful:

\makeatletter
\newcommand\refPkg[1]{%
  \href{https://ctan.org/pkg/#1}{%
    \refAux{#1}%
    \kvtcb@doc@format@page{{\fontfamily{pzd}\fontencoding{U}\fontseries{m}\fontshape{n}\selectfont\char213}%
    \,CTAN}%
  }%
}
\makeatother

Example usage: The box can be further configured via \docAuxCommand*{tcbset} as per the \refPkg{tcolorbox} documentation. will create a href pointing to https://ctan.org/pkg/tcolorbox that looks like this:

[muzimuzhi]

Nice extension!

Just to remind that for some LaTeX packages (<latex-pkg>.sty files), their CTAN names are not directly <latex-pkg>. See a list of mapping here (not sure if comprehensive).

[mikkelee]

Thanks :)

Perhaps an optional argument:

\documentclass{article}

\usepackage{tcolorbox}
\tcbuselibrary{documentation}

\makeatletter
\NewDocumentCommand \refPkg { o m } {%
  \IfValueTF{#1}{%
    \href{https://ctan.org/pkg/#1}%
  }{%
    \href{https://ctan.org/pkg/#2}%
  }{%
    \refAux{#2}%
    \kvtcb@doc@format@page{{\fontfamily{pzd}\fontencoding{U}\fontseries{m}\fontshape{n}\selectfont\char213}% from tcbdocumentation.code.tex line 915
    \,CTAN}%
  }%
}
\makeatother

\begin{document}

The box can be further configured via \docAuxCommand*{tcbset} as per the \refPkg{tcolorbox} documentation.

Linking to a .sty file in a differently named CTAN distribution: \refPkg[preprint]{fullpage}.

\end{document}

e: oh, I guess this one actually has ctan pages for the sub-packages (picked it randomly from the json doc): https://ctan.org/pkg/fullpage

[muzimuzhi]

Tip: In \NewDocumentCommand,

The default for O, D and E arguments can be the result of grabbing another argument.

_{texdoc usrguide (2024-05-24), sec. 2.5 Optional Arguments}

so the definition of \refPkg can be simplified to

\makeatletter
\NewDocumentCommand \refPkg { O{#2} m } {%
  \href{https://ctan.org/pkg/#1}%
  {%
    \refAux{#2}%
    \kvtcb@doc@format@page{{\fontfamily{pzd}\fontencoding{U}\fontseries{m}\fontshape{n}\selectfont\char213}% from tcbdocumentation.code.tex line 915
    \,CTAN}%
  }%
}
\makeatother

[mikkelee]

Oh nice, that's good to know!

[T-F-S]

I like this addition very much and I will integrate it as is into the next version. Thank you 👍

[mikkelee]

Thanks to you as well, looking forward to it :)

[T-F-S]

Done with https://github.com/T-F-S/tcolorbox/releases/tag/v6.4.0

[muzimuzhi]

It seems to me that the "CTAN" in small size (in Computer Modern/Latin Modern Roman) doesn't look very well (see for instance #302 (comment)), maybe \texttt{CTAN} or \textsf{CTAN} can improve readability a bit.

Example used to produce the screenshot above

\documentclass{article}
\usepackage{tcolorbox}
\tcbuselibrary{documentation}
\hypersetup{colorlinks}

\makeatletter
\RenewDocumentCommand \refPkg { O{#2} m } {%
  \href{https://ctan.org/pkg/#1}%
  {%
    \refAux{#2}%
    \kvtcb@doc@format@page{{\fontfamily{pzd}\fontencoding{U}\fontseries{m}\fontshape{n}\selectfont\char213}%
    \,\formatCTAN{CTAN}}%
  }%
}
\makeatother

\NewDocumentCommand{\formatCTAN}{m}{#1}

\begin{document}
rmfamily \refPkg{tcolorbox}

\let\formatCTAN=\texttt
ttfamily \refPkg{tcolorbox}

\let\formatCTAN=\textsf
sffamily \refPkg{tcolorbox}
\end{document}

[dbitouze]

@muzimuzhi I guess it is in small caps, not in small size.

[muzimuzhi]

@dbitouze It's controlled by /tcb/page ref formatter whose initial value is \textsuperscript, so "CTAN" has the baseline and size of script math. Redefining \refPkg to using lowercase letters then the page ref shows lowercase letters, so it's not in small caps.

[T-F-S]

Beauty is in the eye of the beholder... I will add a customization for formatting the CTAN string in the next version: