diff options
Diffstat (limited to 'macros/latex/contrib/tcolorbox/tcolorbox.doc.intro.tex')
-rw-r--r-- | macros/latex/contrib/tcolorbox/tcolorbox.doc.intro.tex | 225 |
1 files changed, 225 insertions, 0 deletions
diff --git a/macros/latex/contrib/tcolorbox/tcolorbox.doc.intro.tex b/macros/latex/contrib/tcolorbox/tcolorbox.doc.intro.tex new file mode 100644 index 0000000000..84d9b00b05 --- /dev/null +++ b/macros/latex/contrib/tcolorbox/tcolorbox.doc.intro.tex @@ -0,0 +1,225 @@ +% !TeX root = tcolorbox.tex +% include file of tcolorbox.tex (manual of the LaTeX package tcolorbox) +\clearpage +\section{Introduction}% +\tcbset{external/prefix=external/intro_}% +The package originates from the first edition of my book +\flqq{\citetitle{sturm:2016e}\frqq~\cite{sturm:2016e} +in about 2006. +For the \LaTeX\ examples and tutorials given there, I wanted to have +accentuated and colored boxes to display source code and +compiled text in combination. +Since, in my opinion, this type of boxes is also quite useful to highlight definitions +and theorems, I applied them for my lecture notes in +mathematics \cite{sturm:2007b,sturm:2008b,sturm:2010a} +as well. +With this package, you are invited to apply these boxes for similar projects. + +Starting with version 2.00, for all internal calculations +$\varepsilon$-\TeX\ \cite{breitenlohner:1998a} expressions are used +in replacement of the package |calc|. +The breaking news for version 2.00 is the support for breakable boxes. +This new feature allows new applications of the package without +affecting the core package too much if you do not need boxes to break automatically. +With version 2.20, the often requested 'side by side' mode for listings has been added. +With version 3.00, boxed titles are introduced together with improved +customization options for overlays, underlays, finishes, and own code extensions. + +\begin{tcolorbox}[enhanced,boxrule=0mm,boxsep=0mm,frame hidden,interior hidden, + left=0mm,right=0mm,top=0mm,bottom=0mm,watermark opacity=0.25,watermark zoom=1.2,before=\par\smallskip, + clip watermark=false, + watermark tikz={% + \path[fill=yellow,draw=yellow!75!red] (0,0) circle (1cm); + \fill[red] (45:5mm) circle (1mm); + \fill[red] (135:5mm) circle (1mm); + \draw[line width=1mm,red] (215:5mm) arc (215:325:5mm);}] +Since the first public release in 2011, I received a lot of feedback from all over the world. +I want to thank all who wrote me for supporting this package by sending bug reports +and ideas for new or better features. +\end{tcolorbox} + + +\subsection{Installation} +Typically, |tcolorbox| will be installed as part of a major \LaTeX\ distribution +and there is nothing special to do for a user. + +If you intend to make a local +installation \emph{by hand}, see the |README| file of the |tcolorbox| package +for some hints. The short story is: you have to install not only +|tcolorbox.sty|, but also all |*.code.tex| files in the local |texmf| tree. + + +\subsection{Loading the Package} +The base package |tcolorbox| loads the packages +|pgf| \cite{tantau:tikz_and_pgf}, |verbatim| \cite{schoepf:2001a}, +|etoolbox| \cite{lehmann:2018a}, +and |environ| \cite{robertson:2014a}. +|tcolorbox| itself is loaded in the usual manner in the preamble: +\begin{dispListing} +\usepackage{tcolorbox} +\end{dispListing} +The package takes option keys in the key-value syntax. +Alternatively, you may use these keys later in the preamble with +\refCom{tcbuselibrary} (see there). +For example, the key to typeset listings is: +\begin{dispListing} +\usepackage[listings]{tcolorbox} +\end{dispListing} + + +\clearpage +\subsection{Libraries}\label{sec:bibliothek} +The base package |tcolorbox| is extendable by program libraries. +This is done by using option keys while loading the package or inside +the preamble by applying the following macro with the same set of keys. + +\begin{docCommand}{tcbuselibrary}{\marg{key list}} + Loads the libraries given by the \meta{key list}. +\begin{dispListing} +\tcbuselibrary{listings,theorems} +\end{dispListing} +\end{docCommand} + +The following keys are used inside |\tcbuselibrary| respectively +|\usepackage| without the key tree path |/tcb/library/|. + +\begin{docTcbKey}[library]{skins}{}{\mylib{skins}} + Loads the package |tikz| \cite{tantau:tikz_and_pgf} and provides additional + styles (skins) for the appearance of the colored boxes; see + Section~\ref{sec:skins} from page~\pageref{sec:skins}. +\end{docTcbKey} + +\begin{docTcbKey}[library]{vignette}{}{\mylib{vignette}} + Provides code for more ornamental; see + Section~\ref{sec:vignette} from page~\pageref{sec:vignette}. +\end{docTcbKey} + +\begin{docTcbKey}[library]{raster}{}{\mylib{raster}} + Provides additional macros and options for typesetting multiple + boxes arranged in a kind of raster; + see Section~\ref{sec:raster} from page~\pageref{sec:raster}. +\end{docTcbKey} + +\begin{docTcbKey}[library]{listings}{}{\mylib{listings}} + Loads the package |listings| \cite{hoffmann:2018a} and provides additional + macros for typesetting listings which are described in Section~\ref{sec:listings} + from page~\pageref{sec:listings}. +\end{docTcbKey} + +\begin{docTcbKey}[library]{listingsutf8}{}{\mylib{listingsutf8}} + Loads the packages |listings| \cite{hoffmann:2018a} and + |listingsutf8| \cite{oberdiek:2016b} for UTF-8 support. + This is a variant of the library \mylib{listings} + and is described in Section \ref{sec:listings} + from page~\pageref{sec:listings}. +\end{docTcbKey} + +\begin{docTcbKey}[library]{minted}{}{\mylib{minted}} + Loads the package |minted| \cite{poore:minted} to + typeset listings with the |Pygments| \cite{pygments:web} tool, + also see \Vref{sec:listings}. +\end{docTcbKey} + +\begin{docTcbKey}[library]{theorems}{}{\mylib{theorems}} + Provides additional + macros for typesetting theorems which are described in Section~\ref{sec:theorems} + from page~\pageref{sec:theorems}. +\end{docTcbKey} + + +\begin{docTcbKey}[library]{breakable}{}{\mylib{breakable}} + Provides support for automatic box breaking from one page to another; + see \Fullref{sec:breakable}. +\end{docTcbKey} + +\begin{docTcbKey}[library]{magazine}{}{\mylib{magazine}} + Provides support for storing broken box parts to be used later or + in interchanged order, \Fullref{sec:magazine}. +\end{docTcbKey} + +\begin{docTcbKey}[library]{poster}{}{\mylib{poster}} + Provides support for creating posters, \Fullref{sec:poster}. +\end{docTcbKey} + +\begin{docTcbKey}[library]{fitting}{}{\mylib{fitting}} + Provides support for font size adaption of the box content to + the box dimensions; + see Section~\ref{sec:fitting} from page~\pageref{sec:fitting}. +\end{docTcbKey} + +\begin{docTcbKey}[library]{hooks}{}{\mylib{hooks}} + Extends several option keys to 'hookable' keys; + see Section~\ref{sec:hooks} from page~\pageref{sec:hooks}. +\end{docTcbKey} + +\clearpage +\begin{docTcbKey}[library]{xparse}{}{\mylib{xparse}} + Provides document command production with |xparse| for |tcolorbox|; + see Section~\ref{sec:xparse} from page~\pageref{sec:xparse}. +\end{docTcbKey} + +\begin{docTcbKey}[library]{external}{}{\mylib{external}} + Provides externalization support for stand-alone document snippets, + see \Fullref{sec:external}. +\end{docTcbKey} + +\begin{docTcbKey}[library]{documentation}{}{\mylib{documentation}} + Provides additional + macros for typesetting \LaTeX\ documentations + which are described in Section~\ref{sec:documentation} + from page~\pageref{sec:documentation}. +\end{docTcbKey} + +\begin{docTcbKey}[library]{many}{}{style, no value} + Loads the libraries \mylib{skins}, \mylib{breakable}, \mylib{raster}, \mylib{hooks}, + \mylib{theorems}, \mylib{fitting}, and \mylib{xparse}. + Use this shortcut, if you want to use all features of |tcolorbox| + with exception of typesetting listings and using + the specialized \mylib{documentation} library. +\end{docTcbKey} + +\begin{docTcbKey}[library]{most}{}{style, no value} + Loads all libraries except \mylib{minted} and \mylib{documentation}. + Use this shortcut, if you want to use all features of |tcolorbox| + with exception of using the |minted| package and using + the specialized \mylib{documentation} library. +\end{docTcbKey} + +\begin{docTcbKey}[library]{all}{}{style, no value} + Loads all libraries. Use this shortcut only, if you indend to use the + \mylib{documentation} library. +\end{docTcbKey} + + +\begin{extcolorbox}[runs=2]{intro_packageoverview} + [title={Package \texttt{tcolorbox}},center title,fonttitle=\bfseries,arc=0pt, + colback=red!10!white, + interior style={fill tile image*={width=2cm}{pink_marble.png},fill image opacity=0.5}, + colframe=red!50!black] + \begin{tcolorbox}[beamer,adjusted title=Basic Features,colframe=blue!50!black,colback=blue!10!white] + Base package + \end{tcolorbox} + \begin{tcbitemize}[raster columns=3,raster before skip=2mm,raster after skip=0pt, + raster equal height,beamer,colframe=blue!50!black,colback=blue!10!white] + \tcbitem[adjusted title=Advanced Features] + \mylib{breakable}\\ + \mylib{external}\\ + \mylib{fitting}\\ + \mylib{hooks}\\ + \mylib{magazine}\\ + \mylib{poster}\\ + \mylib{raster}\\ + \mylib{skins}\\ + \mylib{theorems}\\ + \mylib{vignette}\\ + \mylib{xparse} + \tcbitem[adjusted title=Advanced Listings] + \mylib{listings}\\ + \mylib{listingsutf8} + \tcblower + \mylib{minted} + \tcbitem[adjusted title=Documentation] + \mylib{documentation} + \end{tcbitemize} +\end{extcolorbox} + |