summaryrefslogtreecommitdiff
path: root/macros/latex/contrib/tcolorbox/tcolorbox.doc.listings.tex
diff options
context:
space:
mode:
Diffstat (limited to 'macros/latex/contrib/tcolorbox/tcolorbox.doc.listings.tex')
-rw-r--r--macros/latex/contrib/tcolorbox/tcolorbox.doc.listings.tex1567
1 files changed, 1567 insertions, 0 deletions
diff --git a/macros/latex/contrib/tcolorbox/tcolorbox.doc.listings.tex b/macros/latex/contrib/tcolorbox/tcolorbox.doc.listings.tex
new file mode 100644
index 0000000000..2abe145bb6
--- /dev/null
+++ b/macros/latex/contrib/tcolorbox/tcolorbox.doc.listings.tex
@@ -0,0 +1,1567 @@
+% !TeX root = tcolorbox.tex
+% include file of tcolorbox.tex (manual of the LaTeX package tcolorbox)
+\clearpage
+\section{Libraries
+ \mylib{listings},
+ \mylib{listingsutf8}, and
+ \mylib{minted}}\label{sec:listings}%
+\tcbset{external/prefix=external/listings_}%
+
+\subsection{Loading the Libraries}
+In contrast to other |tcolorbox| libraries, the libraries
+\mylib{listings}, \mylib{listingsutf8}, and \mylib{minted} are concurrent in the sense that
+they all do the same thing, i.\,e.\ displaying listings with or without typesetting
+the listing in \LaTeX\ parallel.
+The difference is the underlying \LaTeX\ package which does the core job for
+displaying a listing. So, typically, you need just \emph{one} of these
+libraries. If you do not have a clue which one of them you should use
+and you are using |pdflatex|, you should take \mylib{listingsutf8}.
+If you are using |xelatex| or |lualatex|, you should take \mylib{listings}
+as |xelatex| and |lualatex| are not compatible with \mylib{listingsutf8}.
+
+\begin{marker}
+The order in which the libraries are included influences the default settings and
+the \refKey{/tcb/reset} behavior. The settings of a later loaded library overwrite
+the settings of a previous loaded library. A library is never loaded twice.
+\end{marker}
+
+
+\subsubsection{Loading \mylib{listings}}
+This library uses the package |listings| \cite{hoffmann:2018a} to typeset
+listings. It is loaded by a package option or inside the preamble by:
+\begin{dispListing}
+\tcbuselibrary{listings}
+\end{dispListing}
+This also loads the package |listings| \cite{hoffmann:2018a}.
+
+The \refKey{/tcb/listing engine} is set to |listings| by the library.
+To reactivate this setting, if overwritten by other libraries, use
+\begin{dispListing}
+\tcbset{listing engine=listings}
+\end{dispListing}
+
+\subsubsection{Loading \mylib{listingsutf8}}
+\begin{marker}
+This library is not needed (and troublesome) when using Xe\LaTeX\ or Lua\LaTeX.
+\end{marker}
+To extend |listings| for UTF-8 encoded sources, you can use the support from
+the package |listingsutf8| \cite{oberdiek:2016b} by loading the library
+variant \mylib{listingsutf8}.
+\begin{dispListing}
+\tcbuselibrary{listingsutf8}
+\tcbset{listing utf8=latin1}% optional; 'latin1' is the default.
+\end{dispListing}
+This also loads the library \mylib{listings}
+and the packages |listings| \cite{hoffmann:2018a}
+and |listingsutf8| \cite{oberdiek:2016b}.
+
+The \refKey{/tcb/listing engine} is set to |listings| by the library.
+To reactivate this setting, if overwritten by other libraries, use
+\begin{dispListing}
+\tcbset{listing engine=listings}
+\end{dispListing}
+
+
+\clearpage
+\subsubsection{Loading \mylib{minted}}
+This library uses the package |minted| \cite{poore:minted} to typeset
+listings. It is loaded by a package option or inside the preamble by:
+\begin{dispListing}
+\tcbuselibrary{minted}
+\end{dispListing}
+This also loads the package |minted| \cite{poore:minted}.
+
+\begin{marker}
+The |minted| package uses the external tool |Pygments| \cite{pygments:web}
+to apply syntax highlighting. It has to be installed and set up, before the
+library can be used, see \cite{poore:minted} and \cite{pygments:web}.
+The |tcolorbox| library \mylib{minted} does not work, if the package
+|minted| \cite{poore:minted} does not work.
+\end{marker}
+
+The \refKey{/tcb/listing engine} is set to |minted| by the library.
+To reactivate this setting, if overwritten by other libraries, use
+\begin{dispListing}
+\tcbset{listing engine=minted}
+\end{dispListing}
+
+
+\subsection{Common Macros of the Libraries}
+
+\begin{docEnvironment}{tcblisting}{\marg{options}}
+ Creates a colored box based on a \refEnv{tcolorbox}.
+ Controlled by the given \meta{options}, the
+ environment content is typeset normally and/or as a listing.
+ Furthermore, the \meta{options} control appearance and functions of
+ the |tcolorbox|.
+ By default, the listing is interpreted as a \LaTeX\ listing.
+\begin{dispExample}
+\begin{tcblisting}{colback=red!5!white,colframe=red!75!black}
+This is a \LaTeX\ example which displays the text as source code
+and in compiled form.
+\end{tcblisting}
+\end{dispExample}
+
+\clearpage
+
+\begin{dispExample}
+% \tcbuselibrary{listings} /or/ \tcbuselibrary{listingsutf8}
+\begin{tcblisting}{colback=yellow!5,colframe=yellow!50!black,listing only,
+ title=This is source code in another language (XML), fonttitle=\bfseries,
+ listing options={language=XML,columns=fullflexible,keywordstyle=\color{red}}}
+<?xml version="1.0"?>
+<project name="Package tcolorbox" default="documentation" basedir=".">
+ <description>
+ Apache Ant build file (http://ant.apache.org/)
+ </description>
+</project>
+\end{tcblisting}
+\end{dispExample}
+
+\enlargethispage*{10mm}
+
+\begin{dispExample}
+% \tcbuselibrary{minted}
+\begin{tcblisting}{colback=yellow!5,colframe=yellow!50!black,listing only,
+ title=This is source code in another language (XML), fonttitle=\bfseries,
+ listing engine=minted,minted language=xml}
+<?xml version="1.0"?>
+<project name="Package tcolorbox" default="documentation" basedir=".">
+ <description>
+ Apache Ant build file (http://ant.apache.org/)
+ </description>
+</project>
+\end{tcblisting}
+\end{dispExample}
+
+
+
+\begin{dispExample}
+% This box is as wide as needed (listing only !!)
+% \tcbuselibrary{skins}
+\begin{tcblisting}{colback=green!5!white,colframe=green!50!black,listing only,
+ hbox,enhanced,drop fuzzy shadow,before=\begin{center},after=\end{center}}
+\begin{tikzpicture}
+\fill[red] (0,0) rectangle (1,1);
+\end{tikzpicture}
+\end{tcblisting}
+\end{dispExample}
+\end{docEnvironment}
+
+
+\clearpage
+\begin{docEnvironment}{tcboutputlisting}{}
+ Saves the environment content to a file which is named by the key value of
+ |listing file|. Later, this file can be loaded by
+ |\tcbinputlisting| or |\tcbuselistingtext| or |\tcbuselistinglisting|.
+\begin{dispListing}
+\begin{tcboutputlisting}
+This \textbf{text} is written to a standardized file for later usage.
+\end{tcboutputlisting}
+\end{dispListing}
+\end{docEnvironment}
+
+
+\begin{docCommand}{tcbinputlisting}{\marg{options}}
+ Creates a colored boxed based on a |tcolorbox|. The text content is read
+ from a file named by the key value of |listing file|. Apart from that,
+ the function is equal to that of \refEnv{tcblisting}.
+\begin{dispExample}
+\tcbinputlisting{colback=red!5!white,colframe=red!75!black,text only}
+\tcbinputlisting{colback=green!5,colframe=green!75!black,listing only}
+\end{dispExample}
+\end{docCommand}
+
+\begin{docCommand}{tcbuselistingtext}{}
+ Loads text from a file named by the key value of |listing file|.
+\begin{dispExample}
+\tcbuselistingtext
+\end{dispExample}
+\end{docCommand}
+
+
+\begin{docCommand}{tcbuselistinglisting}{}
+ Typesets text as listing from a file named by the key value of |listing file|.
+\begin{dispExample}
+\tcbuselistinglisting
+\end{dispExample}
+\end{docCommand}
+
+%\enlargethispage*{5mm}
+\begin{docCommand}{tcbusetemplisting}{}
+ Typesets text as listing from a temporary file which was written by
+ \refEnv{tcbwritetemp}.
+\end{docCommand}
+
+
+\clearpage
+\begin{marker}
+See \Vref{subsec:xparse_listing} and \Vref{subsec:xparse_inputlisting} for more
+elaborate methods to create new environments and commands.
+\end{marker}
+\begin{marker}
+If a new sort of |tcblisting| environments should be created with
+one optional argument only, one is highly recommended to use
+\refCom{DeclareTCBListing} or \refCom{NewTCBListing}
+instead of \refCom{newtcblisting} to
+avoid content scanning problems.
+\end{marker}
+
+\begin{docCommand}{newtcblisting}{\oarg{init options}\marg{name}\oarg{number}\oarg{default}\marg{options}}
+ Creates a new environment \meta{name} based on \refEnv{tcblisting}.
+ Basically, |\newtcblisting| operates like |\newenvironment|. This means,
+ the new environment \meta{name} optionally takes \meta{number} arguments, where
+ \meta{default} is the default value for the optional first argument.
+ The \meta{options} are given to the underlying |tcblisting|.
+ Note that \refKey{/tcb/savedelimiter} is set to the given \meta{name}
+ automatically.
+ The \meta{init options} allow setting up automatic numbering,
+ see Section \ref{sec:initkeys} from page \pageref{sec:initkeys}.
+\begin{dispExample*}{sbs,lefthand ratio=0.5}
+\newtcblisting{mybox}{%
+ colback=red!5!white,
+ colframe=red!75!black}
+
+\begin{mybox}
+This is my \LaTeX\ box.
+\end{mybox}
+\end{dispExample*}
+
+\begin{dispExample*}{sbs,lefthand ratio=0.5}
+\newtcblisting{mybox}[1]{%
+ colback=red!5!white,
+ colframe=red!75!black,
+ fonttitle=\bfseries,
+ title=#1}
+
+\begin{mybox}{Listing Box}
+This is my \LaTeX\ box.
+\end{mybox}
+\end{dispExample*}
+
+\begin{dispExample*}{sbs,lefthand ratio=0.5}
+\newtcblisting{mybox}[2][]{%
+ colback=red!5!white,
+ colframe=red!75!black,
+ fonttitle=\bfseries,
+ title=#2,#1}
+
+\begin{mybox}[listing only]
+ {Listing Box}
+This is my \LaTeX\ box.
+\end{mybox}
+\bigskip
+
+\begin{mybox}[listing side text]
+ {Listing Box}
+This is my
+\LaTeX\ box.
+\end{mybox}
+\end{dispExample*}
+
+\clearpage
+\inputpreamblelisting{C}
+
+\begin{dispExample*}{sbs,lefthand ratio=0.5}
+\begin{mycbox}{Listing Box}
+This is my \LaTeX\ box.
+\end{mycbox}
+\end{dispExample*}
+\end{docCommand}
+
+
+%\enlargethispage*{1cm}
+\begin{docCommand}{renewtcblisting}{\oarg{init options}\marg{name}\oarg{number}\oarg{default}\marg{options}}
+ Operates like \refCom{newtcblisting}, but based on |\renewenvironment| instead of |\newenvironment|.
+ An existing environment is redefined.
+\end{docCommand}
+
+
+\clearpage
+\begin{docCommand}{newtcbinputlisting}{\oarg{init options}\brackets{\texttt{\textbackslash}\rmfamily\meta{name}}\oarg{number}\oarg{default}\marg{options}}
+ Creates a new macro \texttt{\textbackslash}\meta{name} based on \refCom{tcbinputlisting}.
+ Basically, |\newtcbinputlisting| operates like |\newcommand|.
+ The new macro \texttt{\textbackslash}\meta{name} optionally takes \meta{number} arguments, where
+ \meta{default} is the default value for the optional first argument.
+ The \meta{options} are given to the underlying |tcbinputlisting|.
+ The \meta{init options} allow setting up automatic numbering,
+ see Section \ref{sec:initkeys} from page \pageref{sec:initkeys}.
+
+\begin{dispExample}
+\newtcbinputlisting[use counter from=mycbox]{\mylisting}[2][]{%
+ listing file={#2},
+ title=Listing (\thetcbcounter) of \texttt{#2},
+ colback=red!5!white,colframe=red!75!black,fonttitle=\bfseries,
+ listing only,breakable,#1}
+
+\mylisting[before upper=\textit{This is the included file content:}]
+ {\jobname.tcbtemp}
+\end{dispExample}
+
+\begin{dispExample}
+\newtcbinputlisting[use counter from=mycbox]{\mylisting}[2][]{%
+ listing engine=minted,minted language=latex,minted style=colorful,
+ listing file={#2},
+ title=Listing (\thetcbcounter) of \texttt{#2},
+ colback=red!5!white,colframe=red!75!black,fonttitle=\bfseries,
+ listing only,breakable,#1}
+
+\mylisting[before upper=\textit{This is the included file content:}]
+ {\jobname.tcbtemp}
+\end{dispExample}
+\end{docCommand}
+
+
+\begin{docCommand}{renewtcbinputlisting}{\oarg{init options}\brackets{\texttt{\textbackslash}\rmfamily\meta{name}}\oarg{number}\oarg{default}\marg{options}}
+ Operates like \refCom{newtcbinputlisting}, but based on |\renewcommand| instead of |\newcommand|.
+ An existing macro is redefined.
+\end{docCommand}
+
+
+\clearpage
+\subsection{Option Keys of the \mylib{listings} Library}\label{sec:speclistingkeys}
+
+\begin{docTcbKey}{listing options}{=\meta{key list}}{no default, initially |style=tcblatex|}
+ Sets the options from the package |listings| \cite{hoffmann:2018a}
+ which are used during typesetting of the listing.
+ For \LaTeX\ listings, there is a predefined |listings| style named |tcblatex|
+ which can be used.
+\begin{dispExample}
+\begin{tcblisting}{colback=red!5!white,colframe=red!25,left=6mm,
+listing options={style=tcblatex,numbers=left,numberstyle=\tiny\color{red!75!black}}}
+This is a \LaTeX\ example which displays the text as source code
+and in compiled form. Additionally, we use line numbers here.
+\end{tcblisting}
+\end{dispExample}
+\end{docTcbKey}
+
+
+\begin{docTcbKey}{no listing options}{}{no value, initially unset}
+ Abbreviation for |listing options={}|.
+ This removes all options for the |listings| package.
+ This includes the |tcblisting| standard style |tcblatex| and the encoding presets.
+ Use this option, if you want to set the |listings| options outside of |tcblisting|, e.\,g.\ globally in
+ the preamble.
+\begin{dispExample}
+\begin{tcblisting}{no listing options}
+All \textit{listings} options removed.
+\end{tcblisting}
+\end{dispExample}
+\end{docTcbKey}
+
+
+\begin{docTcbKey}{listing style}{=\meta{style}}{no default, initially |tcblatex|}
+ Abbreviation for |listing options={style=...}|. This key sets a \meta{style}
+ for the |listings| package, see \cite{hoffmann:2018a}.
+ For \LaTeX, there is a predefined style named |tcblatex|.
+\begin{dispExample}
+\begin{tcblisting}{colback=red!5!white,colframe=red!75!black,
+listing style=tcblatex}
+Here, we use the predefined style.
+\end{tcblisting}
+\end{dispExample}
+\end{docTcbKey}
+
+\clearpage
+\begin{docTcbKey}{listing inputencoding}{=\meta{encoding}}{no default, initially \texttt{\cs inputencodingname}}
+ Sets the input encoding value for the predefined listing style |tcblatex|
+ and |tcbdocumentation| from the library \mylib{documentation}.
+ The initial value is derived from the package |inputenc| if used.
+\end{docTcbKey}
+
+\begin{docTcbKey}{listing remove caption}{\colOpt{=true\textbar false}}{default |true|, initially |true|}
+If set to |true|, some part of the caption building code of the |listings| package
+is silenced to prevent some unwanted interaction with the |hyperref| package resulting
+in additional vertical space.
+If set to |false|, the |listings| package code is kept unchanged.
+Note that listings outside \refEnv{tcblisting} and
+\refCom{tcbinputlisting} are always processed normally.
+Typically, a user is not expected to use this key at all.
+\end{docTcbKey}
+
+\begin{docTcbKey}{every listing line}{=\meta{text}}{no default, initially unset/empty}
+Inserts some \meta{text} to the begin of every line of a listing.
+Note that this a hack of the |listings| package code. This may become unusable
+or superfluous in the future.
+\begin{dispExample}
+\newtcblisting{commandshell}{colback=black,colupper=white,colframe=yellow!75!black,
+ listing only,listing options={style=tcblatex,language=sh},
+ every listing line={\textcolor{red}{\small\ttfamily\bfseries root \$> }}}
+
+\begin{commandshell}
+ls -al
+cd /usr/lib
+\end{commandshell}
+\end{dispExample}
+\end{docTcbKey}
+
+
+\begin{docTcbKey}{every listing line*}{=\meta{text}}{no default, initially unset/empty}
+Identical to \refKey{/tcb/every listing line} plus additional enlargement
+of \refKey{/tcb/rightupper} by the width of \meta{text}. Therefore, this
+option has to be used after the geometry settings are done.
+This option is intended to be used in conjunction with \refKey{/tcb/hbox}.
+
+\begin{dispExample}
+\newtcblisting{commandshell}{colback=black,colupper=white,colframe=yellow!75!black,
+ listing only,listing options={style=tcblatex,language=sh},hbox,
+ every listing line*={\textcolor{red}{\small\ttfamily\bfseries root \$> }}}
+
+\begin{commandshell}
+ls -al
+cd /usr/lib
+\end{commandshell}
+\end{dispExample}
+\end{docTcbKey}
+
+See further options in \Vref{sec:commonlistingkeys}.
+
+\begin{marker}
+For an combined example of using |\lstinline| inside a |tcolorbox|, see
+\refCom{DeclareTotalTCBox}.
+\end{marker}
+
+\clearpage
+\subsection{Option Keys of the \mylib{listingsutf8} Library}
+\begin{marker}
+The \mylib{listingsutf8} library is not needed (and troublesome) when using Xe\LaTeX\ or Lua\LaTeX.
+\end{marker}
+
+The \mylib{listingsutf8} library is an extension of the
+\mylib{listings} library, so
+all options from \Vref{sec:speclistingkeys} are applicable.
+
+\begin{docTcbKey}{listing utf8}{=\meta{one-byte-encoding}}{style, no default, initially |latin1|}
+ Abbreviation for using \refKey{/tcb/listing inputencoding}
+ together with UTF-8 support from the package |listingsutf8| \cite{oberdiek:2016b}.
+ This option is available only for the library variant \mylib{listingsutf8}.
+ The \meta{one-byte-encoding} is one of
+ the applicable encodings from \cite{oberdiek:2016b}, e.\,g.\ |latin1|
+ which is the default.\par
+ Be aware that this means restriction to this specific \meta{one-byte-encoding}:
+ e.\,g.\ |latin1| comprises umlauts and other accented characters, but not
+ the Euro sign. If you want to use the |listings| package \emph{and} \flqq real\frqq\
+ UTF-8 source code, then do \emph{not} use \mylib{listingsutf8} but \mylib{listings}
+ with
+ \refKey{/tcb/listing inputencoding}|=utf8|
+ \emph{and} with specific manual hacks for specific UTF-8-encoded characters.
+
+\end{docTcbKey}
+
+See further options in \Vref{sec:commonlistingkeys}.
+
+\clearpage
+\subsection{Option Keys of the \mylib{minted} Library}
+
+\begin{docTcbKey}{minted language}{=\meta{programming language}}{no default, initially |latex|}
+Sets a \meta{programming language} known to |Pygments| \cite{pygments:web}.
+\begin{dispExample}
+\begin{tcblisting}{listing engine=minted,minted style=trac,
+ minted language=java,
+ colback=red!5!white,colframe=red!75!black,listing only}
+ public class HelloWorld {
+ // A 'Hello World' in Java
+ public static void main(String[] args) {
+ System.out.println("Hello World!");
+ }
+ }
+\end{tcblisting}
+\end{dispExample}
+\end{docTcbKey}
+
+
+\begin{docTcbKey}[][doc updated={2017-07-05}]{minted options}{=\meta{key list}}{no default, initially
+ |tabsize=2,fontsize=\textbackslash small,|\linebreak|breaklines,autogobble|}
+ Sets the options from the package |minted| \cite{poore:minted}
+ which are used during typesetting of the listing.
+\begin{dispExample}
+% \tcbuselibrary{skins}
+\newtcblisting{myjava}{listing engine=minted,
+ minted style=colorful,
+ minted language=java,
+ minted options={fontsize=\small,breaklines,autogobble,linenos,numbersep=3mm},
+ colback=blue!5!white,colframe=blue!75!black,listing only,
+ left=5mm,enhanced,
+ overlay={\begin{tcbclipinterior}\fill[red!20!blue!20!white] (frame.south west)
+ rectangle ([xshift=5mm]frame.north west);\end{tcbclipinterior}}}
+
+\begin{myjava}
+ public class HelloWorld {
+ // A 'Hello World' in Java
+ public static void main(String[] args) {
+ System.out.println("Hello World!");
+ }
+ }
+\end{myjava}
+\end{dispExample}
+\end{docTcbKey}
+
+\clearpage
+\begin{docTcbKey}{minted style}{=\meta{style}}{no default, initially unset}
+Sets a \meta{style} known to |Pygments| \cite{pygments:web}. This is
+independent from \refKey{/tcb/minted options}. Note that styles are always
+applied globally; all following examples will be set in the given \meta{style}
+until a new style is set. Also note that
+setting |\usemintedstyle|\marg{style} only once per document is more economic, if
+all styles in a document are the same.
+For examples of different styles, see
+\refKey{/tcb/minted language} and \refKey{/tcb/minted options}.
+\end{docTcbKey}
+
+See further options in \Vref{sec:commonlistingkeys}.
+
+
+\clearpage
+\subsection{Common Option Keys of all Libraries}\label{sec:commonlistingkeys}
+For the \meta{options} in \refEnv{tcblisting} respectively \refCom{tcbinputlisting}
+the following |pgf| keys can be applied. The key tree path |/tcb/| is not to
+be used inside these macros.
+
+\begin{docTcbKey}{listing engine}{=\meta{engine}}{no default}
+ Sets the \meta{engine} which typesets the listings. Feasible values are
+ \begin{itemize}
+ \item\docValue{listings}, if library \mylib{listings} or
+ \mylib{listingsutf8} is loaded.
+ \item\docValue{minted}, if library \mylib{minted} is loaded.
+ \end{itemize}
+\end{docTcbKey}
+
+\begin{docTcbKey}{listing file}{=\meta{file name}}{no default, initially \cs{jobname.listing}}
+ Sets the \meta{file name} of the file which is used to save listings.
+\end{docTcbKey}
+
+
+\begin{docTcbKey}{listing and text}{}{no value, initially set}
+ Typesets the environment content as listing in the upper part and
+ as compiled text in the lower part.
+\begin{dispExample}
+\begin{tcblisting}{colback=red!5!white,colframe=red!75!black,listing and text}
+This is a \LaTeX\ example.
+\end{tcblisting}
+\end{dispExample}
+\end{docTcbKey}
+
+
+\begin{docTcbKey}{text and listing}{}{no value}
+ Typesets the environment content as compiled text in the upper part and
+ as listing in the lower part.
+\begin{dispExample}
+\begin{tcblisting}{colback=red!5!white,colframe=red!75!black,text and listing}
+This is a \LaTeX\ example.
+\end{tcblisting}
+\end{dispExample}
+\end{docTcbKey}
+
+
+\begin{docTcbKey}{listing only}{}{no value}
+ Typesets the environment content as listing.
+\begin{dispExample}
+\begin{tcblisting}{colback=red!5!white,colframe=red!75!black,listing only}
+This is a \LaTeX\ example.
+\end{tcblisting}
+\end{dispExample}
+\end{docTcbKey}
+
+
+\clearpage
+\begin{docTcbKey}{text only}{}{no value}
+ Typesets the environment content as compiled text.
+\begin{dispExample}
+\begin{tcblisting}{colback=red!5!white,colframe=red!75!black,text only}
+This is a \LaTeX\ example.
+\end{tcblisting}
+\end{dispExample}
+\end{docTcbKey}
+
+
+
+\begin{docTcbKey}{comment}{=\meta{text}}{no default, initially empty}
+ Records a comment with \meta{text} as content. The comment is displayed
+ e.\,g.\ in conjunction with \refKey{/tcb/listing and comment}
+ and \refKey{/tcb/comment and listing}.
+\begin{dispExample}
+\begin{tcblisting}{comment={This comment is really only a comment},
+ colback=red!5!white,colframe=red!75!black}
+This is a \textbf{tcolorbox}.
+\end{tcblisting}
+\end{dispExample}
+\end{docTcbKey}
+
+
+\begin{docTcbKey}[][doc new=2014-11-17]{comment only}{}{no value}
+ Typesets the environment content with the comment text.
+\begin{dispExample}
+\begin{tcblisting}{comment only,
+ comment={This is a comment.},
+ colback=red!5!white,colframe=red!75!black}
+This is a \textbf{tcolorbox}.
+\end{tcblisting}
+\end{dispExample}
+\end{docTcbKey}
+
+
+
+\begin{docTcbKey}{image comment}{=\marg{options}\marg{filename}}{style, no default, initially unset}
+ Uses an image denoted by \meta{filename} as \textit{comment} for the listing.
+ The image is included by the standard |\includegraphics| macro with
+ given \meta{options}.
+\begin{dispExample}
+\begin{tcblisting}{colback=red!5!white,colframe=red!75!black,listing side comment,
+ image comment={width=2.5cm}{example-image-a.pdf},center lower}
+This is a \LaTeX\ example.
+\end{tcblisting}
+\end{dispExample}
+\end{docTcbKey}
+
+
+\clearpage
+\begin{docTcbKey}[][doc new=2014-11-14]{tcbimage comment}{=\meta{filename}}{style, no default, initially unset}
+ Uses an image denoted by \meta{filename} as \textit{comment} for the listing.
+ The image is included by the \refCom{tcbincludegraphics} macro.
+ The inclusion can be customized by \refKey{/tcb/comment style}.
+ \begin{marker}
+ The library \mylib{skins} is needed to apply this option.
+ \end{marker}
+ \medskip
+\begin{dispExample}
+% \tcbuselibrary{skins}
+\begin{tcblisting}{colback=red!5!white,colframe=red!75!black,listing side comment,
+ righthand width=3cm,lower separated=false,
+ tcbimage comment={example-image-a.pdf},
+ comment style={size=fbox,colframe=blue,colback=blue!50,sharp corners,
+ drop fuzzy shadow}}
+This is a \LaTeX\ example.
+\end{tcblisting}
+\end{dispExample}
+\end{docTcbKey}
+
+%\enlargethispage*{1cm}
+
+\begin{docTcbKey}[][doc new=2014-11-14]{pdf comment}{\colOpt{=\meta{filename}}}{style, default listing file, initially unset}
+ Uses a PDF file denoted by \meta{filename} as \textit{comment} for the listing.
+ The image is included by \refCom{tcbincludepdf} inside a \refEnv{tcbraster}.
+ The inclusion can be customized by \refKey{/tcb/comment style}.
+ \begin{marker}
+ The libraries \mylib{skins} and \mylib{raster} are needed to apply this option.
+ \end{marker}
+ \medskip
+\begin{dispExample}
+% \tcbuselibrary{skins,raster}
+\begin{tcblisting}{colback=red!5!white,colframe=red!75!black,listing and comment,
+ righthand width=3cm,lower separated=false,middle=1mm,
+ pdf comment={tcolorbox-example.pdf},
+ comment style={raster columns=3,graphics pages={1,2,3},
+ colframe=blue,drop fuzzy shadow}}
+This is a \LaTeX\ example.
+\end{tcblisting}
+\end{dispExample}
+\end{docTcbKey}
+
+\clearpage
+
+
+\begin{docTcbKey}[][doc new=2014-11-14]{pdf extension}{=\meta{extension}}{no default, initially |pdf|}
+ Sets the PDF file name extension for \refKey{/tcb/pdf comment} to \meta{extension}.
+ Note that \meta{extension} always overwrites any actual extension given
+ inside \refKey{/tcb/pdf comment}.
+\end{docTcbKey}
+
+
+\begin{docTcbKey}[][doc new=2014-11-14]{comment style}{=\meta{options}}{no default, initially empty}
+ Sets the \meta{options} for \refKey{/tcb/tcbimage comment} and \refKey{/tcb/pdf comment}.
+ These are |tcolorbox| options to customize the colored box drawn around the
+ image(s), also image options encapsulated by \refKey{/tcb/graphics options},
+ and \refEnv{tcbraster} options for \refKey{/tcb/pdf comment}.
+\end{docTcbKey}
+
+
+\begin{docTcbKey}{listing and comment}{}{no value}
+ Typesets the environment content as listing in the upper part and
+ a given comment in the lower part.
+\begin{dispExample}
+\begin{tcblisting}{colback=red!5!white,colframe=red!75!black,listing and comment,
+ comment={This is my comment. It may contain line breaks.\par
+ It can even use the environment content
+ \flqq\ignorespaces\tcbuselistingtext\unskip\frqq}}
+This is a \LaTeX\ example.
+\end{tcblisting}
+\end{dispExample}
+\end{docTcbKey}
+
+\enlargethispage*{10mm}
+\begin{docTcbKey}{comment and listing}{}{no value}
+ Typesets a given comment in the upper part and
+ the environment content as listing in the lower part.
+\begin{dispExample}
+\begin{tcblisting}{colback=red!5!white,colframe=red!75!black,comment and listing,
+comment={This is my comment.}}
+This is a \LaTeX\ example.
+\end{tcblisting}
+\end{dispExample}
+\end{docTcbKey}
+
+
+\clearpage
+\begin{docTcbKey}{listing side text}{}{style, no value}
+Typesets the environment content side by side as listing in the left (upper)
+part and as compiled text in the right (lower) part.
+This is a shortcut for setting \refKey{/tcb/listing and text} and \refKey{/tcb/sidebyside}.
+\begin{dispExample}
+\begin{tcblisting}{colback=red!5!white,colframe=red!75!black,listing side text}
+This is a \LaTeX\ example.
+\end{tcblisting}
+\end{dispExample}
+\begin{marker}
+Note that |sidebyside=false| has to be added, if the setting of
+\refKey{/tcb/listing side text} is to be annihilated.
+\end{marker}
+\end{docTcbKey}
+
+
+\begin{docTcbKey}{text side listing}{}{style, no value}
+Typesets the environment content side by side as compiled text in the left (upper)
+part and as listing in the right (lower) part.
+This is a shortcut for setting \refKey{/tcb/text and listing} and \refKey{/tcb/sidebyside}.
+\begin{dispExample}
+\begin{tcblisting}{colback=red!5!white,colframe=red!75!black,text side listing}
+This is a \LaTeX\ example.
+\end{tcblisting}
+\end{dispExample}
+\end{docTcbKey}
+
+
+\begin{docTcbKey}{listing outside text}{}{no value}
+Typesets the environment content side by side as listing in a |tcolorbox|
+and as compiled text outside the box in the right part of the page.
+Nevertheless, the outside text is treated as \emph{lower} part of the
+|tcolorbox| and can be formatted with all lower part options.
+The space partitioning is done with the side by side options from
+\Fullref{sec:sidebyside}.
+\begin{dispExample}
+\begin{tcblisting}{colback=red!5!white,colframe=red!75!black,listing outside text}
+This is a \LaTeX\ example.
+\end{tcblisting}
+\end{dispExample}
+\end{docTcbKey}
+
+
+\begin{docTcbKey}{text outside listing}{}{no value}
+Typesets the environment content side by side as listing in a |tcolorbox|
+and as compiled text outside the box in the left part of the page.
+Nevertheless, the outside text is treated as \emph{lower} part of the
+|tcolorbox| and can be formatted with all lower part options.
+The space partitioning is done with the side by side options from
+\Fullref{sec:sidebyside}.
+\begin{dispExample}
+\begin{tcblisting}{colback=red!5!white,colframe=red!75!black,text outside listing}
+This is a \LaTeX\ example.
+\end{tcblisting}
+\end{dispExample}
+\end{docTcbKey}
+
+
+\clearpage
+\begin{docTcbKey}{listing side comment}{}{style, no value}
+Typesets the environment content side by side as listing in the left (upper)
+part and a given comment in the right (lower) part.
+This is a shortcut for setting \refKey{/tcb/listing and comment} and \refKey{/tcb/sidebyside}.
+\begin{dispExample}
+\begin{tcblisting}{colback=red!5!white,colframe=red!75!black,listing side comment,
+ righthand width=1.5cm,image comment={width=1.5cm}{example-image-a.pdf}}
+This is a \LaTeX\ example.
+\end{tcblisting}
+\end{dispExample}
+\end{docTcbKey}
+
+
+\begin{docTcbKey}{comment side listing}{}{style, no value}
+Typesets the environment content side by side with a given comment in the left (upper)
+part and as listing in the right (lower) part.
+This is a shortcut for setting \refKey{/tcb/comment and listing} and \refKey{/tcb/sidebyside}.
+\begin{dispExample}
+\begin{tcblisting}{colback=red!5!white,colframe=red!75!black,comment side listing,
+ lefthand width=1.5cm,image comment={width=1.5cm}{example-image-a.pdf}}
+This is a \LaTeX\ example.
+\end{tcblisting}
+\end{dispExample}
+\end{docTcbKey}
+
+
+\enlargethispage*{2cm}
+\begin{docTcbKey}{listing outside comment}{}{no value}
+Typesets the environment content side by side as listing in a |tcolorbox|
+and a given comment outside the box in the right part of the page.
+Nevertheless, the outside text is treated as \emph{lower} part of the
+|tcolorbox| and can be formatted with all lower part options.
+The space partitioning is done with the side by side options from
+\Fullref{sec:sidebyside}.
+\begin{dispExample}
+\begin{tcblisting}{colback=red!5!white,colframe=red!75!black,listing outside comment,
+ righthand width=1.5cm,image comment={width=1.5cm}{example-image-a.pdf}}
+This is a \LaTeX\ example.
+\end{tcblisting}
+\end{dispExample}
+\end{docTcbKey}
+
+
+\begin{docTcbKey}{comment outside listing}{}{no value}
+Typesets the environment content side by side as listing in a |tcolorbox|
+and a given comment outside the box in the left part of the page.
+Nevertheless, the outside text is treated as \emph{lower} part of the
+|tcolorbox| and can be formatted with all lower part options.
+The space partitioning is done with the side by side options from
+\Fullref{sec:sidebyside}.
+\begin{dispExample}
+\begin{tcblisting}{colback=red!5!white,colframe=red!75!black,comment outside listing,
+ lefthand width=1.5cm,image comment={width=1.5cm}{example-image-a.pdf}}
+This is a \LaTeX\ example.
+\end{tcblisting}
+\end{dispExample}
+\end{docTcbKey}
+
+
+\clearpage
+\begin{docTcbKey}{listing above text}{}{no value}
+ Typesets the environment content as listing in a |tcolorbox|
+ and as compiled text outside and below the box.
+ The outside text is treated as \emph{lower} part of the
+ |tcolorbox| and can be formatted with all lower part options.
+ The distance between box and text is controlled by \refKey{/tcb/middle}.
+\begin{dispExample}
+\begin{tcblisting}{colback=red!5!white,colframe=red!75!black,listing above text}
+This is a \LaTeX\ example.
+\end{tcblisting}
+\end{dispExample}
+\end{docTcbKey}
+
+
+\begin{docTcbKey}[][doc new=2014-11-07]{listing above* text}{}{no value}
+ Widely equal to \refKey{/tcb/listing above text}, but the outside text is
+ not formatted with the lower part options.
+ Also, it is not put into a minipage and it may span several pages.
+ The distance between box and text is controlled by \refKey{/tcb/after}.
+\end{docTcbKey}
+
+
+\begin{docTcbKey}{text above listing}{}{no value}
+ Typesets the environment content as listing in a |tcolorbox|
+ and as compiled text outside and above the box.
+ The outside text is treated as \emph{lower} part of the
+ |tcolorbox| and can be formatted with all lower part options.
+ The distance between box and text is controlled by \refKey{/tcb/middle}.
+\begin{dispExample}
+\begin{tcblisting}{colback=red!5!white,colframe=red!75!black,text above listing}
+This is a \LaTeX\ example.
+\end{tcblisting}
+\end{dispExample}
+\end{docTcbKey}
+
+
+\begin{docTcbKey}[][doc new=2014-11-07]{text above* listing}{}{no value}
+ Widely equal to \refKey{/tcb/text above listing}, but the outside text is
+ not formatted with the lower part options.
+ Also, it is not put into a minipage and it may span several pages.
+ The distance between box and text is controlled by \refKey{/tcb/before}.
+\end{docTcbKey}
+
+
+\clearpage
+\begin{docTcbKey}{listing above comment}{}{no value}
+ Typesets the environment content as listing in a |tcolorbox|
+ and a given comment outside and below the box.
+ The outside text is treated as \emph{lower} part of the
+ |tcolorbox| and can be formatted with all lower part options.
+ The distance between box and comment is controlled by \refKey{/tcb/middle}.
+\begin{dispExample}
+\begin{tcblisting}{colback=red!5!white,colframe=red!75!black,listing above comment,
+ center lower,image comment={width=3cm}{example-image-a.pdf}}
+This is a \LaTeX\ example.
+\end{tcblisting}
+\end{dispExample}
+\end{docTcbKey}
+
+
+\begin{docTcbKey}[][doc new=2014-11-07]{listing above* comment}{}{no value}
+ Widely equal to \refKey{/tcb/listing above comment}, but the outside comment is
+ not formatted with the lower part options.
+ Also, it is not put into a minipage and it may span several pages.
+ The distance between box and comment is controlled by \refKey{/tcb/after}.
+\end{docTcbKey}
+
+
+\begin{docTcbKey}{comment above listing}{}{no value}
+ Typesets the environment content as listing in a |tcolorbox|
+ and a given comment outside and above the box.
+ The outside text is treated as \emph{lower} part of the
+ |tcolorbox| and can be formatted with all lower part options.
+ The distance between box and comment is controlled by \refKey{/tcb/middle}.
+\begin{dispExample}
+\begin{tcblisting}{colback=red!5!white,colframe=red!75!black,comment above listing,
+ center lower,image comment={width=3cm}{example-image-a.pdf}}
+This is a \LaTeX\ example.
+\end{tcblisting}
+\end{dispExample}
+\end{docTcbKey}
+
+
+\begin{docTcbKey}[][doc new=2014-11-07]{comment above* listing}{}{no value}
+ Widely equal to \refKey{/tcb/comment above listing}, but the outside comment is
+ not formatted with the lower part options.
+ Also, it is not put into a minipage and it may span several pages.
+ The distance between box and comment is controlled by \refKey{/tcb/before}.
+\end{docTcbKey}
+
+
+\clearpage
+\subsection{Option Keys for Processing and Full Document Examples}\label{sec:proclistingkeys}
+A complete \LaTeX\ document including |\documentclass|, |\begin{document}|
+and |\end{document}| cannot be processed directly by |tcolorbox|.
+It always has to be compiled separately. There are two methods supported
+by the package to process and display such a full document example:
+\begin{itemize}
+\item Prepare and compile the example document independent from your main
+ document. The source file and the resulting PDF file can be included
+ into the main document afterwards. This is the most economic way since
+ the example document can be left untouched after the example is complete.
+\item The other possibility is to compile the example on the fly while
+ the main document is compiled. This way has some charm, because the
+ example can be edited inside the main document. But be aware that the
+ compilation of the example is issued on every run of the main document.
+ Also, there are fewer degrees of freedom how the example is compiled.
+\end{itemize}
+
+For both methods, the resulting example PDF file can be included
+as a \refKey{/tcb/pdf comment}.
+
+The following example shows how to apply the first method.
+There already is a file |tcolorbox-example.tex| and a PDF file
+|tcolorbox-example.pdf|. Both of them are input partly by the following:
+
+\begin{dispListing}
+% \tcbuselibrary{breakable,skins,raster}
+\tcbinputlisting{
+ enhanced jigsaw,breakable,pad at break*=2mm,height fixed for=first and middle,
+ lower separated=false,
+ leftlower=0pt,rightlower=0pt,middle=0pt,
+ colframe=red!50!black,colback=yellow!10!white,
+ listing and comment,
+ listing file={tcolorbox-example},
+ listing options=
+ {style=tcblatex,texcsstyle=*\color{red!70!black},firstline=20,lastline=85},
+ after upper={\par\bigskip\texttt{\ldots}\par},
+ pdf comment,
+ comment style={drop lifted shadow,graphics pages={1,...,4}},
+}
+\end{dispListing}
+{\tcbusetemp}
+
+
+\clearpage
+
+
+\begin{docTcbKey}[][doc new=2014-11-14]{no process}{}{no default}
+ Removes all processing commands if set before.
+\end{docTcbKey}
+
+\begin{docTcbKey}[][doc new=2014-11-14]{process code}{=\meta{code}}{no default, initially empty}
+ Adds \meta{code} which is executed during \refCom{tcbinputlisting}
+ and \refEnv{tcblisting}. At the time of executing the given \meta{code},
+ the listing is already written to \refKey{/tcb/listing file}, but
+ the colored box is not constructed yet.
+ Its intended use is to process the listing somehow before displaying.
+ The processing result can be used inside a \refKey{/tcb/comment}.
+ Several \refKey{/tcb/process code} options can be given which are
+ processed in the given order.
+ Typically, \meta{code} is added by using the following styles
+ \refKey{/tcb/run system command}, \refKey{/tcb/run pdflatex}, etc.
+\end{docTcbKey}
+
+\begin{marker}
+To use the further options, the compiler has to be called with the
+|-shell-escape| permission to authorize potentially dangerous system calls.
+Be warned that this is a security risk. Anyway, it's more economic to
+compile examples independent from the main document and to include them as
+shown in the previous pages.
+\end{marker}
+
+\begin{docTcbKey}[][doc new=2014-11-14]{run system command}{=\meta{system command}}{style, no default, initially unset}
+Runs a \meta{system command}, if the document is compiled with the
+|-shell-escape| permission.
+The current listing file can be accessed as |\filename@area\filename@base\filename@ext|.
+This \meta{system command} is added to \refKey{/tcb/process code}.
+\end{docTcbKey}
+
+
+\begin{docTcbKey}[][doc new and updated={2014-11-14}{2016-05-27}]{compilable listing}{}{style, no default}
+ Sets \refKey{/tcb/listing file} to |\jobname|\texttt{-listing-}\meta{counter}.
+ \begin{marker}
+ The default \refKey{/tcb/listing file} setting cannot be used to compile
+ a listing, since the base name equals the |\jobname| and the included PDF
+ files should be unique.
+ Therefore, to use \refKey{/tcb/run pdflatex} etc., the \refKey{/tcb/listing file}
+ has to be set to a unique value.
+ One may use \refKey{/tcb/compilable listing} for this purpose.
+ \end{marker}
+\end{docTcbKey}
+
+
+\begin{docTcbKey}[][doc new=2014-11-14]{run pdflatex}{\colOpt{=\meta{arguments}}}{style, no default, initially unset}
+Issues a |pdflatex| compilation of the listing with the given \meta{arguments}.
+\begin{itemize}
+\item The main document has to be compiled with the |-shell-escape| permission.
+\item The \refKey{/tcb/listing file} has to be unique for the listing.
+\item If the listing has to be compiled twice, add |run pdflatex| two times to
+ the option list.
+\end{itemize}
+
+\begin{dispListing*}{breakable,enhanced,pad at break*=2mm,before upper=,after skip=3mm}
+\begin{tcblisting}{enhanced jigsaw,lower separated=false,
+ leftlower=0pt,rightlower=0pt,
+ colframe=red!50!black,colback=yellow!10!white,
+ listing options={style=tcblatex,texcsstyle=*\color{red!70!black}},
+ listing and comment,
+ pdf comment,freeze pdf,
+ compilable listing,
+ run pdflatex
+}
+\documentclass{beamer}
+\usetheme{Warsaw}
+\begin{document}
+\begin{frame}{Beamer example}
+ \begin{block}{Hello World}
+ \begin{itemize}[<+->]
+ \item One
+ \item Two
+ \end{itemize}
+ \end{block}
+
+ \begin{alertblock}{Integral}
+ \begin{equation}
+ \visible<3->{\int\limits_1^x \frac{1}{t}~dt}
+ \visible<4->{ = \ln(x).}
+ \end{equation}
+ \end{alertblock}
+\end{frame}
+\end{document}
+\end{tcblisting}
+\end{dispListing*}
+{\tcbusetemp}
+\end{docTcbKey}
+
+
+\clearpage
+\begin{docTcbKey}[][doc new=2014-11-14]{run xelatex}{\colOpt{=\meta{arguments}}}{style, no default, initially unset}
+Issues a |xelatex| compilation of the listing with the given \meta{arguments}.
+\end{docTcbKey}
+
+\begin{docTcbKey}[][doc new=2014-11-14]{run lualatex}{\colOpt{=\meta{arguments}}}{style, no default, initially unset}
+Issues a |lualatex| compilation of the listing with the given \meta{arguments}.
+\end{docTcbKey}
+
+\begin{docTcbKey}[][doc new=2014-11-14]{run makeindex}{\colOpt{=\meta{arguments}}}{style, no default, initially unset}
+Issues a |makeindex| compilation of the listing with the given \meta{arguments}.
+\end{docTcbKey}
+
+\begin{docTcbKey}[][doc new=2014-11-14]{run bibtex}{\colOpt{=\meta{arguments}}}{style, no default, initially unset}
+Issues a |bibtex| compilation of the listing with the given \meta{arguments}.
+\end{docTcbKey}
+
+\begin{docTcbKey}[][doc new=2014-11-14]{run biber}{\colOpt{=\meta{arguments}}}{style, no default, initially unset}
+Issues a |biber| compilation of the listing with the given \meta{arguments}.
+\end{docTcbKey}
+
+\begin{docTcbKey}[][doc new=2014-11-14]{run arara}{\colOpt{=\meta{arguments}}}{style, no default, initially unset}
+Issues an |arara| compilation of the listing with the given \meta{arguments}.
+\end{docTcbKey}
+
+\begin{docTcbKey}[][doc new=2014-11-14]{run latex}{\colOpt{=\meta{arguments}}}{style, no default, initially unset}
+Issues a |latex| compilation of the listing with the given \meta{arguments}.
+\end{docTcbKey}
+
+\begin{docTcbKey}[][doc new=2014-11-14]{run dvips}{\colOpt{=\meta{arguments}}}{style, no default, initially unset}
+Issues a |dvips| compilation of the listing with the given \meta{arguments}.
+\end{docTcbKey}
+
+\enlargethispage*{1cm}
+\begin{docTcbKey}[][doc new=2014-11-14]{run ps2pdf}{\colOpt{=\meta{arguments}}}{style, no default, initially unset}
+Issues a |ps2pdf| compilation of the listing with the given \meta{arguments}.
+\end{docTcbKey}
+
+\begin{dispListing*}{breakable,enhanced,pad at break*=2mm,before upper=,after skip=3mm}
+\begin{tcblisting}{enhanced jigsaw,
+ title={PSTricks with pdflatex},fonttitle=\bfseries,
+ colframe=red!50!black,colback=yellow!10!white,
+ listing options={style=tcblatex,texcsstyle=*\color{red!70!black}},
+ lower separated=false,middle=0pt,
+ listing side comment,righthand width=4cm,
+ compilable listing,
+ run latex,run dvips,run ps2pdf,
+ pdf comment,freeze pdf,
+ comment style={raster columns=1,
+ graphics options={viewport=0.5in 7.7in 3.5in 10.5in,clip}},
+}
+\documentclass{article}
+\usepackage{pstricks,multido}
+\begin{document}
+\psset{unit=3}%
+\multido{\nHue=0.01+0.01}{100}{%
+\definecolor{MyColor}{hsb}{\nHue,1,1}%
+\pscircle[linewidth=0.01,linecolor=MyColor]{\nHue}}
+\end{document}
+\end{tcblisting}
+\end{dispListing*}
+{\tcbusetemp}
+
+\clearpage
+
+\begin{marker}
+ For most applications, you will like to add \refKey{/tcb/freeze pdf} as option,
+ since the included |pdf| file is only refreshed, if the source for this file
+ has changed.
+\end{marker}
+
+\begin{docTcbKey}[][doc new=2016-07-14]{freeze file}{=\meta{file}}{no default, initially unset}
+ Observes some \meta{file}, usually the final file produced by \refKey{/tcb/process code},
+ \refKey{/tcb/run system command}, \refKey{/tcb/run pdflatex}, etc.
+ If the MD5 checksum of the current \refKey{/tcb/listing file} is unchanged
+ and \meta{file} exists, the processing is skipped and
+ the \meta{file} is kept (frozen).
+ Typically, the style \refKey{/tcb/freeze pdf} can be used for
+ convenience.
+\end{docTcbKey}
+
+\begin{docTcbKey}[][doc new=2016-07-14]{freeze none}{}{no default, initially set}
+ Freeze no file and always execute the given process commands.
+\end{docTcbKey}
+
+\begin{docTcbKey}[][doc new=2016-07-14]{freeze extension}{=\meta{text}}{style, no default}
+ Calls \refKey{/tcb/freeze file} with the current \refKey{/tcb/listing file}
+ stripped with its extension plus \meta{text} as new extension.
+\begin{dispListing}
+ ...
+ listing file=myfile.tex,
+ freeze extension=-modified.pdf, % -> myfile-modified.pdf is observed
+ ...
+\end{dispListing}
+\end{docTcbKey}
+
+\begin{docTcbKey}[][doc new=2016-07-14]{freeze pdf}{}{no value}
+ Calls \refKey{/tcb/freeze file} with the current \refKey{/tcb/listing file}
+ stripped with its extension plus |.pdf| as new extension.
+\end{docTcbKey}
+
+\begin{docTcbKey}[][doc new=2016-07-14]{freeze png}{}{no value}
+ Calls \refKey{/tcb/freeze file} with the current \refKey{/tcb/listing file}
+ stripped with its extension plus |.png| as new extension.
+ See the examples for \refKey{/tcb/run pdflatex} and \refKey{/tcb/run ps2pdf}.
+\end{docTcbKey}
+
+\begin{docTcbKey}[][doc new=2016-07-14]{freeze jpg}{}{no value}
+ Calls \refKey{/tcb/freeze file} with the current \refKey{/tcb/listing file}
+ stripped with its extension plus |.jpg| as new extension.
+\end{docTcbKey}
+
+
+
+
+\clearpage
+\subsection{Creation of \LaTeX\ Tutorials}\label{sec:latextutorial}
+The following source code gives a guideline for the creation of \LaTeX\ tutorials.
+In the next section, a framework for \LaTeX\ exercises is described.
+All examples shall be numbered optionally.
+
+Firstly, some additional |tcb| keys are defined for the appearance.
+For the examples, three environments |texexp|, |texexptitled|,
+and |texexptitledspec| are defined with automatic numbering.
+
+\begin{itemize}
+\item |texexp| is used for untitled examles,
+\item |texexptitled| is used for titled examles,
+\item |texexptitledspec| is used for titled examles with special treatment.
+\end{itemize}
+
+\inputpreamblelisting{D}
+
+\begin{dispExample}
+\begin{tcblisting}{texexp}
+This is a \LaTeX\ example which displays the text as source code
+and in compiled form.
+\end{tcblisting}
+\end{dispExample}
+
+
+\begin{dispExample}
+\begin{texexptitled}{First example with a title line}{firstExample}
+Here, we use Example \ref{firstExample} with a title line.
+\end{texexptitled}
+\end{dispExample}
+
+
+\begin{dispExample}
+\begin{texexp}{}
+This is a \LaTeX\ example which displays the text as source code
+and in compiled form.
+\end{texexp}
+\end{dispExample}
+
+
+\begin{dispExample}
+\begin{texexp}{text and listing}
+This is a \LaTeX\ example which displays the text as source code
+and in compiled form.
+\end{texexp}
+\end{dispExample}
+
+
+\begin{dispExample}
+\begin{texexp}{listing only}
+This is a \LaTeX\ example which displays the text as source code only.
+\end{texexp}
+\end{dispExample}
+
+
+\begin{dispExample}
+\begin{texexp}{text only}
+This is a \LaTeX\ example which displays the text in compiled form only.
+\end{texexp}
+\end{dispExample}
+
+
+\begin{dispExample}
+\begin{texexptitled}{An Example with a Heading}{heading1}
+This is a \LaTeX\ example with a numbered heading line
+which can be referred to.
+\end{texexptitled}
+Here, we see Example \ref{heading1}.
+\end{dispExample}
+
+
+\begin{dispExample}
+\begin{texexptitled}[listing only]{Another Example with a Heading}{heading2}
+The keys can be used in combination. Here, an example with a heading line
+and source code only is given.
+\end{texexptitled}
+Here, we see Example \ref{heading2}.
+\end{dispExample}
+
+
+\begin{dispListing}
+\begin{texexptitled}[float]{A floating Example with a Heading}{heading3}
+This is another \LaTeX\ example with numbered heading line.
+But now, the box is a floating object.
+\end{texexptitled}
+\end{dispListing}
+\tcbusetemp
+
+\begin{dispExample}
+The floating box of the last example is seen as Example \ref{heading3}
+on page \pageref{heading3}.
+\end{dispExample}
+
+
+\begin{dispExample}
+\begin{texexptitledspec}{Special application}{texexpbox1}
+\begin{lstlisting}[style=tcblatex]
+Some \LaTeX\ source code.
+\end{lstlisting}
+\tcblower
+For special cases, the environment |texexptitledspec| with style
+|example| can be used directly. As one can see, the upper and the lower
+part of the box can be used uncoupled also.
+\end{texexptitledspec}
+\end{dispExample}
+
+
+The following series of examples demonstrate the application of
+\refEnv{tcolorbox} options for diversification.
+
+\begin{dispExample}
+\begin{texexptitled}{How to use options (1):\par The basic example}{options1}
+\begin{tikzpicture}
+\path[fill=yellow!50!white] (0,0) circle (11mm);
+\path[fill=white] (0,0) circle (9mm);
+\foreach \w/\c in {90/red,210/green,330/blue}
+{\path[shading=ball,ball color=\c] (\w:1cm) circle (7mm);}
+\end{tikzpicture}
+\end{texexptitled}
+\end{dispExample}
+
+
+\begin{dispExample}
+\begin{texexptitled}[center lower,enhanced,segmentation hidden,middle=0mm]
+ {How to use options (2):\par The text output is centered and the
+ segmentation line has vanished.}{options2}
+\begin{tikzpicture}
+\path[fill=yellow!50!white] (0,0) circle (11mm);
+\path[fill=white] (0,0) circle (9mm);
+\foreach \w/\c in {90/red,210/green,330/blue}
+{\path[shading=ball,ball color=\c] (\w:1cm) circle (7mm);}
+\end{tikzpicture}
+\end{texexptitled}
+\end{dispExample}
+
+\begin{dispExample}
+\begin{texexptitled}[tikz lower,bicolor,colbacklower=white]
+ {How to use options (3):\par Here, the |tikzpicture| is totally hidden.
+ The |bicolor| skin highlights the output.}{options3}
+\path[fill=yellow!50!white] (0,0) circle (11mm);
+\path[fill=white] (0,0) circle (9mm);
+\foreach \w/\c in {90/red,210/green,330/blue}
+{\path[shading=ball,ball color=\c] (\w:1cm) circle (7mm);}
+\end{texexptitled}
+\end{dispExample}
+
+\begin{dispExample}
+\begin{texexptitled}[center lower,listing side text,righthand width=3.5cm,
+ bicolor,colbacklower=white]
+ {How to use options (4):\par The |bicolor| skin also works with side
+ by side mode}{options4}
+\begin{tikzpicture}
+\path[fill=yellow!50!white] (0,0) circle (11mm);
+\path[fill=white] (0,0) circle (9mm);
+\foreach \w/\c in {90/red,210/green,330/blue}
+{\path[shading=ball,ball color=\c]
+ (\w:1cm) circle (7mm);}
+\end{tikzpicture}
+\end{texexptitled}
+\end{dispExample}
+
+
+\begin{dispExample}
+\begin{texexptitled}[center lower,listing outside text,righthand width=3.5cm]
+ {How to use options (5):\par Putting our picture outside is just
+ a matter of one word.}{options5}
+\begin{tikzpicture}
+\path[fill=yellow!50!white] (0,0) circle (11mm);
+\path[fill=white] (0,0) circle (9mm);
+\foreach \w/\c in {90/red,210/green,330/blue}
+{\path[shading=ball,ball color=\c]
+ (\w:1cm) circle (7mm);}
+\end{tikzpicture}
+\end{texexptitled}
+\end{dispExample}
+
+
+\begin{dispExample}
+\begin{texexptitled}[center lower,text above listing]
+ {How to use options (6):\par The picture may also be put above
+ the listing box.}{options6}
+\begin{tikzpicture}
+\path[fill=yellow!50!white] (0,0) circle (11mm);
+\path[fill=white] (0,0) circle (9mm);
+\foreach \w/\c in {90/red,210/green,330/blue}
+{\path[shading=ball,ball color=\c]
+ (\w:1cm) circle (7mm);}
+\end{tikzpicture}
+\end{texexptitled}
+\end{dispExample}
+
+
+\begin{dispExample}
+\begin{texexptitled}[beamer,center lower,text outside listing,lefthand width=3.5cm]
+ {How to use options (7):\par Our style is easily transformed into
+ a beamerish one.}{options7}
+\begin{tikzpicture}
+\path[fill=yellow!50!white] (0,0) circle (11mm);
+\path[fill=white] (0,0) circle (9mm);
+\foreach \w/\c in {90/red,210/green,330/blue}
+{\path[shading=ball,ball color=\c]
+ (\w:1cm) circle (7mm);}
+\end{tikzpicture}
+\end{texexptitled}
+\end{dispExample}
+
+
+\clearpage
+\subsection{Creation of \LaTeX\ Exercises}\label{listing:exercises}
+In the following, a guideline is given for the creation of \LaTeX\ exercises
+with solutions. These solutions are saved to disk for application at a place of
+choice.
+Therefore, all used exercises are logged to a file |\jobname.records| for automatic
+processing. The solution contents themselves are saved to a subdirectory named
+|solutions|. Also see \Vref{sec:recording}.
+
+\begin{itemize}
+\item Before the first exercise is given,
+ \refCom{tcbstartrecording} has to be called to start recording.
+\item The solution is given as content of a \refEnv{tcboutputlisting}
+ environment. Note, that you can use this content also inside the
+ exercise with \refCom{tcbuselistingtext} in compiled form.
+\item After the last exercise is given (and before using the solutions),
+ \refCom{tcbstoprecording} has to be called to stop recording.
+\item The solutions are loaded by \refCom{tcbinputrecords}.
+\end{itemize}
+
+Inside the exercise text, there may be text parts which are needed as
+\LaTeX\ source code and as compiled text as well. These parts can be
+saved by \refEnv{tcbwritetemp} and used in compiled form by \refCom{tcbusetemp}
+or as source code by \refCom{tcbusetemplisting}.
+
+At first, we generate some a common style for the exercises and the
+solutions. Further, since exercises and solutions should
+be numbered, we force to use a label \meta{marker}.
+Automatically, the label |exe:|\meta{marker} is used to mark the exercise
+and the label |sol:|\meta{marker} is used to mark the solution.
+
+\begin{dispListing}
+\tcbset{texercisestyle/.style={arc=0.5mm, colframe=blue!25!yellow!90!white,
+ colback=blue!25!yellow!5!white, coltitle=blue!25!yellow!40!black,
+ fonttitle=\small\sffamily\bfseries, fontupper=\small, fontlower=\small,
+ listing options={style=tcblatex,texcsstyle=*\color{red!40!black}},
+}}
+\end{dispListing}
+\tcbusetemp
+
+With these preparations, the kernel environment |texercise| for our
+exercises is created quickly:
+
+\inputpreamblelisting{E}
+
+\clearpage
+The following examples demonstrate the application.
+
+\begin{dispListing}
+\tcbstartrecording
+\end{dispListing}
+\tcbusetemp
+
+
+\begin{dispExample}
+\begin{texercise}{tabular_example}
+\textit{Create the following table:}\par\smallskip%
+\begin{tcboutputlisting}
+\begin{tabular}{|p{3cm}|p{3cm}|p{3cm}|p{3cm}|}\hline
+\multicolumn{4}{|c|}{\bfseries\itshape Das alte Italien}\\\hline
+\multicolumn{2}{|c|}{\bfseries Antike} &
+\multicolumn{2}{c|}{\bfseries Mittelalter}\\\hline
+\multicolumn{1}{|c|}{\itshape Republik}&
+\multicolumn{1}{c|}{\itshape Kaiserreich}&
+\multicolumn{1}{c|}{\itshape Franken}&
+\multicolumn{1}{c|}{\itshape Teilstaaten}\\\hline
+In den Zeiten der r\"{o}mischen Republik standen dem Staat jeweils zwei
+Konsuln vor, deren Machtbefugnisse identisch waren. &
+Das r\"{o}mische Kaiserreich wurde von einem Alleinherrscher, dem Kaiser,
+regiert.
+& In der V\"{o}lkerwanderungszeit \"{u}bernahmen die Goten und sp\"{a}ter die
+Franken die Vorherrschaft.
+& Im sp\"{a}teren Mittelalter regierten F\"{u}rsten einen Fleckenteppich
+von Einzelstaaten.\\\hline
+\end{tabular}
+\end{tcboutputlisting}
+\tcbuselistingtext%
+\end{texercise}
+\end{dispExample}
+
+
+\begin{dispExample}
+\begin{texercise}{macro_oneparam}
+\begin{tcboutputlisting}
+\newcommand{\headingline}[1]{%
+ \begin{center}\Large\bfseries #1\end{center}}
+\end{tcboutputlisting}
+\tcbuselistingtext%
+
+Create a new macro \verb+\headingline+ which produces the
+following output:\par\smallskip
+\begin{tcbwritetemp}
+\headingline{Very important heading}
+\end{tcbwritetemp}
+\tcbusetemplisting\tcbusetemp%
+\end{texercise}
+\end{dispExample}
+
+
+
+\begin{dispExample}
+\begin{texercise}{macro_twoparam}
+\begin{tcboutputlisting}
+\newcommand{\minitable}[2]{%
+ \begin{center}\begin{tabular}{p{10cm}}\hline%
+ \multicolumn{1}{c}{\bfseries#1}\\\hline%
+ #2\\\hline%
+ \end{tabular}\end{center}}
+\end{tcboutputlisting}
+\tcbuselistingtext%
+Create a new macro \verb+\minitable+ which produces the
+following output:\par\smallskip
+\begin{tcbwritetemp}
+\minitable{My heading}{In this tiny tabular, there is only a heading
+ and some text below which has a width of ten centimeters.}
+\end{tcbwritetemp}
+\tcbusetemplisting\par\smallskip\tcbusetemp%
+\end{texercise}
+\end{dispExample}
+
+
+\begin{dispExample}
+\begin{texercise}{macro_threeparam}
+\begin{tcboutputlisting}
+\newcommand{\synop}[3]{%
+ \begin{tabular}{@{}p{(\linewidth-\tabcolsep*2-\arrayrulewidth)/2}|%
+ p{(\linewidth-\tabcolsep*2-\arrayrulewidth)/2}@{}}\hline
+ \multicolumn{2}{c}{\bfseries #1}\\\hline
+ \multicolumn{1}{c|}{\itshape English}&
+ \multicolumn{1}{c}{\itshape German}\\\hline
+ #2 & #3
+ \end{tabular}}
+\end{tcboutputlisting}
+\tcbuselistingtext%
+Create a new macro \verb+\synop+ which typesets a synoptic text according
+to the following example. Base your macro on a tabular which takes the
+total line width.\par\smallskip
+\begin{tcbwritetemp}
+\synop{Neil Armstrong}%
+{That's one small step for a man, one giant leap for mankind.}%
+{Das ist ein kleiner Schritt f\"{u}r einen Mann,
+ ein riesiger Sprung f\"{u}r die Menschheit.}
+\end{tcbwritetemp}
+\tcbusetemplisting\par\smallskip\tcbusetemp%
+\end{texercise}
+\end{dispExample}
+%\closeoutsol
+
+\begin{dispListing}
+\tcbstoprecording
+\end{dispListing}
+\tcbusetemp
+
+\bigskip
+
+Now, we give a list of all exercises with:
+
+\begin{dispListing}
+\tcblistof[\subsection]{exam}{List of Exercises%
+ \label{listofexercises}}
+\end{dispListing}
+\tcbusetemp
+
+\clearpage
+\subsection{Solutions for the given \LaTeX\ Exercises}
+
+For all solutions, a macro |\processsol| was written to the file |\jobname.records|.
+Now, we need a definition for this macro to use the solutions.
+
+\begin{dispListing}
+% \usepackage{hyperref} % for phantomlabel
+\newtcbinputlisting{\processsol}[2]{%
+ texercisestyle,
+ listing only,
+ listing file={#1},
+ phantomlabel={sol:#2},%
+ title={Solution for Exercise \ref{exe:#2} on page \pageref{exe:#2}},
+}
+\end{dispListing}
+\tcbusetemp
+
+The loading of all solutions is done by:
+
+\begin{dispListing}
+\tcbinputrecords
+\end{dispListing}
+
+With this, we get:
+
+\tcbusetemp
+
+
+