Convenience feature: environment upper = description etc.

[mgkurtz]

For my own use, I defined keys environment upper and environment upper args as well as their lower equivalents for usage such as

\begin{tcolorbox}[
    environment upper args = {description} { \setlength\itemsep{0pt} \setlength\parsep{0pt} },
    environment lower = pseudo,
    title = Random sort
]
    \item[Input] a list $l$
    \item[Output] the same list, now sorted
    \item[Performance] hilarious
\tcblower
    \kw{repeat} \\+
        shuffle($l$) \\-
    \kw{until} issorted($l$) \\
    \kw{return} $l$
\end{tcolorbox}

For me, such usage feels more natural than setting before upper*, after upper*, before lower*, and after lower*. Your mileage may vary.

Implementation

\tcbset {
	__environment / .style~n~args = 3 {
		before~#1* = { \begin {#2} #3 }
		, after~#1* = \end {#2}
	}
	, environment~upper / .value~required
	, environment~lower / .value~required
	, environment~title / .value~required
	, environment~upper / .style = { __environment = { upper } {#1} { } }
	, environment~lower / .style = { __environment = { lower } {#1} { } }
	, environment~title / .style = { __environment = { title } {#1} { } }
	, environment~upper~args / .style~2~args = { __environment = { upper } {#1} {#2} }
	, environment~lower~args / .style~2~args = { __environment = { lower } {#1} {#2} }
	, environment~title~args / .style~2~args = { __environment = { title } {#1} {#2} }
}

[T-F-S]

Thank you for this feature proposal. Currently, I am very busy, but I will look into it in some days.

[T-F-S]

I think this is a nice new shortcut feature and I will add it to the next version. Thank you!

[muzimuzhi]

Maybe it's worth mentioning in doc that environment upper and friends cannot be used to wrap upper/lower/title in another tcolorbox-based environment.

That is,

\documentclass{article}
\usepackage{tcolorbox}

\newtcolorbox{mybox}[1][]{#1}
\begin{document}
% ! LaTeX Error: \begin{mybox} on input line 7 ended by \end{tcolorbox}.
\begin{tcolorbox}[environment upper={mybox}]
  content
\end{tcolorbox}

% ! LaTeX Error: \begin{tcolorbox} on input line 12 ended by \end{mybox}.
\begin{mybox}[environment upper={tcolorbox}]
  content
\end{mybox}
\end{document}

[muzimuzhi]

Many options function by setting before upper(*) and after upper(*), thus they compete with each other and only the last one wins.

For upper part, there are (no guarantee of completeness)

• in main package:
  • attach title to upper
  • tabularx(*), tabulars(*)
  • tikz upper, tikznode upper, tikznode
  • varwidth upper
  • text fill
• in documentation lib: ams equation(*) upper, math upper, ams align(*) upper, ams gather(*) upper, ams nodisplayskip upper
• in theorems lib: doc new, doc updated, doc new and updated

Two thoughts

• Do we need an additive version of environment upper and friends, perhaps in hooks library?
• Is it worth listing existing options that wrap upper or another part in an environment, with non-trivial extra code inserted?
  Several considerations:
  • make similar options mentioned in a single place
  • point out that not any environment can be set by environment upper, and when it's not totally impossible, some options are already provided with hacks to support frequently used envs (like varwidth, amsmath multiline math envs).

[mgkurtz]

• Is it worth listing existing options that wrap upper or another part in an environment, with non-trivial extra code inserted?
  Several considerations:

  • make similar options mentioned in a single place
  • point out that not any environment can be set by environment upper, and when it's not totally impossible, some options are already provided with hacks to support frequently used envs (like varwidth, amsmath multiline math envs).

Good idea. Perhaps even better: instead of writing this in the docs, we can also write it into the code. So that environment upper = align ends up as ams align upper. One consistent interface up front and many hacks beyond.

[muzimuzhi]

@mgkurtz Nice idea! Though I'm afraid not all such options should be auto ended up as.

This is the case for /tcb/tabularx(*) and /tcb/tabular(*): current /tcb/environment upper args already works for such tabular envs, while the special options adjust geometry in addition to make the table just embedded into the upper.

\PassOptionsToPackage{table}{xcolor}
\documentclass{article}
\usepackage{array}
\usepackage{tcolorbox}

\tcbset{colframe=red!50!black}

\begin{document}
\def\testWrapUpperInTabular#1{%
  \hspace*{-2\parindent}{\ttfamily\detokenize{#1}}
  \begin{tcolorbox}[#1]
    \hline
    a   &   b \\
    aa  &  bb \\
    aaa & bbb \\ \hline
  \end{tcolorbox}
}

\testWrapUpperInTabular{environment upper args = {tabular}{{|l|r|}}}
\testWrapUpperInTabular{environment upper args = {tabular*}
  {{\linewidth}{|@{\extracolsep{\fill}\hspace{20mm}}l|r@{\hspace{20mm}}|}}}

\testWrapUpperInTabular{tabulars =
  {|@{\extracolsep{\fill}\hspace{20mm}}l|r@{\hspace{20mm}}|}}
\end{document}

[T-F-S]

Maybe it's worth mentioning in doc that environment upper and friends cannot be used to wrap upper/lower/title in another tcolorbox-based environment.

I will add such a warning. Thank you!

[T-F-S]

• Do we need an additive version of environment upper and friends, perhaps in hooks library?

That may be useful. Such extensions are provided for before upper etc inside the hooks library. I will look into it.

[T-F-S]

Is it worth listing existing options that wrap upper or another part in an environment, with non-trivial extra code inserted?
Several considerations:

* make similar options mentioned in a single place

* point out that not any environment can be set by `environment upper`, and when it's not totally impossible, some options are already provided with hacks to support frequently used envs (like `varwidth`, `amsmath` multiline math envs).

No, I do not think so. Beginning to cross-reference everything to everything would just open dependency hell for every change. And putting all in one place is already done with 4.11 Box Content Additions for the core options. Other options are from the libraries.

[T-F-S]

@mgkurtz Nice idea! Though I'm afraid not all such options should be auto ended up as.

This is the case for /tcb/tabularx(*) and /tcb/tabular(*): current /tcb/environment upper args already works for such tabular envs, while the special options adjust geometry in addition to make the table just embedded into the upper.

I also consider such an approach to be nice, but not applicable or too complicated. Some hacks are very special and possible more may come in future.

[T-F-S]

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