summaryrefslogtreecommitdiff
path: root/macros/latex/contrib/tcolorbox/tcolorbox.doc.intro.tex
blob: 4c8fb7683ad2c69562063af932fb24ac0f2b8bd5 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
% !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:latex}\frqq~\cite{sturm:latex}
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:mathe1,sturm:mathe2,sturm:mathe3}
as well.
With this package, you are invited to apply these boxes for similar projects.

The breaking news for version 2.00 was the support for breakable boxes.
This 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:etoolbox},
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:listings} 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:listings} and
  |listingsutf8| \cite{oberdiek:listingsutf8} 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 intend 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}