summaryrefslogtreecommitdiff
path: root/macros/latex/contrib/tcolorbox/tcolorbox.doc.magazine.tex
diff options
context:
space:
mode:
authorNorbert Preining <norbert@preining.info>2019-09-02 13:46:59 +0900
committerNorbert Preining <norbert@preining.info>2019-09-02 13:46:59 +0900
commite0c6872cf40896c7be36b11dcc744620f10adf1d (patch)
tree60335e10d2f4354b0674ec22d7b53f0f8abee672 /macros/latex/contrib/tcolorbox/tcolorbox.doc.magazine.tex
Initial commit
Diffstat (limited to 'macros/latex/contrib/tcolorbox/tcolorbox.doc.magazine.tex')
-rw-r--r--macros/latex/contrib/tcolorbox/tcolorbox.doc.magazine.tex516
1 files changed, 516 insertions, 0 deletions
diff --git a/macros/latex/contrib/tcolorbox/tcolorbox.doc.magazine.tex b/macros/latex/contrib/tcolorbox/tcolorbox.doc.magazine.tex
new file mode 100644
index 0000000000..bf9c106bc4
--- /dev/null
+++ b/macros/latex/contrib/tcolorbox/tcolorbox.doc.magazine.tex
@@ -0,0 +1,516 @@
+% !TeX root = tcolorbox.tex
+% include file of tcolorbox.tex (manual of the LaTeX package tcolorbox)
+\clearpage
+\section{Library \mylib{magazine}}\label{sec:magazine}%
+\tcbset{external/prefix=external/magazine_}%
+\newboxarray{myarticle}
+
+\begin{tcolorbox}[
+ enhanced jigsaw,
+ size=small,width=6cm,
+ title=Example Article,
+ fonttitle=\bfseries,center title,
+ fontupper=\small,
+ %height fixed for=first and middle,
+ watermark text=\arabic{tcbbreakpart},
+ breakable,
+ break at=8.5\baselineskip/9\baselineskip,
+ reset and store to box array=myarticle,
+ colframe=green!50!black,
+ colback=green!10,
+ pad at break=5mm,
+ ]
+This is an example for an article which starts right here and
+is continued to the following pages.
+The body text for the article is written inside a single
+|tcolorbox|. This box is split into parts using the tools from
+this section, namely \refKey{/tcb/reset and store to box array}
+with a new box array |myarticle| which was created by
+|\newboxarray{myarticle}|.
+
+The resulting parts are distributed throughout this
+\Fullref{sec:magazine} using \refCom{consumetcboxarray}
+at the appropriate places you see.
+The linking texts like \emph{continued on page x} are created
+by \refKey{/tcb/finish} commands for the embedding \refCom{tcbox}.
+To label the box parts, \refKey{/tcb/phantomlabel} is used.
+
+These quite small partial boxes are for demonstration purposes.
+With the tools of this section, a magazine type document could be
+created, but this still needs a lot of manual control.
+\end{tcolorbox}
+
+\newtcolorbox{articleside}[1][]{blanker,sidebyside,sidebyside gap=5mm,sidebyside align=top seam,
+ parbox=false,righthand width=6cm,
+ goto/.style={finish={\node[above=-2pt,color=green!50!black] at (frame.south)
+ {\slshape\scriptsize --- continued on page~\hypersetup{linkcolor=green!50!black}\pageref{myarticle-##1}\ \textcolor{green!50!black}{---}};}},
+ from/.style={finish={\node[below=-1pt,color=green!50!black] at (frame.north)
+ {\slshape\scriptsize --- continued from page~\hypersetup{linkcolor=green!50!black}\pageref{myarticle-##1}\ \textcolor{green!50!black}{---}};}},
+ #1}
+
+\begin{articleside}[after skip=6pt]
+The main purpose of this library is to store a |tcolorbox| into an array
+of box registers for later usage.
+
+If the |tcolorbox| is not breakable, there is not much add-on
+compared to usual \TeX/\LaTeX\ box storage and usage (and you do not really need this
+library for that use case).
+For a breakable |tcolorbox|, this library allows to capture all partial boxes
+into a sequence of registers. The partial boxes can be used anywhere in
+arbitrary order.
+\tcblower\consumetcboxarray[myarticle]{1}{blanker,nobeforeafter,phantomlabel=myarticle-one,goto=two}
+\end{articleside}
+
+The name of this library indicates \emph{magazine} in the sense of storage,
+but also in the sense of a journal where an article often is \emph{continued on page x}.
+An example for this kind of application is given throughout this section starting
+on the right hand side. The creation of this library was motivated by
+Ulrike Fischer and Steven B.~Segletes.
+
+The library is loaded by a package option or inside the preamble by:
+\begin{dispListing}
+ \tcbuselibrary{magazine}
+\end{dispListing}
+This also loads the library \mylib{breakable}, see \Fullref{sec:breakable}.
+
+\begin{marker}
+The box register operations of this library are global. \TeX\ grouping will
+not clear the registers when leaving the current group. Also be aware that
+extensive use of large box arrays may eat up \TeX's available memory and
+registers.
+\end{marker}
+
+\subsection{Creation and Resetting of Box Arrays}\label{subsec:magazine_creation}
+
+\begin{docCommand}[doc new=2015-07-13]{newboxarray}{\marg{name}}
+ This creates a new box array called \meta{name}. There already is a
+ box array available with name |default| which can be used directly.
+ Note that the creation is a global operation.
+\begin{dispListing}
+\newboxarray{myarray}
+\end{dispListing}
+\end{docCommand}
+
+
+\begin{docCommand}[doc new=2015-07-13]{boxarrayreset}{\oarg{name}}
+ Resets the size counter of a box array \meta{name} to zero.
+ If \meta{name} is not provided, |default| is used as name.
+ Use this or \refKey{/tcb/reset box array} before
+ you apply \refKey{/tcb/store to box array}. Otherwise, all boxes would
+ be appended to the already existing boxes.
+ This command does not clear box registers.
+\begin{dispListing}
+\boxarrayreset % resets 'default'
+\boxarrayreset{myarray} % resets 'myarray'
+\end{dispListing}
+\end{docCommand}
+
+\enlargethispage*{20mm}
+
+\begin{docTcbKey}[][doc new=2015-07-13]{reset box array}{\colOpt{=\meta{name}}}{default |default|, initially unset}
+ Resets the size counter of a box array \meta{name} to zero.
+ Use this or \refCom{boxarrayreset} (which does the same) before
+ you apply \refKey{/tcb/store to box array}.
+\begin{dispListing}
+\tcbset{
+ reset box array, % resets 'default'
+ reset box array=myarray, % resets 'myarray'
+}
+\end{dispListing}
+\end{docTcbKey}
+
+\clearpage
+\begin{docCommand}[doc new=2015-07-13]{boxarrayclear}{\oarg{name}}
+ Works like \refCom{boxarrayreset} to reset the size counter of a
+ box array \meta{name} to zero. Additionally, all allocated box registers
+ of the box array are cleared of their content.
+ Note that the allocated box registers stay allocated. So, this may be
+ useful to clear memory, but not to free registers for other applications.
+ If \refCom{consumeboxarray} or \refCom{consumetcboxarray} was used to
+ apply the stored boxes, there is no advantage in using \refCom{boxarrayclear}.
+\begin{dispListing}
+\boxarrayclear % clears 'default'
+\boxarrayclear{myarray} % clears 'myarray'
+\end{dispListing}
+\end{docCommand}
+
+
+
+\subsection{Storing Content}\label{subsec:magazine_storing}
+
+\begin{docTcbKey}[][doc new=2015-07-13]{store to box array}{\colOpt{=\meta{name}}}{default |default|, initially unset}
+Stores a |tcolorbox| or all parts of a break sequence of a |tcolorbox| into
+a box array \meta{name}. If no \meta{name} is given, the already existing |default|
+box array is used. Otherwise, the box array has to be created beforehand
+with \refCom{newboxarray}. Note that the box has to be \refKey{/tcb/breakable},
+if the box shall break into several parts.
+Typically, manual break points are additionally defined by \refKey{/tcb/break at}.
+Otherwise, the box parts will have a length of about |\textheight|.
+For most use cases, a \refKey{/tcb/reset box array} should be applied
+to reset the box array counter.\enlargethispage*{2cm}
+
+\begin{exdispExample}{storetoboxarray_1}
+% \usepackage{lipsum}
+\begin{tcolorbox}[enhanced jigsaw,size=fbox,width=4cm,
+ colback=yellow!10,colframe=yellow!10!black,
+ enforce breakable,% use only breakable in the real world!
+ break at=7cm/4cm,
+ height fixed for=all,
+ watermark text=\arabic{tcbbreakpart},
+ reset box array,
+ store to box array
+ ]
+\lipsum[1]
+\end{tcolorbox}
+
+\useboxarray{1}\hfill
+\begin{tabular}[b]{cc}
+\multicolumn{2}{c}{\includegraphics[width=7cm]{Basilica_5.png}}\\
+\useboxarray{2} & \useboxarray{3}
+\end{tabular}
+\end{exdispExample}
+
+\clearpage
+If the first box part should fill the rest of the available space of
+the current page, you can use |\pagegoal-\pagetotal| minus some distance for
+the first element of \refKey{/tcb/break at}. You may want to have some
+additional distance to the preceeding text.
+
+\begin{dispListing}
+% \usepackage{lipsum}
+\begin{tcolorbox}[enhanced,breakable,
+ reset box array,
+ store to box array,
+ break at=\pagegoal-\pagetotal-5mm/0pt,
+ height fixed for=first and middle]
+\lipsum[1-15]
+\end{tcolorbox}%
+%
+\consumetcboxarray{1}{blanker,before=\par\vfill\noindent}
+\end{dispListing}
+
+
+\begin{exdispExample}{storetoboxarray_2}
+\begin{tcolorbox}[blanker,width=4cm,
+ fontupper=\footnotesize,
+ enforce breakable,% use only breakable in the real world!
+ break at=4cm,
+ height fixed for=all,
+ watermark text=\arabic{tcbbreakpart},
+ reset box array,
+ store to box array
+ ]
+\includegraphics[width=\linewidth]{Basilica_5.png}\par
+\lipsum[1-2]
+\end{tcolorbox}
+
+\begin{tcbitemize}[raster columns=3,raster equal height,
+ size=small,halign=center,sharp corners,colback=blue!5]
+\tcbitem\consumeboxarray{5}
+\tcbitem\consumeboxarray{6}
+\tcbitem\consumeboxarray{1}
+\tcbitem\consumeboxarray{2}
+\tcbitem\consumeboxarray{3}
+\tcbitem\consumeboxarray{4}
+\end{tcbitemize}
+\end{exdispExample}
+\end{docTcbKey}
+
+
+\begin{docTcbKey}[][doc new=2015-07-13]{reset and store to box array}{\colOpt{=\meta{name}}}{style, default |default|, initially unset}
+ Combination of \refKey{/tcb/reset box array} and \refKey{/tcb/store to box array}.
+\end{docTcbKey}
+
+
+
+\begin{docTcbKey}[][doc new=2015-07-13]{do not store to box array}{}{style, no default, initially set}
+Disables the \refKey{/tcb/store to box array} option, if set before.
+\end{docTcbKey}
+
+
+\begin{docEnvironment}[doc new=2015-07-13]{boxarraystore}{\marg{name}}
+ Stores the environment content into a box array \meta{name}.
+ This corresponds to the standard \LaTeX\ environment |lrbox|, but
+ the storage operation is global. As long as \refCom{boxarrayreset} is
+ not used, every new \refEnv{boxarraystore} adds a further box to
+ the array.
+
+\begin{dispExample}
+\boxarrayreset
+\begin{boxarraystore}{default}\fbox{Mary}\end{boxarraystore}
+\begin{boxarraystore}{default}\fbox{Had}\end{boxarraystore}
+\begin{boxarraystore}{default}\fbox{a}\end{boxarraystore}
+\begin{boxarraystore}{default}\fbox{Little}\end{boxarraystore}
+\begin{boxarraystore}{default}\fbox{Lamb}\end{boxarraystore}
+\useboxarray{5}\useboxarray{4}\useboxarray{3}\useboxarray{2}\useboxarray{1}\hfill
+\useboxarray{1}\useboxarray{5}
+\end{dispExample}
+\end{docEnvironment}
+
+\subsection{Retrieving Content}\label{subsec:magazine_retrieve}
+
+\begin{docCommand}[doc new=2015-07-13]{boxarraygetsize}{\oarg{name}\marg{macro}}
+\begin{articleside}[before skip=5pt]
+ Stores the current size of a box array \meta{name} into a given \meta{macro}.
+ If no \meta{name} is given, the already existing |default| box array is used.
+\begin{dispExample}
+\boxarraygetsize{\mysize}
+Current size of the default box array:
+\mysize.
+\end{dispExample}
+\tcblower\consumetcboxarray[myarticle]{2}{blanker,nobeforeafter,phantomlabel=myarticle-two,from=one,goto=three}
+\end{articleside}
+\end{docCommand}
+
+\begin{docCommand}[doc new=2015-07-13]{useboxarray}{\oarg{name}\marg{index}}
+ Typesets the box with the given \meta{index} number from the box array \meta{name}.
+ If no \meta{name} is given, the already existing |default| box array is used.
+ It is considered an error, if a not existing box array \meta{name} is used.
+ It is silently ignored, if the \meta{index} is out of range.
+ Note that \refCom{useboxarray} corresponds to the standard |\usebox| macro,
+ respectively, |\copy|.
+\begin{dispExample}
+\boxarraygetsize{\mysize}
+\foreach \n in {1,...,\mysize} { \useboxarray{\n} }
+\end{dispExample}
+\end{docCommand}
+
+\clearpage
+\begin{docCommand}[doc new=2015-07-13]{usetcboxarray}{\oarg{name}\marg{index}\marg{options}}
+ Typesets the box with the given \meta{index} number from the box array \meta{name}
+ using \refCom{useboxarray} as content of a \refCom{tcbox}.
+ If no \meta{name} is given, the already existing |default| box array is used.
+ It is considered an error, if a not existing box array \meta{name} is used.
+ It is silently ignored, if the \meta{index} is out of range.
+ The \refCom{tcbox} can be customized by |tcolorbox| \meta{options}.
+\begin{dispExample}
+\boxarraygetsize{\mysize}
+\foreach \n in {1,...,\mysize} { \usetcboxarray{\n}{on line,colframe=yellow,
+ colback=yellow!10} }
+\end{dispExample}
+\end{docCommand}
+
+
+\begin{docCommand}[doc new=2015-07-13]{consumeboxarray}{\oarg{name}\marg{index}}
+ Typesets the box with the given \meta{index} number from the box array \meta{name}.
+ If no \meta{name} is given, the already existing |default| box array is used.
+ It is considered an error, if a not existing box array \meta{name} is used.
+ It is silently ignored, if the \meta{index} is out of range.
+ In contrast to \refCom{useboxarray},
+ \refCom{consumeboxarray} corresponds to the standard |\box| macro, i.e.
+ after typesetting the box register is cleared and cannot be used again.
+\begin{dispExample}
+\boxarraygetsize{\mysize}
+First run: \foreach \n in {1,...,\mysize} { \consumeboxarray{\n} }
+\par
+Second run: \foreach \n in {1,...,\mysize} { \consumeboxarray{\n} }
+\end{dispExample}
+\end{docCommand}
+
+
+\begin{docCommand}[doc new=2015-07-13]{consumetcboxarray}{\oarg{name}\marg{index}\marg{options}}
+\begin{articleside}[before skip=5pt]
+ Typesets the box with the given \meta{index} number from the box array \meta{name}
+ using \refCom{consumeboxarray} as content of a \refCom{tcbox}.
+ If no \meta{name} is given, the already existing |default| box array is used.
+ It is considered an error, if a not existing box array \meta{name} is used.
+ It is silently ignored, if the \meta{index} is out of range.
+ The \refCom{tcbox} can be customized by |tcolorbox| \meta{options}.
+ After typesetting the box register is cleared and cannot be used again.
+\tcblower\consumetcboxarray[myarticle]{3}{blanker,nobeforeafter,phantomlabel=myarticle-three,,from=two,goto=four}
+\end{articleside}
+\begin{exdispExample}{consumetcboxarray}
+% \usepackage{lipsum}
+\begin{tcolorbox}[enhanced jigsaw,size=fbox,width=6cm,
+ colback=yellow!10,colframe=yellow!10!black,
+ enforce breakable,% use only breakable in the real world!
+ break at=5cm,
+ watermark text=\arabic{tcbbreakpart},
+ reset and store to box array
+ ]
+\lipsum[1]
+\end{tcolorbox}
+
+\consumeboxarray{2} \hfill \consumeboxarray{1} \hfill \consumeboxarray{1}
+\end{exdispExample}
+\end{docCommand}
+
+
+\begin{docCommand}[doc new=2015-07-13]{boxarraygetbox}{\oarg{name}\marg{macro}\marg{index}}
+ Assigns the box with the given \meta{index} number from the box array \meta{name}
+ to a \meta{macro}.
+ If no \meta{name} is given, the already existing |default| box array is used.
+ It is considered an error, if a not existing box array \meta{name} is used.
+ If the \meta{index} is out of range, the \meta{macro} will be undefined.
+\begin{exdispExample}{boxarraygetbox}
+\tcbox[size=small,colframe=blue!20,colback=yellow!5,on line,
+ reset and store to box array]{Test}
+
+\boxarraygetsize{\mysize} Array size: \mysize
+
+\boxarraygetbox{\mybox}{1}
+Box width: \the\wd\mybox
+\quad\usebox{\mybox}
+\end{exdispExample}
+\end{docCommand}
+
+
+\begin{docCommand}[doc new=2017-06-27]{ifboxarrayempty}{\oarg{name}\marg{index}\marg{true}\marg{false}}
+ Tests the box with the given \meta{index} number from the box array \meta{name}
+ for emptiness be empty and executes \meta{true} if it is empty, and \meta{false} otherwise.
+ If no \meta{name} is given, the already existing |default| box array is used.
+ It is considered an error, if a not existing box array \meta{name} is used.
+\begin{exdispExample}{ifboxarrayempty}
+\tcbox[size=small,colframe=blue!20,colback=yellow!5,on line,
+ reset and store to box array]{Test}
+
+\ifboxarrayempty{1}{no Box~1}{Box~1: \useboxarray{1}},
+\ifboxarrayempty{2}{no Box~2}{Box~2: \useboxarray{2}}
+\end{exdispExample}
+\end{docCommand}
+
+
+\clearpage
+\subsection{Box Dimensions}\label{subsec:magazine_dimensions}
+
+\begin{docCommand}[doc new=2015-07-13]{boxarraygetwidth}{\oarg{name}\marg{macro}\marg{index}}
+ Assigns the width of the box with the given \meta{index} number from the box array \meta{name}
+ to a \meta{macro}.
+ If no \meta{name} is given, the already existing |default| box array is used.
+ It is considered an error, if a not existing box array \meta{name} is used.
+ If the \meta{index} is out of range, the \meta{macro} will be set to |0pt|.
+\begin{exdispExample}{boxarraygetwidth}
+\tcbox[size=small,colframe=blue!20,colback=yellow!5,on line,
+ reset and store to box array]{Test}
+
+\begin{tabular}{ll}
+\useboxarray{1} & width of box 1: \boxarraygetwidth{\mylen}{1} \mylen\\
+\useboxarray{2} & width of box 2: \boxarraygetwidth{\mylen}{2} \mylen
+\end{tabular}
+\end{exdispExample}
+\end{docCommand}
+
+
+\begin{docCommand}[doc new=2015-07-13]{boxarraygetheight}{\oarg{name}\marg{macro}\marg{index}}
+ Assigns the height of the box with the given \meta{index} number from the box array \meta{name}
+ to a \meta{macro}.
+ If no \meta{name} is given, the already existing |default| box array is used.
+ It is considered an error, if a not existing box array \meta{name} is used.
+ If the \meta{index} is out of range, the \meta{macro} will be set to |0pt|.
+\begin{exdispExample}{boxarraygetheight}
+\tcbox[size=small,colframe=blue!20,colback=yellow!5,on line,
+ reset and store to box array]{Test}
+
+\begin{tabular}{ll}
+\useboxarray{1} & height of box 1: \boxarraygetheight{\mylen}{1} \mylen\\
+\useboxarray{2} & height of box 2: \boxarraygetheight{\mylen}{2} \mylen
+\end{tabular}
+\end{exdispExample}
+\end{docCommand}
+
+
+\begin{docCommand}[doc new=2015-07-13]{boxarraygetdepth}{\oarg{name}\marg{macro}\marg{index}}
+ Assigns the depth of the box with the given \meta{index} number from the box array \meta{name}
+ to a \meta{macro}.
+ If no \meta{name} is given, the already existing |default| box array is used.
+ It is considered an error, if a not existing box array \meta{name} is used.
+ If the \meta{index} is out of range, the \meta{macro} will be set to |0pt|.
+\begin{exdispExample}{boxarraygetdepth}
+\tcbox[size=small,colframe=blue!20,colback=yellow!5,on line,
+ reset and store to box array]{Test}
+
+\begin{tabular}{ll}
+\useboxarray{1} & depth of box 1: \boxarraygetdepth{\mylen}{1} \mylen\\
+\useboxarray{2} & depth of box 2: \boxarraygetdepth{\mylen}{2} \mylen
+\end{tabular}
+\end{exdispExample}
+\end{docCommand}
+
+
+\clearpage
+\begin{docCommand}[doc new=2015-07-13]{boxarraygettotalheight}{\oarg{name}\marg{macro}\marg{index}}
+\begin{articleside}[before skip=5pt]
+ Assigns the total height of the box with the given \meta{index} number from the box array \meta{name}
+ to a \meta{macro}.
+ If no \meta{name} is given, the already existing |default| box array is used.
+ It is considered an error, if a not existing box array \meta{name} is used.
+ If the \meta{index} is out of range, the \meta{macro} will be set to |0pt|.
+\tcblower\consumetcboxarray[myarticle]{4}{blanker,nobeforeafter,phantomlabel=myarticle-four,from=three}
+\end{articleside}
+\begin{exdispExample}{boxarraygettotalheight}
+\boxarrayreset
+\tcbox[size=small,colframe=blue!20,colback=yellow!5,on line,
+ store to box array]{Test}
+
+\begin{tabular}{ll}
+\useboxarray{1} & total height of box 1: \boxarraygettotalheight{\mylen}{1} \mylen\\
+\useboxarray{2} & total height of box 2: \boxarraygettotalheight{\mylen}{2} \mylen
+\end{tabular}
+\end{exdispExample}
+\end{docCommand}
+
+\clearpage
+\subsection{Leaflet Example}
+The following full application example can be used to create leaflets.
+Obviously, the code can be adapted and customized in many ways.
+
+\begin{tcblisting}{
+ enhanced jigsaw,lower separated=false,breakable,
+ listing style=mydocumentation,base example,
+ listing and comment,
+ pdf comment,freeze pdf,
+ comment style={raster columns=1},
+ compilable listing,
+ run pdflatex}
+\documentclass[a4paper,landscape]{article}
+\usepackage[noheadfoot,margin=0pt]{geometry}
+\usepackage[skins,raster,magazine]{tcolorbox}
+\usepackage{lipsum}
+
+\newenvironment{leaflet}[1][]{%
+ \begin{tcolorbox}[nobeforeafter,empty,colback=white,
+ sharp corners,size=minimal,left=10mm,right=10mm,top=10mm,bottom=10mm,
+ width=\textwidth/3,
+ breakable,
+ break at=\textheight,
+ height fixed for=all,
+ reset box array,
+ store to box array,#1]}
+ {\end{tcolorbox}%
+ \begin{tcbitemize}[raster columns=3,raster equal skip=0pt,blankest]
+ \tcbitem\consumeboxarray{5}
+ \tcbitem\consumeboxarray{6}
+ \tcbitem\consumeboxarray{1}
+ \tcbitem\consumeboxarray{2}
+ \tcbitem\consumeboxarray{3}
+ \tcbitem\consumeboxarray{4}
+ \end{tcbitemize}%
+ }
+
+\pagestyle{empty}
+\begin{document}
+
+\begin{leaflet}[underlay={\node[above=5mm,font=\footnotesize]
+ at (frame.south) {- \arabic{tcbbreakpart} -};}]
+ \includegraphics[width=\linewidth]{Basilica_5.png}
+ \begin{center}
+ \bfseries\LARGE Example
+ \end{center}
+
+ \section{Introduction}
+ \lipsum[1]
+
+ \section{Main Part A}
+ \lipsum[2-8]
+
+ \section{Main Part B}
+ \lipsum[9-15]
+
+ \section{Conclusion}
+ \lipsum[16-18]
+\end{leaflet}
+
+\end{document}
+\end{tcblisting}
+
+