Improve zref-clever support

[gusbrs]

Hi @T-F-S,

I'm revisiting the support you kindly added for zref and zref-clever (#206), and I think I have an idea for a slight improvement of things.

I'd like to suggest using the reftype option instead of countertype. I know, it was my own suggestion to do otherwise when we originally discussed this. My argument to make that recommendation then was that reftype would apply to any other \zlabel made within the box's environment, which is true. But I think my reasoning was somewhat skewed because I started from the assumption that the option and the label would (potentially) be done at different places. However, the way you ended up implementing things, these two things are done at the same place: \__tcobox_label_zlabel:n. Which makes for an easy solution to the problem which made us rule out reftype, just add a group.

I see two advantages of so doing. First, reftype is an exact equivalent of cleveref's optional argument for \label. So you no longer have to worry about documentation ambiguities, or slight differences of behavior depending on the "reference backend". Second, it would work for phantomlabel too, which is currently not covered.

The implementation could look like:

\cs_new_protected:Npn \__tcobox_zcsetup_reftype:n #1
  {
    \cs_if_exist:NT \zcsetup
      {
        \zcsetup { reftype={#1} }
      }
  }

\cs_new_protected:Npn \__tcobox_label_zlabel:n #1
  {
    \group_begin:
    \quark_if_nil:NF \l__tcobox_kv_labeltype_tl
      {
        \exp_args:NV \__tcobox_zcsetup_reftype:n \l__tcobox_kv_labeltype_tl
      }
    \cs_if_exist:NT \zlabel
      {
        \zlabel {#1}
      }
    \group_end:
  }

A test document for it:

\documentclass{article}

\usepackage{tcolorbox}
\tcbuselibrary{theorems}

\usepackage{zref-titleref}
\usepackage{zref-clever}
\usepackage{hyperref}


\ExplSyntaxOn
\makeatletter
\cs_new_protected:Npn \__tcobox_zcsetup_reftype:n #1
  {
    \cs_if_exist:NT \zcsetup
      {
        \zcsetup { reftype={#1} }
      }
  }

% \cs_new_protected:Npn
\cs_set_protected:Npn \__tcobox_label_zlabel:n #1
  {
    \group_begin:
    \quark_if_nil:NF \l__tcobox_kv_labeltype_tl
      {
        \exp_args:NV \__tcobox_zcsetup_reftype:n \l__tcobox_kv_labeltype_tl
      }
    \cs_if_exist:NT \zlabel
      {
        \zlabel {#1}
      }
    \group_end:
  }
\makeatother
\ExplSyntaxOff


\newtcolorbox[auto counter,number within=section]{pabox}[2][]{%
  colback=red!5!white,colframe=red!75!black,fonttitle=\bfseries,
  label type=example,
  title=Examp.~\thetcbcounter: #2,#1}

\newtcolorbox[use counter from=pabox]{pabox2}[2][]{%
  colback=red!5!white,colframe=red!75!black,fonttitle=\bfseries,
  label type=solution,
  title=Examp.~\thetcbcounter: #2,#1}

\newcounter{extracounter}

% A custom type
\newtcolorbox[%
  use counter=extracounter,
  number within=section,
  ]{mypabox}[2][]{%
  colback=red!5!white,colframe=red!75!black,fonttitle=\bfseries,
  label type=myexample,
  title=Myexample~\thetcbcounter: #2,#1}

\zcRefTypeSetup{myexample}{
  % that which crefname/Crefname would provide:
  Name-sg=Myexample,
  name-sg=myexample,
  Name-pl=Myexamples,
  name-pl=myexamples,
  % and more, e.g.:
  reffont=\bfseries,
  refbounds={(,,,)},
  refbounds-first-sg={,(,),},
}

\newtcbtheorem[number within=section]{mytheo}{My Theorem}%
  {colback=green!5,colframe=green!35!black,fonttitle=\bfseries,
   label type=mytheorem}{th}

\zcRefTypeSetup{mytheorem}{
  % that which crefname/Crefname would provide:
  Name-sg=Mytheorem,
  name-sg=mytheorem,
  Name-pl=Mytheorems,
  name-pl=Mytheorems,
  % and more, e.g.:
  %reffont=\bfseries,
  %refbounds={(,,,)},
  %refbounds-first-sg={,(,),},
}

\tcbset{label is zlabel}

\begin{document}

\section{Foo bar}
\zlabel{sec:section-1}

\begin{pabox}[label={myautocounter},nameref={Bar Baz}]{Title with number}
  This box is automatically numbered with \zcref{myautocounter} on
  \zcpageref{myautocounter}. Inside the box, the \thetcbcounter\ can also be
  referenced by |\thetcbcounter|.  The real counter name is
  \texttt{\tcbcounter}. \zcref[ref=title]{myautocounter}.
\end{pabox}

\begin{pabox}[label={typedlabel},label type=solution]{Title with number}
  This box is automatically numbered with \zcref{typedlabel} on
  \zcpageref{typedlabel}. Inside the box, the \thetcbcounter\ can also be
  referenced by |\thetcbcounter|.  The real counter name is
  \texttt{\tcbcounter}.
\end{pabox}

\begin{pabox2}[label={sharedlabel}]{Title with number}
  This box is automatically numbered with \zcref{sharedlabel} on
  \zcpageref{sharedlabel}. Inside the box, the \thetcbcounter\ can also be
  referenced by |\thetcbcounter|.  The real counter name is
  \texttt{\tcbcounter}.
\end{pabox2}

\begin{mypabox}[label={customtype}]{Title with number}
  This box is automatically numbered with \zcref{customtype} on
  \zcpageref{customtype}. Inside the box, the \thetcbcounter\ can also be
  referenced by |\thetcbcounter|.  The real counter name is
  \texttt{\tcbcounter}.
\end{mypabox}

\begin{pabox}[label={xtypedlabel}]{Title with number}
  This box is automatically numbered with \zcref{xtypedlabel} on
  \zcpageref{xtypedlabel}. Inside the box, the \thetcbcounter\ can also be
  referenced by |\thetcbcounter|.  The real counter name is
  \texttt{\tcbcounter}.
\end{pabox}

\newcounter{othercounter}
\zcsetup{countertype={othercounter=footnote}}

\begin{pabox}[label={ytypedlabel},label type=myexample]{Title with number}
  This box is automatically numbered with \zcref{ytypedlabel} on
  \zcpageref{ytypedlabel}. Inside the box, the \thetcbcounter\ can also be
  referenced by |\thetcbcounter|. The real counter name is
  \texttt{\tcbcounter}.
  \refstepcounter{othercounter}\zlabel{other1}
  Other reference is \zcref{other1}.
\end{pabox}


\begin{pabox}[label={ztypedlabel},label type=myexample]{Title with number}
  This box is automatically numbered with \zcref{ztypedlabel} on
  \zcpageref{ztypedlabel}. Inside the box, the \thetcbcounter\ can also be
  referenced by |\thetcbcounter|.  The real counter name is
  \texttt{\tcbcounter}.
  \refstepcounter{othercounter}\zlabel{other2}
  Other reference is \zcref{other2}.
\end{pabox}

\begin{tcolorbox}[label={dummy},label type=myexample]
Some box \zcref{dummy}.
\end{tcolorbox}

\begin{mytheo}{This is my title}{theoexample}
  This is the text of the theorem. The counter is automatically assigned and,
  in this example, prefixed with the section number. This theorem is numbered with
  \zcref[cap]{th:theoexample}, it is given on \zcpageref{th:theoexample},
  and it is titled ``\ztitleref{th:theoexample}''.
\end{mytheo}

\begin{mytheo*}[phantomlabel={theosolution},label type=solution]{Solution title}
  This is the text of the theorem. This theorem is unnumbered, but we can
  reference its type name correctly: \zcref[cap,noref]{theosolution}.  And it
  is given on \zcpageref{theosolution}.
\end{mytheo*}

\end{document}

(Btw, that last box, which I added to illustrate the handling of phantomlabel in an unnumbered box, throws an ugly error with the current standing of things: "LaTeX Error: Blank key name in key-value input on line 163". I'm not sure why it happens. But anyway, the proposed improvement seems to fix it as well.)

WDYT?

[muzimuzhi]

Btw, that last box, which I added to illustrate the handling of phantomlabel in an unnumbered box, throws an ugly error with the current standing of things: "LaTeX Error: Blank key name in key-value input on line 163".

Can't reproduce the error, using texlive 2023 and updated packages, even without the proposed improvement.

[gusbrs]

Hi @muzimuzhi

Can't reproduce the error, using texlive 2023 and updated packages, even without the proposed improvement.

Thanks for checking. I'm actually relieved, since I find it strange and that "it shouldn't happen". So, better if it's just me. But I'm also running an up to date TeX Live 2023, and just checked I was not getting anything from my ~/texmf/ directory so, as far as I can tell, I'm running on a clean environment. And I do get the error every time. Also not aux file related, since I tested cleaning everything as well. The error I get (with that document, just removing the \ExplSyntax part) is:

./test doc.tex:163: Use of \??? doesn't match its definition.
<argument> \???  
                 ! LaTeX Error: Blank key name in key-value input on line 163
l.163 ...ion},label type=solution]{Solution title}
                                                  
If you say, e.g., `\def\a1{...}', then you must always
put `1' after `\a', since control sequence names are
made up of letters only. The macro here has not been
followed by the required stuff, so I'm ignoring it.

[muzimuzhi]

with that document, just removing the \ExplSyntax part

Ohhh now I can see the same error. 🥲 I'll dig into this.

[gusbrs]

with that document, just removing the \ExplSyntax part

Ohhh now I can see the same error. smiling_face_with_tear I'll dig into this.

That's what I had meant by "current standing of things". 😉

[muzimuzhi]

In starred tcb theorem, \tcbcounter is let to empty, but \__tcobox_label_zlabel:n only checks if \tcbcounter is defined. Hence \zcsetup { countertype={<counter>={<label type>}} } is called with empty <counter>, which throws the error ! LaTeX Error: Blank key name in key-value input.

Related source lines

tcolorbox/tex/latex/tcolorbox/tcolorbox.sty

Lines 2167 to 2169 in 67963e2

	\def\tcb@proc@counter@no#1{%
	\appto\tcb@new@colopt{,code={\let\tcbcounter=\@empty\let\thetcbcounter=\@empty}}%
	}%

tcolorbox/tex/latex/tcolorbox/tcolorbox.sty

Lines 890 to 912 in 67963e2

	\cs_new:Npn \__tcobox_zcsetup_countertype:nn #1#2
	{
	\cs_if_exist:NT \zcsetup
	{
	\zcsetup { countertype={#1={#2}} }
	}
	}
	\cs_new:Npn \__tcobox_label_zlabel:n #1
	{
	\quark_if_nil:NF \l__tcobox_kv_labeltype_tl
	{
	\cs_if_exist:NT \tcbcounter
	{
	\exp_args:NVV \__tcobox_zcsetup_countertype:nn \tcbcounter \l__tcobox_kv_labeltype_tl
	}
	}
	\cs_if_exist:NT \zlabel
	{
	\zlabel { #1 }
	}
	}

With the proposed improvement by @gusbrs,

• \__tcobox_label_zlabel:n checks if \l__tcobox_kv_labeltype_tl is defined instead of \tcbcounter and
• \__tcobox_zcsetup_reftype:n (renamed from \__tcobox_zcsetup_countertype:nn) calls \zcsetup { reftype={<label type>} }, instead of \zcsetup { countertype={<counter>={<lable type>}} }.

Therefore the error is never triggered. I'm not familiar with zref bundle, hence not able to review the improvement itself.

[gusbrs]

In starred tcb theorem, \tcbcounter is let to empty, but \__tcobox_label_zlabel:n only checks if \tcbcounter is defined. Hence \zcsetup { countertype={<counter>={<label type>}} } is called with empty <counter>, which throws the error ! LaTeX Error: Blank key name in key-value input.

Ah, makes sense. It should be tested for emptiness. Thanks for looking into this.

With the proposed improvement by @gusbrs,

• \__tcobox_label_zlabel:n checks if \l__tcobox_kv_labeltype_tl is defined instead of \tcbcounter and

• \__tcobox_zcsetup_reftype:n (renamed from \__tcobox_zcsetup_countertype:nn) calls \zcsetup { reftype={<label type>} }, instead of \zcsetup { countertype={<counter>={<lable type>}} }.

Therefore the error is never triggered.

Sounds like a third reason for the suggested improvement. Or "second and a half". ;-)

[T-F-S]

The discussion clearly reveals that this is a really an improvement. I see nothing what speaks against it and I will add it to the next tcolorbox version.

Thank you both.

[gusbrs]

@T-F-S Once again, thank you very much.

@muzimuzhi Thank you too.

[T-F-S]

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

[gusbrs]

@T-F-S Thank you!