summaryrefslogtreecommitdiff
path: root/macros/latex/contrib/tcolorbox/tcolorbox.doc.coreoptions.tex
diff options
context:
space:
mode:
Diffstat (limited to 'macros/latex/contrib/tcolorbox/tcolorbox.doc.coreoptions.tex')
-rw-r--r--macros/latex/contrib/tcolorbox/tcolorbox.doc.coreoptions.tex150
1 files changed, 133 insertions, 17 deletions
diff --git a/macros/latex/contrib/tcolorbox/tcolorbox.doc.coreoptions.tex b/macros/latex/contrib/tcolorbox/tcolorbox.doc.coreoptions.tex
index 9144696d2c..e20936d76b 100644
--- a/macros/latex/contrib/tcolorbox/tcolorbox.doc.coreoptions.tex
+++ b/macros/latex/contrib/tcolorbox/tcolorbox.doc.coreoptions.tex
@@ -4,7 +4,11 @@
\section{Option Keys}\label{sec:optkeys}%
\tcbset{external/prefix=external/coreoptions_}%
For the \meta{options} in \refEnv{tcolorbox} respectively \refCom{tcbset}
-the following |pgf| keys can be applied. The key tree path |/tcb/| is not to
+the following |pgf| keys can be applied%
+\footnote{Strictly speaking, they are \texttt{pgfkeys} keys.
+ The \texttt{pgfkeys} package is auto-loaded by \texttt{pgf} and is
+ documented in \cite[Part~VII]{tantau:tikz_and_pgf}.}.
+The key tree path |/tcb/| is not to
be used inside these macros. It is easy to add your own style keys using
the syntax for |pgf| keys, see \cite{tantau:tikz_and_pgf,sturm:latex} or the examples
starting from page~\pageref{sec:latextutorial}.
@@ -272,8 +276,10 @@ This is a \textbf{tcolorbox} (but invisible).
This is the counterpart of \refKey{/tcb/savelowerto}, but it saves not
only the upper part but the whole content. If a lower part is present,
it is also saved including \refCom{tcblower}.
+ An empty \meta{file name} deactivates \refKey{/tcb/saveto}.
\begin{marker}
- This option cannot be combined with \refKey{/tcb/savelowerto}.
+ This option cannot be combined with \refKey{/tcb/savelowerto} or
+ \refKey{/tcb/redirectlowerto}.
\end{marker}
\begin{exdispExample}{saveto_1}
@@ -315,6 +321,12 @@ Now, we load the saved text:
\item\docValue{ignored}: the lower part is not used (here).
\end{itemize}
The last two values are usually applied in connection with |savelowerto|.
+
+ \begin{marker}
+ The lower part is always typeset into a box which is used or dropped
+ accordingly. The only exception is applying \refKey{/tcb/redirectlowerto}.
+ \end{marker}
+
\begin{exdispExample}{lowerbox}
\begin{tcolorbox}[lowerbox=invisible,colback=white]
This is a \textbf{tcolorbox}.
@@ -331,8 +343,14 @@ This is the lower part (but ignored).
\end{docTcbKey}
+\clearpage
\begin{docTcbKey}[][doc updated=2014-11-28]{savelowerto}{=\meta{file name}}{no default, initially empty}
Saves the content of the lower part into a file for an optional later usage.
+ An empty \meta{file name} deactivates \refKey{/tcb/savelowerto}.
+ \begin{marker}
+ This option cannot be combined with \refKey{/tcb/saveto}.
+ \end{marker}
+
\begin{exdispExample}{savelowerto}
\begin{tcolorbox}[lowerbox=invisible,savelowerto=\jobname_bspsave.tex,colback=white]
This is a \textbf{tcolorbox}.
@@ -346,18 +364,23 @@ Now, we load the saved text:\\
\end{exdispExample}
\end{docTcbKey}
+\medskip
-\clearpage
\begin{docTcbKey}[][doc new=2023-07-17]{redirectlowerto}{=\meta{file name}}{no default, initially empty}
This is a combination of \refKey{/tcb/savelowerto} and \refKey{/tcb/lowerbox}|=|\docValue{ignored}
\emph{and additionally} avoids typesetting the content of the lower part.
This can be useful, if the lower part contains counters or similar.
+ An empty \meta{file name} deactivates the saving, but the \refKey{/tcb/lowerbox}
+ setting will still be \docValue{ignored}.
+ \begin{marker}
+ This option cannot be combined with \refKey{/tcb/saveto}.
+ \end{marker}
\begin{exdispExample}{redirectlowerto}
\setcounter{enumi}{1}
Test counter: \theenumi
-\begin{tcolorbox}[redirectlowerto=\jobname_bspsave.tex,colback=white]
+\begin{tcolorbox}[redirectlowerto=\jobname_bspsave2.tex,colback=white]
This is a \textbf{tcolorbox}.
\tcblower
This is the lower part.\stepcounter{enumi}
@@ -365,7 +388,7 @@ New value of test counter: \theenumi.
\end{tcolorbox}
Now, we load the saved text:\\
-\input{\jobname_bspsave.tex}
+\input{\jobname_bspsave2.tex}
\end{exdispExample}
\end{docTcbKey}
@@ -425,7 +448,7 @@ This is the lower part.
\clearpage
\begin{docTcbKey}{savedelimiter}{=\meta{name}}{no default, initially \texttt{tcolorbox}}
Used in connection with new environment definitions which extend
- |tcolorbox| and use or allow the option |savelowerto|.
+ |tcolorbox| and use or allow the option \refKey{/tcb/savelowerto} or \refKey{/tcb/redirectlowerto}.
To catch the end of the new box environment \meta{name} has to be the name of
this environment. Additionally, the environment definition has to use
|\tcolorbox| instead of
@@ -433,7 +456,7 @@ This is the lower part.
\begin{exdispExample}{savedelimiter1}
\newenvironment{mybox}[1]{%
\tcolorbox[savedelimiter=mybox,
- savelowerto=\jobname_bspsave2.tex,lowerbox=ignored,
+ savelowerto=\jobname_bspsave3.tex,lowerbox=ignored,
colback=red!5!white,colframe=red!75!black,fonttitle=\bfseries,
title={#1}]}%
{\endtcolorbox}
@@ -446,17 +469,17 @@ Saved lower part!
Now, the saved part is used:
\begin{tcolorbox}[colback=green!5]
-\input{\jobname_bspsave2.tex}
+\input{\jobname_bspsave3.tex}
\end{tcolorbox}
\end{exdispExample}
\enlargethispage*{1cm}
-The |savedelimiter| is used implicitely with \refCom{newtcolorbox} which
+The |savedelimiter| is used implicitly with \refCom{newtcolorbox} which
allows a more convenient usage:
\begin{exdispExample}{savedelimiter2}
\newtcolorbox{mybox}[1]{%
- savelowerto=\jobname_bspsave2.tex,lowerbox=ignored,
+ savelowerto=\jobname_bspsave4.tex,lowerbox=ignored,
colback=red!5!white,colframe=red!75!black,fonttitle=\bfseries,
title={#1}}%
@@ -468,7 +491,7 @@ Saved lower part!
Now, the saved part is used:
\begin{tcolorbox}[colback=green!5]
-\input{\jobname_bspsave2.tex}
+\input{\jobname_bspsave4.tex}
\end{tcolorbox}
\end{exdispExample}
\end{docTcbKey}
@@ -2631,6 +2654,99 @@ Lower part.
\end{exdispExample*}
\end{docTcbKey}
+\clearpage
+
+\begin{docTcbKeys}[
+ doc new = 2023-10-16,
+ doc description = style,
+ ]
+ {
+ { doc name = environment upper, doc parameter={=\meta{name}} },
+ { doc name = environment upper args, doc parameter={=\marg{name}\marg{code}} }
+ }
+ This shortcut style sets \refKey{/tcb/before upper*}
+ to |\begin|\marg{name} and \refKey{/tcb/after upper*}
+ to |\end|\marg{name}, i.e. the upper part is enclosed by the environment \meta{name}.
+ The second variant also places \meta{code} after |\begin|\marg{name}.
+\begin{exdispExample}{environment_upper_1}
+\begin{tcolorbox}[colback=yellow!30, colframe=yellow!80!black,
+ environment upper=itemize
+]
+ \item one
+ \item two
+\end{tcolorbox}
+\end{exdispExample}
+ Note that you may need \emph{additional} brackets around \meta{code}, if
+ \meta{code} contains some para\-meter(s) for the environment \meta{name}.
+\begin{exdispExample}{environment_upper_2}
+\begin{tcolorbox}[center upper,
+ colback=yellow!30, colframe=yellow!80!black,
+ environment upper args={tabular}{{cc}}
+]
+ one & two \\
+ three & four\\
+\end{tcolorbox}
+\end{exdispExample}
+\begin{exdispExample}{environment_upper_3}
+\begin{tcolorbox}[colback=yellow!30, colframe=yellow!80!black,
+ environment upper args = {list}{{\bfseries Fact:}
+ {\setlength\itemsep{0pt}\setlength\parsep{0pt}}},
+]
+ \item Blue is red
+ \item Red is green
+\end{tcolorbox}
+\end{exdispExample}
+\end{docTcbKeys}
+
+
+\begin{marker}
+\refKey{/tcb/environment upper} and friends (following) cannot be used to
+wrap another |tcolorbox|-based environment, i.e. never use
+|/tcb/environment upper=tcolorbox| or
+|/tcb/environment upper=etc-derived-from-tcolorbox|.
+\end{marker}
+
+
+\clearpage
+
+\begin{docTcbKeys}[
+ doc new = 2023-10-16,
+ doc description = style,
+ ]
+ {
+ { doc name = environment lower, doc parameter={=\meta{name}} },
+ { doc name = environment lower args, doc parameter={=\marg{name}\marg{code}} }
+ }
+ This shortcut style sets \refKey{/tcb/before lower*}
+ to |\begin|\marg{name} and \refKey{/tcb/after lower*}
+ to |\end|\marg{name}, i.e. the lower part is enclosed by the environment \meta{name}.
+ The second variant also places \meta{code} after |\begin|\marg{name}.
+ Note that you may need \emph{additional} brackets around \meta{code}, if
+ \meta{code} contains some para\-meter(s) for the environment \meta{name}.
+
+ See \refKey{/tcb/environment upper} for analog examples.
+\end{docTcbKeys}
+
+
+\begin{docTcbKeys}[
+ doc new = 2023-10-16,
+ doc description = style,
+ ]
+ {
+ { doc name = environment title, doc parameter={=\meta{name}} },
+ { doc name = environment title args, doc parameter={=\marg{name}\marg{code}} }
+ }
+ This shortcut style sets \refKey{/tcb/before title*}
+ to |\begin|\marg{name} and \refKey{/tcb/after title*}
+ to |\end|\marg{name}, i.e. the title text is enclosed by the environment \meta{name}.
+ The second variant also places \meta{code} after |\begin|\marg{name}.
+ Note that you may need \emph{additional} brackets around \meta{code}, if
+ \meta{code} contains some para\-meter(s) for the environment \meta{name}.
+
+ See \refKey{/tcb/environment upper} for analog examples.
+\end{docTcbKeys}
+
+
\clearpage
\subsection{Overlays}\label{subsec:overlays}
@@ -3848,7 +3964,7 @@ in the following order. Following options overwrite preceding options.
\item For layer 2 and above (nested boxes), a \refKey{/tcb/reset} followed by
\refKey{/tcb/every box} option list is applied.
Every resettable options given by a preceding \refCom{tcbset}
- and by the sourrounding box(es) are reset.
+ and by the surrounding box(es) are reset.
\end{itemize}
\item The \meta{options} given to the |tcolorbox| are applied.
Or, if the box was generated by \refCom{newtcolorbox} or friends,
@@ -4013,7 +4129,7 @@ This is a tcolorbox.
\clearpage
\subsection{Text Characteristics}
-\begin{docTcbKey}[][doc updated=2015-10-14]{parbox}{\colOpt{=true\textbar false}}{default |true|, initially |true|}
+\begin{docTcbKey}[][doc updated=2024-01-10]{parbox}{\colOpt{=true\textbar false}}{default |true|, initially |true|}
The text inside a |tcolorbox| is formatted using a \LaTeX\ |minipage|
if the box is unbreakable. If breakable, the box tries a mimicry of
a |minipage|. In a |minipage| or |parbox|, paragraphs are formatted slightly different
@@ -4072,7 +4188,7 @@ targeting different box types and they do not blend very well.
\subsection{Files}
\begin{docTcbKey}{tempfile}{=\meta{file name}}{no default, initially \cs{jobname.tcbtemp}}
Sets \meta{file name} as name for the temporary file which is used inside
- \refEnv{tcbwritetemp} and \refCom{tcbusetemp} implicitely.
+ \refEnv{tcbwritetemp} and \refCom{tcbusetemp} implicitly.
\end{docTcbKey}
\clearpage
@@ -4430,7 +4546,7 @@ of a page.
\refKey{/tcb/toggle enlargement}, and
\refKey{/tcb/if odd page}
automatically set |check odd page|, but for
-\refCom{tcbifoddpage} this option has to be set explicitely.
+\refCom{tcbifoddpage} this option has to be set explicitly.
\end{docTcbKey}
\enlargethispage*{1cm}
@@ -4451,7 +4567,7 @@ If a box is \refKey{/tcb/breakable}, using \refKey{/tcb/if odd page}
only acts upon the \emph{first} box. If the setting should be
repeated for every partial box of the break sequence, the option should be
packed into \refKey{/tcb/extras}. In this case, \refKey{/tcb/check odd page}
-has to be set explicitely! Also see \refKey{/tcb/if odd page*}.
+has to be set explicitly! Also see \refKey{/tcb/if odd page*}.
\end{marker}
\end{docTcbKey}
@@ -4638,7 +4754,7 @@ Sets (nearly) all |tcolorbox| settings (including loaded libraries) back to thei
\emph{plus} any settings given by \refCom{tcbsetforeverylayer}.
\refKey{/tcb/savedelimiter}, \refKey{/tcb/capture}, and
\refKey{/tcb/shield externalize} keep their values.
-Also, all raster values (see \Vref{sec:raster}) are not resetted.
+Also, all raster values (see \Vref{sec:raster}) are not reset.
This option is useful for boxes in boxes where the inner box should not inherit
the settings of the outer box.