No linebreak with \refKey (tcolorbox documentation library)

Question

I currently try to document a LaTeX-package with several keys. When I use the internal tools of the tcolorbox documentation library, I get some ugly results.

\documentclass{scrartcl}
\usepackage{showframe}
\usepackage{tcolorbox}
\tcbuselibrary{documentation}

\begin{document}
\begin{docKey}[my/very/long/keypath]{myKey}{=\marg{value}}{}
    This is a very very very (very) very long description of the \refKey{/my/very/long/keypath/myKey}
\end{docKey}
\end{document}

This leads to which can definitely be improved.

Is there a way to only get the last part (the key itself) when referencing the key? Are there other ways to break the reference at line endings?

---

After some searching through the documentation, I found this part, which should be relevant for my question (lines 808 ff.):

\NewDocumentCommand\tcb@ref@doc{msm}{%
  \hyperref[#1:#3]{\texttt{\ref*{#1:#3}}%
  \IfBooleanTF{#2}{}{%
    \ifnum\getpagerefnumber{#1:#3}=\thepage\relax%
    \else%
      \textsuperscript{\ding{213}\,\kvtcb@text@pageshort\,\pageref*{#1:#3}}%
    \fi}}%
}

\def\refCom{\tcb@ref@doc{com}}
\def\refEnv{\tcb@ref@doc{env}}
\def\refKey{\tcb@ref@doc{key}}

What I probably need is a replacement for the \ref*{#1:#3} which extracts the last element of a /-separated list from the reference. But unfortunately I don't know, how I could achieve that.

Answer 1

For the question to get only the last part you can renew the docKey environment to add another label to the definition that prints only the key itself and not the path. In the MWE below the label is defined as */#1/\kvtcb@doc@label, so you can reference it by prefixing the key with *.

MWE:

\documentclass{scrartcl}
\usepackage{showframe}
\usepackage{tcolorbox}
\tcbuselibrary{documentation}

\makeatletter
\RenewDocumentEnvironment{docKey}{ O{} +O{} m m +m }{\tcbset{doc label={#3},#2,doc description={#5}}%
  \begin{tcb@manual@entry}%
  \begin{tcb@doc@head}{doc@head@key}%
  \ifblank{#1}{%
    \tcb@Print@Key{#3}\tcb@index@Key{#3}\protected@edef\@currentlabel{#3}\label{key:\kvtcb@doc@label}{\ttfamily #4}%
  }{%
    \tcb@Print@Key{/#1/#3}%
    \tcb@index@KeyPath{#1}{#3}\protected@edef\@currentlabel{/#1/#3}\label{key:/#1/\kvtcb@doc@label}%
    % ADDED LABEL DEFINITION HERE
    \protected@edef\@currentlabel{/#3}\label{key:*/#1/\kvtcb@doc@label}%
    {\ttfamily #4}%
  }%
  \tcb@doc@do@description%
  \end{tcb@doc@head}\nobreak\tcbset{before upper=}\kvtcb@doc@body@key@before\ignorespaces}%
  {\ifvmode\else\unskip\fi\kvtcb@doc@body@key@after\end{tcb@manual@entry}}
\makeatother

\begin{document}
\begin{docKey}[my/very/long/keypath]{myKey}{=\marg{value}}{}
    This is a very very very (very) very long description of the \refKey{/my/very/long/keypath/myKey}
    This is a very very very (very) very long description of the \refKey{*/my/very/long/keypath/myKey}
\end{docKey}
\end{document}

Result:

Note that this code was tested using tcolorbox v4.22. The most recent version (currently 4.42) has had a major rewrite for which the code in this answer does not work out of the box.

For breaking the long keys you can change the environment definition to use \slash instead of a literal /, which will allow line breaking on the slashes. Because this is a command (which is not allowed in labels) you should define the printed text (with the \slash commands) and the label text (with the literal /) separately using the doc label key from tcolorbox.

MWE:

\documentclass{scrartcl}
\usepackage{showframe}
\usepackage{tcolorbox}
\tcbuselibrary{documentation}

\makeatletter
\RenewDocumentEnvironment{docKey}{ O{} +O{} m m +m }{\tcbset{doc label={#3},#2,doc description={#5}}%
  \begin{tcb@manual@entry}%
  \begin{tcb@doc@head}{doc@head@key}%
  \ifblank{#1}{%
    \tcb@Print@Key{#3}\tcb@index@Key{#3}\protected@edef\@currentlabel{#3}\label{key:\kvtcb@doc@label}{\ttfamily #4}%
  }{%
    \tcb@Print@Key{/#1/#3}%
    \tcb@index@KeyPath{#1}{#3}\protected@edef\@currentlabel{\slash#1\slash#3}\label{key:\kvtcb@doc@label}%
    \protected@edef\@currentlabel{/#3}\label{key:*\kvtcb@doc@label}%
    {\ttfamily #4}%
  }%
  \tcb@doc@do@description%
  \end{tcb@doc@head}\nobreak\tcbset{before upper=}\kvtcb@doc@body@key@before\ignorespaces}%
  {\ifvmode\else\unskip\fi\kvtcb@doc@body@key@after\end{tcb@manual@entry}}
\makeatother

\begin{document}
\begin{docKey}[my\slash very\slash long\slash keypath][doc label=/my/very/long/keypath/myKey]{myKey}{=\marg{value}}{}
    This is a very very very (very) very long description of the \refKey{/my/very/long/keypath/myKey}
    
    This is a very very very (very) very long description of the \refKey{*/my/very/long/keypath/myKey}
\end{docKey}

\end{document}

Result:

Answer 2

Thanks to the answer of @Marijn, I was able to make the changes in the current version of tcolorbox and want to share them here:

\ExplSyntaxOn
\cs_gset:Npn \__tcobox_doc_head_key:
    {
        \__tcobox_print_key:
        \__tcobox_index_key:
        \tl_if_empty:NTF \kvtcb@doc@keypath
        {
            \seq_if_in:NVF \g__tcobox_label_seq \kvtcb@doc@label
            {
                \protected@edef\@currentlabel{\kvtcb@doc@name}
                \label{key:\kvtcb@doc@label}
                \seq_gput_left:NV \g__tcobox_label_seq \kvtcb@doc@label
            }
        }
        {
            \tl_set:Nx \l_tmpa_tl {/\kvtcb@doc@keypath/\kvtcb@doc@label}
            \seq_if_in:NVF \g__tcobox_label_seq \l_tmpa_tl
            {
                % define the short ref
                \protected@edef\@currentlabel{/\kvtcb@doc@name}
                \label{key:/\kvtcb@doc@keypath/\kvtcb@doc@label}
                % define the long one
                \protected@edef\@currentlabel{\slash\kvtcb@doc@keypath\slash\kvtcb@doc@name}
                \label{key:*/\kvtcb@doc@keypath/\kvtcb@doc@label}
                \seq_gput_left:NV \g__tcobox_label_seq \l_tmpa_tl
            }
        }
        {\ttfamily\kvtcb@doc@parameter}
        \tcb@doc@do@description
    }
\ExplSyntaxOff

This implements the long and short reference label as well as the line breaking functionality.