summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/doc/latex/tcolorbox/tcolorbox.doc.intro.tex
blob: f11470c6857b6b6d5260edc0cc73c5e1f7903911 (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
% !TeX root = tcolorbox.tex
% include file of tcolorbox.tex (manual of the LaTeX package tcolorbox)
\clearpage
\section{Introduction}
The package originates from the first edition of my book
\flqq{\citetitle{sturm:2012k}\frqq~\cite{sturm:2012k}
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| \cite{thorub:2007a}.
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.

\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:2010c}, |verbatim| \cite{schoepf:2001a},
|etoolbox| \cite{lehmann:2011a},
and |environ| \cite{robertson:2013a}.
|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:2010c} 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]{listings}{}{\mylib{listings}}
  Loads the package |listings| \cite{heinz:2007a} 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{heinz:2007a} and
  |listingsutf8| \cite{oberdiek:2011a} 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{rudolph:2011a} to
  typeset listings with the |Pygments| \cite{pygments:2013} 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 Section \ref{sec:breakable} from page \pageref{sec:breakable}.
\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}

\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}

\clearpage
\begin{docTcbKey}[library]{many}{}{style, no value}
  Loads the libraries \mylib{skins}, \mylib{breakable}, \mylib{hooks},
  \mylib{theorems}, and \mylib{fitting}.
  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{tcolorbox}[title={Package \texttt{tcolorbox}},center title,fonttitle=\bfseries,arc=0pt,
  colback=red!10!white,colframe=red!50!black]
  \begin{tcolorbox}[beamer,adjusted title=Basic Features,colframe=blue!50!black,colback=blue!10!white]
  Base package
  \end{tcolorbox}
  \tcbset{every box on layer 2/.style={reset,nobeforeafter,width=\linewidth/3-2mm,
    equal height group=packageoverview,beamer,colframe=blue!50!black,colback=blue!10!white}}
  \vspace{2mm}
  \begin{tcolorbox}[adjusted title=Advanced Features]
    \mylib{skins}\\
    \mylib{breakable}\\
    \mylib{theorems}\\
    \mylib{fitting}\\
    \mylib{hooks}
  \end{tcolorbox}
  \hfill
  \begin{tcolorbox}[adjusted title=Listings]
    \mylib{listings}\\
    \mylib{listingsutf8}
    \tcblower
    \mylib{minted}
  \end{tcolorbox}
  \hfill
  \begin{tcolorbox}[adjusted title=Documentation]
    \mylib{documentation}
  \end{tcolorbox}
\end{tcolorbox}