User-specified `graphical environment`

[muzimuzhi]

I noticed in v6.3.0 graphical environment is deprecated and its doc is removed. https://github.com/T-F-S/tcolorbox/blob/f7f39a4af09b6cce028c0e8e83d6c40f56d899d1/tex/latex/tcolorbox/tcolorbox.sty#L566

Although since v6.3.0 all tcolorbox skins use tikzpicture and never pgfpicture, users who specified different graphical environment, like graphical environment=circuitikz (provided by circuitikz package) may experience some breaking change.

No real use cases, just my guessing.

[T-F-S]

This observation is correct. But, I realized that all skins except standard do use a modified tikzpicture and not as previously documented tikzpicture only (some hooks added). Also, the main idea of having graphical environment was that the standard skin should be more light-weighted with pgfpicture. But, with all the overhead of tcolorbox, I think this idea is outdated.

So, the new version has a unified and cleaner setup with a fixed tikzpicture. Hope is, that possible tagging adations should be easier this way. The drawback is a possible user modification of graphical environment. My guess and hope is that this feature was never really used 'out there'.

[muzimuzhi]

But, I realized that all skins except standard do use a modified tikzpicture and not as previously documented tikzpicture only (some hooks added).

Oh it requires the graphical environment takes an optional argument and passes it to \begin{tikzpicture}[...], which may be too strong a requirement for derived environments. Unless, there's a tikz style every next picture={<tikz options>} which does something like

every next picture/.code={%
  every picture/.append code={%
    % backup code of /tikz/every picture
    \pgfkeysalso{#1}%
    % restore code of /tikz/every picture
  }%
}

[muzimuzhi]

My guess and hope is that this feature was never really used 'out there'.

To make such (now unsupported) uses be noticed, maybe graphical environment can now raise a warning. For example

\documentclass{article}
\usepackage{tcolorbox}
\tcbuselibrary{documentation} % for "/tcb/(before|after) example"

\makeatletter
\tcbset{
  graphical environment/.code={\tcb@warning@deprecatedkey{v6.3.0 (2024/07/10)}},
  before example/.code=       {\tcb@warning@deprecatedkey{v3.50 (2015/03/16)}},
  after example/.code=        {\tcb@warning@deprecatedkey{v3.50 (2015/03/16)}},
}

\def\tcb@warning@deprecatedkey#1{%
  % take a 2nd argument to give some suggestion like "see ... for more info" or "use ... instead"?
  \tcb@warning{`\pgfkeyscurrentkey' key is deprecated hence ignored since #1.}%
}
\makeatother

\begin{document}
\begin{tcolorbox}[graphical environment=tikzpicture]
  content
\end{tcolorbox}
\end{document}

[muzimuzhi]

And just in case, the value of \tcb@tikz@option@hook can be braced, just like the fix for #229. https://github.com/T-F-S/tcolorbox/blob/f7f39a4af09b6cce028c0e8e83d6c40f56d899d1/tex/latex/tcolorbox/tcolorbox.sty#L2047-L2050

diff --git a/tex/latex/tcolorbox/tcolorbox.sty b/tex/latex/tcolorbox/tcolorbox.sty
index 23f0d51..db75d96 100644
--- a/tex/latex/tcolorbox/tcolorbox.sty
+++ b/tex/latex/tcolorbox/tcolorbox.sty
@@ -2047,7 +2047,7 @@
 \NewDocumentEnvironment{ tcb@drawing }{ }
   {
     \use:c{ tcb@before@\tcb@split@state }
-    \exp_last_unbraced:NnNo \begin{tikzpicture}[\tcb@tikz@option@hook]
+    \exp_args:NnNo \begin{tikzpicture}[\tcb@tikz@option@hook]
     \UseTaggingSocket{tcb/drawing/begin}
     \SuspendTagging{tcb/drawing}
     \tcb@tikz@begin@hook
@@ -2061,7 +2061,7 @@
     \end{tikzpicture}
     \use:c{ tcb@after@\tcb@split@state }
   }
-
+\exp_args_generate:n {nNo} % generate \exp_args:NnNo
 \ExplSyntaxOff

[T-F-S]

To make such (now unsupported) uses be noticed, maybe graphical environment can now raise a warning.

Yes, this may be helpful also for future deprecactions.

[T-F-S]

And just in case, the value of \tcb@tikz@option@hook can be braced, just like the fix for #229.

Good point. It slipped my mind that bracing here is not bad, but even helpful. I will change this accordingly. Thank you!