diff options
Diffstat (limited to 'macros/latex/contrib/tcolorbox/tcolorbox.doc.coreoptions.tex')
-rw-r--r-- | macros/latex/contrib/tcolorbox/tcolorbox.doc.coreoptions.tex | 306 |
1 files changed, 205 insertions, 101 deletions
diff --git a/macros/latex/contrib/tcolorbox/tcolorbox.doc.coreoptions.tex b/macros/latex/contrib/tcolorbox/tcolorbox.doc.coreoptions.tex index ba853c46e3..d885f48279 100644 --- a/macros/latex/contrib/tcolorbox/tcolorbox.doc.coreoptions.tex +++ b/macros/latex/contrib/tcolorbox/tcolorbox.doc.coreoptions.tex @@ -240,8 +240,6 @@ and an optional \emph{lower part}. These parts are separated by This is a \textbf{tcolorbox} (but invisible). \end{tcolorbox} -\bigskip - \begin{tcolorbox}[upperbox=invisible,colback=white] This is a \textbf{tcolorbox} (but invisible). \tcblower @@ -426,6 +424,8 @@ Now, the saved part is used: \end{tcolorbox} \end{exdispExample} +\enlargethispage*{1cm} + The |savedelimiter| is used implicitely with \refCom{newtcolorbox} which allows a more convenient usage: \begin{exdispExample}{savedelimiter2} @@ -2805,52 +2805,34 @@ are drawn by the codes given with \subsection{Embedding into the Surroundings}\label{subsec:surroundings} Typically, but not necessarily, a |tcolorbox| is put inside a separate paragraph and has some vertical space before and after it. -This behavior is controlled by the keys |before| and |after|. +This behavior is controlled by the keys \refKey{/tcb/before} and \refKey{/tcb/after}. + +\begin{marker} +Before version 4.40, the default setting for \refKey{/tcb/before} +and \refKey{/tcb/after} was given by \refKey{/tcb/autoparskip}. +Starting with version 4.40, the default setting is given by +\refKey{/tcb/before skip balanced} and \refKey{/tcb/after skip balanced}.\par +Note that old documents may need adaptions of page breaks.\par +Alternatively, the old default setting can be restored by using +\begin{dispListing} +\tcbsetforeverylayer{autoparskip} +\end{dispListing} +inside the document preamble. +\end{marker} -\begin{docTcbKey}{before}{=\meta{code}}{no default, initially see \refKey{/tcb/autoparskip}} + +\begin{docTcbKey}{before}{=\meta{code}}{no default, initially see \refKey{/tcb/before skip balanced}} Sets the \meta{code} which is executed before the colored box. It is not used for floating boxes. Also, it is not used, if the box follows a heading immediately and \refKey{/tcb/ignore nobreak} is set to \docValue{false}. \end{docTcbKey} -\begin{docTcbKey}{after}{=\meta{code}}{no default, initially see \refKey{/tcb/autoparskip}} +\begin{docTcbKey}{after}{=\meta{code}}{no default, initially see \refKey{/tcb/after skip balanced}} Sets the \meta{code} which is executed after the colored box. It is not used for floating boxes. \end{docTcbKey} -\begin{docTcbKey}[][doc updated=2017-02-01]{parskip}{}{style, no value} - Sets the keys |before| and |after| to values which are - recommended, if the package |parskip| \emph{is} used and there is no better - idea for |before| and |after|. This is similar to: -\begin{dispListing} -\tcbset{parskip/.style={before={\par\pagebreak[0]\parindent=0pt}, - after={\par}}} -\end{dispListing} -\end{docTcbKey} - -\begin{docTcbKey}[][doc updated=2017-02-01]{noparskip}{}{style, no value} - Sets the keys |before| and |after| to values which are - recommended, if the package |parskip| is \emph{not} used and there is no better - idea for |before| and |after|. This is similar to: -\begin{dispListing} -\tcbset{noparskip/.style={before={\par\pagebreak[0]\smallskip\parindent=0pt}, - after={\par\smallskip}}} -\end{dispListing} -\end{docTcbKey} - -\begin{docTcbKey}{autoparskip}{}{style, no value, initially set} - Tries to detect the usage of the package |parskip| and sets - the keys |before| and |after| accordingly. Actually, the following is done: - \begin{itemize} - \item If the length of |\parskip| is greater than |0pt| at the beginning of the document, - \refKey{/tcb/parskip} is executed. Here, the usage of package |parskip| is \emph{assumed}. - \item Otherwise, if the length of |\parskip| is not greater than |0pt| at the beginning of the document, - \refKey{/tcb/noparskip} is executed. Here, the absence of package |parskip| is \emph{assumed}. - \end{itemize} - |autoparskip| is the default for the package |tcolorbox|, if |before| or |after| - are not changed otherwise. -\end{docTcbKey} \begin{docTcbKey}{nobeforeafter}{}{style, no value} Abbreviation for clearing the keys |before| and |after|. The colored box @@ -2865,7 +2847,6 @@ This behavior is controlled by the keys |before| and |after|. \end{exdispExample} \end{docTcbKey} -\enlargethispage*{1cm} \begin{docTcbKey}{force nobeforeafter}{}{style, no value} Forces the setting of \refKey{/tcb/nobeforeafter} even if \refKey{/tcb/before} and \refKey{/tcb/after} are set to other values @@ -2876,78 +2857,80 @@ This behavior is controlled by the keys |before| and |after|. \clearpage -\begin{docTcbKey}{baseline}{=\meta{length}}{no default, initially |0pt|} - Used to set the |\pgfsetbaseline| value of the resulting |tcolorbox|. -\begin{exdispExample}{baseline} -\tcbset{colframe=red!50!white,width=4cm,nobeforeafter} -Some text\dotfill -\begin{tcolorbox}[baseline=3mm] -One line. -\end{tcolorbox} -\begin{tcolorbox}[baseline=3mm] -First line.\\Second line. +\begin{docTcbKey}[][doc new={2020-09-25}]{before skip balanced}{=\meta{glue}}{no default, initially |0.5\textbackslash baselineskip plus 2pt|} + Inserts some vertical space before the colored box. This style sets \refKey{/tcb/before}.\par + If the depth of the + preceeding \TeX\ box is between |0pt| and |0.3\baselineskip|, + the distance between the \emph{baseline} of the preceeding \TeX\ box and the tcolorbox + ist set to \meta{glue}$+$|0.3\baselineskip|.\par + If the depth is larger, the distance of the preceeding \TeX\ box and the tcolorbox + ist set to \meta{glue}.\par + Alternatively, see \refKey{/tcb/before skip} which ignores the \emph{baseline}. + +\begin{exdispExample*}{before_skip_balanced}{sbs,lefthand ratio=0.6} +Some text. +\begin{tcolorbox}[before skip balanced=1cm, + colframe=red!50!white] + This is a \textbf{tcolorbox}. \end{tcolorbox} -\end{exdispExample} +\end{exdispExample*} \end{docTcbKey} +\begin{docTcbKey}[][doc new={2020-09-25}]{after skip balanced}{=\meta{glue}}{no default, initially |0.5\textbackslash baselineskip plus 2pt|} + Inserts some vertical space of the given \meta{glue} after the colored box. + This style sets \refKey{/tcb/after}. + Additionally, |\prevdepth| is set to |0.3\baselineskip|. The following + \TeX\ box may enlarge the space by further glue to adjust its \emph{baseline}. + Alternatively, see \refKey{/tcb/after skip} which ignores the \emph{baseline}. -\begin{docTcbKey}[][doc new=2014-10-10]{box align}{=\meta{alignment}}{style, no default, initially |bottom|} - Used to set the \refKey{/tcb/baseline} value of the resulting |tcolorbox|. - Feasible values for \meta{alignment} are: - \begin{itemize} - \item\docValue{bottom}: alignment with the box bottom, - \item\docValue{top}: alignment with the box top, - \item\docValue{center}: alignment with the box center, - \item\docValue{base}: alignment with the box content base. This option - is not applicable for a \refEnv{tcolorbox} but for a \refCom{tcbox} only. - It is an alias for \refKey{/tcb/tcbox raise base}. - \end{itemize} - -\begin{exdispExample}{box_align_1} -\tcbset{colframe=red!50!white,width=4cm,nobeforeafter} -Some text\dotfill -\begin{tcolorbox}[box align=bottom] -One line. -\end{tcolorbox} -\begin{tcolorbox}[box align=bottom] -First line.\\Second line. -\end{tcolorbox} -\end{exdispExample} - -\begin{exdispExample}{box_align_2} -\tcbset{colframe=red!50!white,width=4cm,nobeforeafter} -Some text\dotfill -\begin{tcolorbox}[box align=top] -One line. -\end{tcolorbox} -\begin{tcolorbox}[box align=top] -First line.\\Second line. +\begin{exdispExample*}{after_skip_balanced}{sbs,lefthand ratio=0.6} +\begin{tcolorbox}[after skip balanced=1cm, + colframe=red!50!white] + This is a \textbf{tcolorbox}. \end{tcolorbox} -\end{exdispExample} +Some text. +\end{exdispExample*} +\end{docTcbKey} -\begin{exdispExample}{box_align_3} -\tcbset{colframe=red!50!white,width=4cm,nobeforeafter} -Some text\dotfill -\begin{tcolorbox}[box align=center] -One line. -\end{tcolorbox} -\begin{tcolorbox}[box align=center] -First line.\\Second line. -\end{tcolorbox} -\end{exdispExample} -\begin{exdispExample}{box_align_4} -\tcbset{colframe=red!50!white,nobeforeafter} -Some text\dotfill -\tcbox[nobeforeafter,box align=base]{One line} -\tcbox[nobeforeafter,box align=base,size=fbox]{Another line} -\end{exdispExample} +\begin{docTcbKey}[][doc new={2020-09-25}]{beforeafter skip balanced}{=\meta{glue}}{no default, initially |0.5\textbackslash baselineskip plus 2pt|} + Inserts some vertical space of the given \meta{glue} before \emph{and} after the colored box. + This style sets \refKey{/tcb/before skip balanced} and \refKey{/tcb/after skip balanced}. +\begin{exdispExample*}{beforeafter_skip_balanced}{sbs,lefthand ratio=0.6} +\newtcolorbox{doubleline}[1][]{ + beforeafter skip balanced=0pt, + height=1.8\baselineskip, + enlarge top by=.1\baselineskip, + enlarge bottom by=.1\baselineskip, + colframe=blue!20,colback=blue!5, + size=small,valign upper=center,#1 } + +\noindent\begin{tikzpicture} +\path[use as bounding box] (0,0) + rectangle (0.1,0.1); +\foreach \y in {0,1,...,9} { + \draw[very thin,red] + (-0.2,-\y*\baselineskip) -- + (\linewidth+0.2cm,-\y*\baselineskip); } +\end{tikzpicture} +line 1\par +\begin{doubleline} Abc \end{doubleline} +\begin{doubleline} Def \end{doubleline} +line 2g\par +\begin{doubleline} Ghi \end{doubleline} +line 3\par +line 4 g +\end{exdispExample*} \end{docTcbKey} -\begin{docTcbKey}[][doc new and updated={2014-10-10}{2015-03-16}]{before skip}{=\meta{glue}}{style, no default} +\clearpage + +\begin{docTcbKey}[][doc new and updated={2020-09-25}{2015-03-16}]{before skip}{=\meta{glue}}{style, no default} Inserts some vertical space of the given \meta{glue} before the colored box. This style sets \refKey{/tcb/before}. + In contrast to \refKey{/tcb/before skip balanced}, this \meta{glue} is + relative to the lower edge of the preceeding box and not to the baseline. \begin{exdispExample*}{before_skip}{sbs,lefthand ratio=0.6} Some text. \begin{tcolorbox}[before skip=1cm, @@ -2957,9 +2940,11 @@ Some text. \end{exdispExample*} \end{docTcbKey} -\begin{docTcbKey}[][doc new and updated={2014-10-10}{2017-02-01}]{after skip}{=\meta{glue}}{style, no default} +\begin{docTcbKey}[][doc new and updated={2020-09-25}{2017-02-01}]{after skip}{=\meta{glue}}{style, no default} Inserts some vertical space of the given \meta{glue} after the colored box. This style sets \refKey{/tcb/after}. + In contrast to \refKey{/tcb/after skip balanced}, this \meta{glue} is + relative to the upper edge of the following box and not to the baseline. \begin{exdispExample*}{after_skip}{sbs,lefthand ratio=0.6} \begin{tcolorbox}[after skip=1cm, colframe=red!50!white] @@ -2971,19 +2956,23 @@ Some text. \begin{docTcbKey}[][doc new=2014-10-10]{beforeafter skip}{=\meta{glue}}{style, no default} Inserts some vertical space of the given \meta{glue} before \emph{and} after the colored box. - This style sets \refKey{/tcb/before} and \refKey{/tcb/after}. + This style sets \refKey{/tcb/before skip} and \refKey{/tcb/after skip}. \begin{exdispExample*}{beforeafter_skip}{sbs,lefthand ratio=0.6} \tcbset{beforeafter skip=0pt, colframe=red!50!white} + +text before \begin{tcolorbox} This is a \textbf{tcolorbox}. \end{tcolorbox} \begin{tcolorbox} Second box. \end{tcolorbox} +text after \end{exdispExample*} \end{docTcbKey} + \clearpage \begin{docTcbKey}[][doc new=2014-11-07]{left skip}{=\meta{length}}{style, no default, initially |0mm|} @@ -3028,6 +3017,122 @@ Some text. \end{docTcbKey} +\clearpage + +\begin{docTcbKey}[][doc updated=2017-02-01]{parskip}{}{style, no value} + This options is considered to be superseded by + \refKey{/tcb/before skip balanced} and \refKey{/tcb/after skip balanced} + (see note on page~\pageref{subsec:surroundings}).\par + Sets the keys |before| and |after| to values which are + recommended, if the package |parskip| \emph{is} used and there is no better + idea for |before| and |after|. This is similar to: +\begin{dispListing} +\tcbset{parskip/.style={before={\par\pagebreak[0]\parindent=0pt}, + after={\par}}} +\end{dispListing} +\end{docTcbKey} + +\begin{docTcbKey}[][doc updated=2017-02-01]{noparskip}{}{style, no value} + This options is considered to be superseded by + \refKey{/tcb/before skip balanced} and \refKey{/tcb/after skip balanced} + (see note on page~\pageref{subsec:surroundings}).\par + Sets the keys |before| and |after| to values which are + recommended, if the package |parskip| is \emph{not} used and there is no better + idea for |before| and |after|. This is similar to: +\begin{dispListing} +\tcbset{noparskip/.style={before={\par\pagebreak[0]\smallskip\parindent=0pt}, + after={\par\smallskip}}} +\end{dispListing} +\end{docTcbKey} + +\begin{docTcbKey}{autoparskip}{}{style, no value} + This options is considered to be superseded by + \refKey{/tcb/before skip balanced} and \refKey{/tcb/after skip balanced} + (see note on page~\pageref{subsec:surroundings}).\par + Tries to detect the usage of the package |parskip| and sets + the keys |before| and |after| accordingly. Actually, the following is done: + \begin{itemize} + \item If the length of |\parskip| is greater than |0pt| at the beginning of the document, + \refKey{/tcb/parskip} is executed. Here, the usage of package |parskip| is \emph{assumed}. + \item Otherwise, if the length of |\parskip| is not greater than |0pt| at the beginning of the document, + \refKey{/tcb/noparskip} is executed. Here, the absence of package |parskip| is \emph{assumed}. + \end{itemize} +\end{docTcbKey} + + +\clearpage + +\begin{docTcbKey}{baseline}{=\meta{length}}{no default, initially |0pt|} + Used to set the |\pgfsetbaseline| value of the resulting |tcolorbox|. +\begin{exdispExample}{baseline} +\tcbset{colframe=red!50!white,width=4cm,nobeforeafter} +Some text\dotfill +\begin{tcolorbox}[baseline=3mm] +One line. +\end{tcolorbox} +\begin{tcolorbox}[baseline=3mm] +First line.\\Second line. +\end{tcolorbox} +\end{exdispExample} +\end{docTcbKey} + + +\begin{docTcbKey}[][doc new=2014-10-10]{box align}{=\meta{alignment}}{style, no default, initially |bottom|} + Used to set the \refKey{/tcb/baseline} value of the resulting |tcolorbox|. + Feasible values for \meta{alignment} are: + \begin{itemize} + \item\docValue{bottom}: alignment with the box bottom, + \item\docValue{top}: alignment with the box top, + \item\docValue{center}: alignment with the box center, + \item\docValue{base}: alignment with the box content base. This option + is not applicable for a \refEnv{tcolorbox} but for a \refCom{tcbox} only. + It is an alias for \refKey{/tcb/tcbox raise base}. + \end{itemize} + +\begin{exdispExample}{box_align_1} +\tcbset{colframe=red!50!white,width=4cm,nobeforeafter} +Some text\dotfill +\begin{tcolorbox}[box align=bottom] +One line. +\end{tcolorbox} +\begin{tcolorbox}[box align=bottom] +First line.\\Second line. +\end{tcolorbox} +\end{exdispExample} + +\begin{exdispExample}{box_align_2} +\tcbset{colframe=red!50!white,width=4cm,nobeforeafter} +Some text\dotfill +\begin{tcolorbox}[box align=top] +One line. +\end{tcolorbox} +\begin{tcolorbox}[box align=top] +First line.\\Second line. +\end{tcolorbox} +\end{exdispExample} + +\begin{exdispExample}{box_align_3} +\tcbset{colframe=red!50!white,width=4cm,nobeforeafter} +Some text\dotfill +\begin{tcolorbox}[box align=center] +One line. +\end{tcolorbox} +\begin{tcolorbox}[box align=center] +First line.\\Second line. +\end{tcolorbox} +\end{exdispExample} + +\begin{exdispExample}{box_align_4} +\tcbset{colframe=red!50!white,nobeforeafter} +Some text\dotfill +\tcbox[nobeforeafter,box align=base]{One line} +\tcbox[nobeforeafter,box align=base,size=fbox]{Another line} +\end{exdispExample} +\end{docTcbKey} + + + + \begin{docTcbKey}[][doc new=2014-12-11]{ignore nobreak}{\colOpt{=true\textbar false}}{default |true|, initially |false|} After a heading, \LaTeX\ tries to avoid a break by setting a |nobreak| boolean value. Starting from version |3.33|, the \refKey{/tcb/before} respectively \refKey{/tcb/before skip} @@ -3048,7 +3153,6 @@ enforce the \refKey{/tcb/before} setting. the box follows a heading. \end{docTcbKey} -\enlargethispage*{1cm} \begin{docTcbKey}[][doc new=2017-02-23]{parfillskip restore}{\colOpt{=true\textbar false}}{default |true|, initially |true|} If this option is set to be |true|, the minimum value of |\parfillskip| is |