Improve error message thrown by \tcblower

[muzimuzhi]

Just a small improvement.

Although it's already documented that

A \tcbox cannot have a lower part and cannot be broken.

a low-level "Undefined control sequence ... \tcblower" error raised by using \tcbox{... \tcblower ...} may still make new users lost for a while.

Therefore I suggest to define \tcblower in \tcb@ox (\tcbox is a thin wrapper around it by specifying the capture mode) to give a more helpful error message.

\documentclass{article}
\usepackage{tcolorbox}

\makeatletter
\long\def\tcb@ox#1#2{%
  \begingroup%
  \tcb@layer@inc%
  \tcb@apply@box@options{#1,breakable@false,sidebyside@false}\tcb@height@adjust%
  \let\tcblower\tcb@error@nolower% <<< added here
  \csname tcbox@inner@\kvtcb@capture\endcsname{#2}%
  \tcb@layer@dec%
  \endgroup%
}

\def\tcb@error@nolower{\tcb@error{%
  % or more bluntly, \tcblower cannot be used in \tcbox and friends
  \string\tcbox\space and friends cannot have a lower part.
  I'll drop this `\string\tcblower'}{}}
\makeatother

\begin{document}
\tcbox{box content \tcblower lower part}
\end{document}

The raised error

! Package tcolorbox Error: \tcbox and friends cannot have a lower part. I'll drop this `\tcblower'.

[T-F-S]

I will add something quite similar to \tcb@apply@box@options instead of \tcb@ox to display such an error message.

[muzimuzhi]

After some more digging, I find that for the in total six box + capture mode combinations (box can be one of tcolorbox, or tcbox and capture mode can be one of minipage, hbox, and fitbox mode), only tcolorbx + minipage supports use of \tcblower hence defines it. Therefore similar informative error message is needed by all other 5 cases, including the two tcolorbox + hbox and tcolorbox + fitbox.

But in \tcb@apply@box@options it may be too late to have sufficient info (not 100% sure) to tell whether it is called by a tcolorbox, a tcbox, or a tcbfitbox (which for \tcblower issue is the same as tcbox). Prompting "\tcblower is not supported in \tcbox/\tcbfitbox" for use \begin{tcolorbox}[capture=hbox] upper \tcblower lower \end{tcolorbox} is wrong.

Possible (mutually replaceable) solutions:

1. Change the error message to an inverse proposition: "\tcblower is only supported for tcolorbox and derived environments with capture mode minipage."
2. Add an inner macro to record the box type and use it in \tcblower@error.
3. Provide (for the tcolorbox + minipage case, move) definitions to \tcblower to the six \tcb@@capture@<mode> and \tcbox@inner@<mode> macros. But since \tcb@@capture@(hbox|fitbox) will eventually call the corresponding \tcbox@inner@<mode>, some check like \ifdefined\tcblower\else \let\tcblower= \tcblower@error \fi is needed.

[T-F-S]

After some more digging, I find that for the in total six box + capture mode combinations (box can be one of tcolorbox, or tcbox and capture mode can be one of minipage, hbox, and fitbox mode), only tcolorbx + minipage supports use of \tcblower hence defines it. Therefore similar informative error message is needed by all other 5 cases, including the two tcolorbox + hbox and tcolorbox + fitbox.

Yes, that's why I moved the error message away from \tcb@ox

But in \tcb@apply@box@options it may be too late to have sufficient info (not 100% sure) to tell whether it is called by a tcolorbox, a tcbox, or a tcbfitbox (which for \tcblower issue is the same as tcbox). Prompting "\tcblower is not supported in \tcbox/\tcbfitbox" for use \begin{tcolorbox}[capture=hbox] upper \tcblower lower \end{tcolorbox} is wrong.

I think, \tcb@apply@box@options is a good location since it is called for every box. I agree to add a helpful error message, but individualizing it for every possible combination is too much effort in my eyes. So, my solution is a general message:

\def\tcb@error@nolower{\tcb@error{%
  \string\tcblower\space cannot be used for \string\tcbox, \string\tcboxfit, and similar box macros,
  also not for capture=hbox, capture=fitbox, etc.
  I'll drop this `\string\tcblower'}{}}

\long\def\tcb@apply@box@options#1{%
  \let\tcb@space\tcb@zpt%
  \let\tcb@outer@textheight\tcbtextheight%
  \let\tcbtextheight\tcb@zpt%
  \let\tcbtextwidth\tcb@zpt%
  \tcbset{#1}%
  \tcb@lateoptions@hook\let\tcb@lateoptions@hook\@empty%
  \tcb@afteroptions@hook%
  \iftcb@isbreakable%
    \tcb@init@breakable%
  \else%
    \tcb@init@unbreakable%
  \fi%
  \let\iftcb@minipage\if@minipage%
  \let\iftcb@nobreak\if@nobreak%
  \let\tcblower\tcb@error@nolower%
}

[T-F-S]

Added to https://github.com/T-F-S/tcolorbox/releases/tag/v6.0.2