% !TeX root = tcolorbox.tex
% include file of tcolorbox.tex (manual of the LaTeX package tcolorbox)
\clearpage
\section{Library 'breakable'}\label{sec:breakable}
The library is loaded by a package option or inside the preamble by:
\begin{dispListing}
\tcbuselibrary{breakable}
\end{dispListing}

\subsection{Technical Overview}
The library 'breakable' supports the automatic breaking of a |tcolorbox|.
This feature is enabled by \refKey{/tcb/breakable}
and disabled by \refKey{/tcb/unbreakable}.

{
\tcbset{colframe=Navy,colback=AliceBlue,fonttitle=\bfseries,
  watermark color=AliceBlue!85!Navy,enhanced}
If a |tcolorbox| is set to be \refKey{/tcb/breakable}, then the following
algorithm is executed:
\begin{enumerate}
\item The box content is read to a box register similar but not identical
  to the unbreakable case.
\item If the total box fits into the current page, it is shipped out visibly
  unbroken and the algorithm stops.
  \begin{tcolorbox}[title=Unbroken Box,watermark text=unbroken]
  The box.
  \end{tcolorbox}
\item Otherwise, it is checked if at least \refKey{/tcb/lines before break}
  of the upper box can be placed on the current page.
  If not, a page break is inserted and the algorithm goes back to Step 2.
\item Now, the \emph{break sequence} starts.
  The upper box part or the lower box part is split such that it fits
  into the current page. The fitting part is named \emph{first part} of
  the \emph{break sequence} and shipped out.
  \begin{tcolorbox}[title=Broken Box,watermark text=first,skin=enhancedfirst]
  The box.
  \end{tcolorbox}
\item
  If the remaining content of the total box
  fits into the current page, the algorithm continues with Step 7, else
  with Step 6.
\item
  The upper box part or the lower box part is split such that it fits
  into the current page. The fitting part is named \emph{middle part} of
  the \emph{break sequence} and shipped out.
  Then, the algorithm goes back to Step 5.
  \begin{tcolorbox}[watermark text=middle,skin=enhancedmiddle]
  The box.
  \end{tcolorbox}
\item
  The remaining part is named \emph{last part} of
  the \emph{break sequence} and shipped out. The algorithm stops.
  \begin{tcolorbox}[watermark text=last,skin=enhancedlast]
  The box.
  \end{tcolorbox}
\end{enumerate}
}

The algorithm takes care that the optional segmentation line never appears at
the end of a box. The optional lower box part is also checked to
have at least \refKey{/tcb/lines before break}.

\clearpage
In principal, all boxes of the \emph{break sequence} share the same geometric
parameters. The differences are:
\begin{itemize}
\item The given \refKey{/tcb/before} and \refKey{/tcb/after} values are
  used only before the \emph{first} and after the \emph{last} part
  of the \emph{break sequence}.
\item A special behavior between the parts of the \emph{break sequence} can
  be given by \refKey{/tcb/toprule at break},
  \refKey{/tcb/bottomrule at break},
  \refKey{/tcb/enlarge top at break by}, and
  \refKey{/tcb/enlarge bottom at break by}.
\item The \refKey{/tcb/skin} decides \emph{how} the \emph{first}, \emph{middle},
  and \emph{last} part look like. Actually, every part type has its own
  skin given by the options  \refKey{/tcb/skin first}, \refKey{/tcb/skin middle}, and
  \refKey{/tcb/skin last}. Typically, these options are set automatically by
  the main skin, see Subsection \ref{subsec:breaksequence} from
  page \pageref{subsec:breaksequence}.
\end{itemize}


\subsection{Limitations and Known Bugs}
\begin{itemize}
\item The box content is a \TeX\ |\vbox| register which has a
  restricted capacity. Therefore, you cannot place hundreds of pages
  inside a |tcolorbox|.
\item You can nest an unbreakable |tcolorbox| inside another |tcolorbox|,
  even inside a breakable one. But you should not nest a breakable box
  inside a breakable box since this will give a mess. Inside a breakable box,
  the further breaking is disabled by default. If you really want to or
  have to use the keys \refKey{/tcb/breakable} or \refKey{/tcb/unbreakable}
  inside the content of an outer |tcolorbox|, you have to guard this with a
  \TeX\ group.
\item If your text content contains some text color changing commands,
  your color will not survive the break to the next box\footnote{The reason is that
  I am to dumb to catch the current color at the split point. If you know the trick,
  let me know.}.
\end{itemize}


\clearpage
\subsection{Main Option Keys}
\begin{docTcbKey}{breakable}{}{no value}
  Allows the |tcolorbox| to be breakable. If the box is larger than the
  available space at the current page, the box is automatically broken
  and continued to the next next page. All sorts of |tcolorbox| can be made
  breakable. It depends on the skin how the breaking looks like.
  If you do not know better, use \refKey{/tcb/enhanced} for breaking a box.
  The parts of the \emph{break sequence} are numbered
  by the counter |tcbbreakpart|.
  \begin{dispListing}
  % \usepackage{lipsum}  % preamble
  \tcbset{colback=red!5!white,colframe=red!75!black,
    watermark color=yellow!25!white,watermark text=\arabic{tcbbreakpart},
    fonttitle=\bfseries}

  \begin{tcolorbox}[breakable,enhanced,title=My breakable box]
  \lipsum[1-6]
  \end{tcolorbox}
  \end{dispListing}
\end{docTcbKey}
{\tcbusetemp}


\begin{docTcbKey}{unbreakable}{}{no value, initially set}
  Sets the |tcolorbox| to be unbreakable.
\end{docTcbKey}


\begin{docTcbKey}{title after break}{=\meta{text}}{no default, initially empty}
  The \refKey{/tcb/title} is used only for the \emph{first} part of a
  \emph{break sequence}. Use |title after break| to create a heading line
  with \meta{text} as content for all following parts.
\end{docTcbKey}


\begin{docTcbKey}{notitle after break}{}{no value, initially set}
  Removes the title line or following parts in a  \emph{break sequence} if set before.
\end{docTcbKey}


\begin{docTcbKey}{adjusted title after break}{=\meta{text}}{style, no default, initially unset}
  Works like \refKey{/tcb/adjusted title} but applied to \refKey{/tcb/title after break}.
\end{docTcbKey}


\begin{docTcbKey}{lines before break}{=\meta{number}}{no default, initially |2|}
  Assures that the given \meta{number} of lines of the upper box part or
  the lower box part are placed before a break happens.
\end{docTcbKey}



\begin{docTcbKey}{shrink break goal}{=\meta{length}}{no default, initially |0pt|}
  This is an emergency parameter if the break algorithm produces unpleasant
  breaks. It shrinks the goal height of the current box part by \meta{length}
  which may result in smaller boxes. Never use negative values.
\end{docTcbKey}


\clearpage
\subsection{Option Keys for the Break Appearance}

\begin{docTcbKey}{toprule at break}{=\meta{length}}{no default, initially \texttt{0.5mm}}
  Sets the line width of the top rule to \meta{length} \emph{if} the box is \refKey{/tcb/breakable}.
  In this case, it is applied to \emph{middle} and \emph{last} parts in a
  break sequence. Note that \refKey{/tcb/toprule} overwrites this value
  if used afterwards.
\end{docTcbKey}


\begin{docTcbKey}{bottomrule at break}{=\meta{length}}{no default, initially \texttt{0.5mm}}
  Sets the line width of the bottom rule to \meta{length} \emph{if} the box is \refKey{/tcb/breakable}.
  In this case, it is applied to \emph{first} and \emph{middle} parts in a
  break sequence. Note that \refKey{/tcb/bottomrule} overwrites this value
  if used afterwards.
\end{docTcbKey}




\begin{docTcbKey}{topsep at break}{=\meta{length}}{no default, initially \texttt{0mm}}
  Additional vertical space of \meta{length} which is added at the top of
  \emph{middle} and \emph{last} parts in a break sequence. In general,
  it is not advisable to change this value if these parts start with a rule or a title.
\end{docTcbKey}

\begin{docTcbKey}{bottomsep at break}{=\meta{length}}{no default, initially \texttt{0mm}}
  Additional vertical space of \meta{length} which is added at the bottom of
  \emph{first} and \emph{middle} parts in a break sequence.
  In general, it is not advisable to change this value if these parts end with a rule.
\end{docTcbKey}

\begin{docTcbKey}{pad before break}{=\meta{length}}{style, no default, initially \texttt{3.5mm}}
  Sets the total amount of vertical space after the text content and before the
  break point to \meta{length}. This style sets \refKey{/tcb/toprule at break} to |0pt|
  and changes \refKey{/tcb/topsep at break} as required.
  In general, it is not advisable to change this value if the
  \emph{middle} and \emph{last} parts in a break sequence start with a rule or a title.
\end{docTcbKey}

\begin{docTcbKey}{pad after break}{=\meta{length}}{style, no default, initially \texttt{3.5mm}}
  Sets the total amount of vertical space after the break point and before the
  text content to \meta{length}. This style sets \refKey{/tcb/bottomrule at break} to |0pt|
  and changes \refKey{/tcb/bottomsep at break} as required.
  In general, it is not advisable to change this value if the
  \emph{first} and \emph{middle} parts in a break sequence end with a rule.
\end{docTcbKey}

\begin{docTcbKey}{pad at break}{=\meta{length}}{style, no default, initially \texttt{3.5mm}}
  Abbreviation for setting \meta{length} to \refKey{/tcb/pad before break}
  and \refKey{/tcb/pad after break}.
\end{docTcbKey}


\begin{dispListing}
% \usepackage{lipsum}  % preamble
\tcbset{colback=red!5!white,colframe=red!75!black,fonttitle=\bfseries}

\begin{tcolorbox}[enhanced,breakable,pad at break=0mm,
  title={For this box, the pad space at the break point is set to 0mm}]
  \lipsum[1-2]
\end{tcolorbox}
\end{dispListing}
{\tcbusetemp}



\begin{docTcbKey}{enlarge top at break by}{=\meta{length}}{no default, initially \texttt{0mm}}
  Enlarges the bounding box distance to the top of the box by \meta{length}
  \emph{if} the box is \refKey{/tcb/breakable}.
  In this case, it is applied to \emph{middle} and \emph{last} parts in a
  break sequence.
  \refKey{/tcb/enlarge top by} overwrites this key.
\end{docTcbKey}


\begin{docTcbKey}{enlarge bottom at break by}{=\meta{length}}{no default, initially \texttt{0mm}}
  Enlarges the bounding box distance to the bottom of the box by \meta{length}
  \emph{if} the box is \refKey{/tcb/breakable}.
  In this case, it is applied to \emph{first} and \emph{middle} parts in a
  break sequence. \refKey{/tcb/enlarge bottom by} overwrites this key.
\end{docTcbKey}


\clearpage
\subsection{Break Sequence for the Skins}\label{subsec:breaksequence}
The following diagrams document the \emph{break sequence} for different
skins. Depending on the main skin of a |tcolorbox|, the actual skins of
the \emph{break sequence} parts are displayed.

\def\tcbbreakskininto#1#2#3#4#5{%
\begin{center}\begin{tikzpicture}
\tcbset{width=5cm,colframe=Navy,colback=AliceBlue,fonttitle=\bfseries,
  watermark color=AliceBlue!85!Navy,#5
  }
\node[above] (unbroken) at (0,0) {\begin{tcolorbox}[title=Unbroken Box,skin=#1,watermark text=unbroken,height=3.8cm]
\texttt{skin=#1}
\end{tcolorbox}};
\node[above] (first) at (8,2.4) {\begin{tcolorbox}[title=Broken Boxes,skin=#2,watermark text=first,height=1.4cm]
\texttt{skin=#2}
\end{tcolorbox}};
\node[above] (middle) at (8,1.2) {\begin{tcolorbox}[skin=#3,watermark text=middle,height=1cm]
\texttt{skin=#3}
\end{tcolorbox}};
\node[above] (last) at (8,0) {\begin{tcolorbox}[skin=#4,watermark text=last,height=1cm]
\texttt{skin=#4}
\end{tcolorbox}};
\path[draw=FireBrick,line width=2pt,->] (unbroken) edge (first.west) edge (middle.west) edge (last.west);
\end{tikzpicture}\end{center}}

\tcbbreakskininto{standard}{standard}{standard}{standard}{watermark text/.style={}}
\tcbbreakskininto{enhanced}{enhancedfirst}{enhancedmiddle}{enhancedlast}{}
\tcbbreakskininto{enhancedfirst}{enhancedfirst}{enhancedmiddle}{enhancedmiddle}{}
\tcbbreakskininto{enhancedmiddle}{enhancedmiddle}{enhancedmiddle}{enhancedmiddle}{}
\tcbbreakskininto{enhancedlast}{enhancedmiddle}{enhancedmiddle}{enhancedlast}{}
\tcbbreakskininto{freelance}{freelance}{freelance}{freelance}{}
\tcbbreakskininto{bicolor}{bicolorfirst}{bicolormiddle}{bicolorlast}{bicolor}
\tcbbreakskininto{bicolorfirst}{bicolorfirst}{bicolormiddle}{bicolormiddle}{bicolor}
\tcbbreakskininto{bicolormiddle}{bicolormiddle}{bicolormiddle}{bicolormiddle}{bicolor}
\tcbbreakskininto{bicolorlast}{bicolormiddle}{bicolormiddle}{bicolorlast}{bicolor}
\tcbbreakskininto{beamer}{beamerfirst}{beamermiddle}{beamerlast}{beamer}
\tcbbreakskininto{beamerfirst}{beamerfirst}{beamermiddle}{beamermiddle}{beamer}
\tcbbreakskininto{beamermiddle}{beamermiddle}{beamermiddle}{beamermiddle}{beamer}
\tcbbreakskininto{beamerlast}{beamermiddle}{beamermiddle}{beamerlast}{beamer}
\clearpage
\tcbbreakskininto{widget}{widgetfirst}{widgetmiddle}{widgetlast}{widget}
\tcbbreakskininto{widgetfirst}{widgetfirst}{widgetmiddle}{widgetmiddle}{widget}
\tcbbreakskininto{widgetmiddle}{widgetmiddle}{widgetmiddle}{widgetmiddle}{widget}
\tcbbreakskininto{widgetlast}{widgetmiddle}{widgetmiddle}{widgetlast}{widget}
\tcbbreakskininto{draft}{draft}{draft}{draft}{draft}


\clearpage
\subsection{Break by Hand (Faked Break)}
Since the appearance of broken boxes is done by skins, it is quite easy
to 'fake a break'. For this, you actually don't need the 'breakable' library at
all.

\begin{dispExample}
\tcbset{enhanced,equal height group=fakedbreak,
  colback=LightGreen,colframe=DarkGreen,
  width=(\linewidth-6mm)/3,nobeforeafter,
  left=1mm,right=1mm,top=1mm,bottom=1mm,middle=1mm}
%
\begin{tcolorbox}[title=My broken box,skin=enhancedfirst]
This is a box which breaks from one column to another
\end{tcolorbox}\hfill
\begin{tcolorbox}[skin=enhancedmiddle]
column. I am sorry to say that this is a trick.
Nevertheless, you may use this trick for your
\end{tcolorbox}\hfill
\begin{tcolorbox}[skin=enhancedlast]
own purposes.
\end{tcolorbox}
\end{dispExample}


