summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/doc/latex/tcolorbox/tcolorbox.doc.listings.tex
diff options
context:
space:
mode:
authorKarl Berry <karl@freefriends.org>2013-04-09 16:31:58 +0000
committerKarl Berry <karl@freefriends.org>2013-04-09 16:31:58 +0000
commitd6730e96b1acc94ef3a26f9079e57099be823dff (patch)
tree2bc872d6369d464c590c9a071de5274beca219c7 /Master/texmf-dist/doc/latex/tcolorbox/tcolorbox.doc.listings.tex
parent92897266fb13289d7ef1da636a65bd9c444864f3 (diff)
tcolorbox (9apr13)
git-svn-id: svn://tug.org/texlive/trunk@29788 c570f23f-e606-0410-a88d-b1316a301751
Diffstat (limited to 'Master/texmf-dist/doc/latex/tcolorbox/tcolorbox.doc.listings.tex')
-rw-r--r--Master/texmf-dist/doc/latex/tcolorbox/tcolorbox.doc.listings.tex553
1 files changed, 553 insertions, 0 deletions
diff --git a/Master/texmf-dist/doc/latex/tcolorbox/tcolorbox.doc.listings.tex b/Master/texmf-dist/doc/latex/tcolorbox/tcolorbox.doc.listings.tex
new file mode 100644
index 00000000000..21fd295e39d
--- /dev/null
+++ b/Master/texmf-dist/doc/latex/tcolorbox/tcolorbox.doc.listings.tex
@@ -0,0 +1,553 @@
+% !TeX root = tcolorbox.tex
+% include file of tcolorbox.tex (manual of the LaTeX package tcolorbox)
+\clearpage
+\section{Library 'listings' / 'listingsutf8'}\label{sec:listings}
+The library is loaded by a package option or inside the preamble by:
+\begin{dispListing}
+\tcbuselibrary{listings}
+\end{dispListing}
+This also loads the package |listings| \cite{heinz:2007a}.
+
+Alternatively, if your sources are encoded with UTF-8, you can use the support from
+the package |listingsutf8| \cite{oberdiek:2011a} by loading the library
+variant 'listingsutf8'.
+\begin{dispListing}
+\tcbuselibrary{listingsutf8}
+\tcbset{listing utf8=latin1}% optional; 'latin1' is the default.
+\end{dispListing}
+This also loads the packages |listings| \cite{heinz:2007a}
+and |listingsutf8| \cite{oberdiek:2011a}.
+
+
+
+\subsection{Macros of the Library}
+
+\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}
+{\tcbset{breakable}\begin{dispExample}
+\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}
+}
+\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{dispExample}
+\begin{tcboutputlisting}
+This \textbf{text} is written to a standardized file for later usage.
+\end{tcboutputlisting}
+\end{dispExample}
+\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}
+
+
+\begin{docCommand}{tcbusetemplisting}{}
+ Typesets text as listing from a temporary file which was written by
+ \refEnv{tcbwritetemp}.
+\end{docCommand}
+
+
+\clearpage
+\subsection{Option Keys of the Library}
+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 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 options}{=\meta{key list}}{no default, initially |style=tcblatex|}
+ Sets the options from the package |listings| \cite{heinz:2007a}
+ 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}{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{heinz:2007a}.
+ 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}
+
+
+\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 'documentation'.
+ The initial value is derived from the package |inputenc| if used.
+\end{docTcbKey}
+
+
+\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:2011a}.
+ This option is available only for the library variant 'listingsutf8'.
+ The \meta{one-byte-encoding} is one of
+ the applicable encodings from \cite{oberdiek:2011a}, e.\,g.\ |latin1|.
+\end{docTcbKey}
+
+
+\clearpage
+\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}
+
+\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}
+
+
+\clearpage
+\begin{docTcbKey}{comment}{=\meta{text}}{no default, initially empty}
+ Records a comment with \meta{text} as content. The comment is displayed
+ only 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}{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}
+
+
+
+\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
+\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 and automatic
+numbering.
+
+\begin{dispListing}
+%\newcounter{texexp} % preamble
+
+\tcbset{
+ texexp/.style={colframe=red!50!yellow!50!black, colback=red!50!yellow!5!white,
+ coltitle=red!50!yellow!3!white,
+ fonttitle=\small\sffamily\bfseries, fontupper=\small, fontlower=\small},
+ example/.code 2 args={\refstepcounter{texexp}\label{#2}%
+ \pgfkeysalso{texexp,title={Example \thetexexp: #1}}},
+}
+\end{dispListing}
+\tcbusetemp
+
+
+\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{tcblisting}{example={Direct application of \texttt{example}}{firstExample}}
+Here, we use Example \ref{firstExample} with a title line.
+\end{tcblisting}
+\end{dispExample}
+
+For the next examples, two environments
+|texexp| and |texexptitled|
+are defined for abbreviation.
+
+\begin{dispListing}
+\newenvironment{texexp}[1]{\tcblisting{texexp,#1}}{\endtcblisting}
+
+\newenvironment{texexptitled}[3][]{\tcblisting{example={#2}{#3},#1}}{\endtcblisting}
+\end{dispListing}
+\tcbusetemp
+
+For special cases, |tcolorbox| with the key
+|texexp| can be used instead of these two environments.
+
+Now, we have a flexible box for \LaTeX\ examples which is demonstrated in
+the following.
+
+\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{tcolorbox}[example={Direct application of the style |texexp|}{texexpbox1}]
+\begin{lstlisting}[style=tcblatex]
+Some \LaTeX\ source code.
+\end{lstlisting}
+\tcblower
+For special cases, the environment |tcolorbox| 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{tcolorbox}
+\end{dispExample}
+
+
+\subsection{Creation of \LaTeX\ 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.sol| for automatic
+processing. The solution contents themselves are saved to a subdirectory named
+|solutions|.
+
+\begin{dispListing}
+%\newcounter{texercise} % preamble
+
+\newwrite\solout
+\def\openoutsol{\immediate\openout\solout\jobname.sol}
+\def\solfile#1{solutions/texercise#1.tex}
+\def\writesol#1{\immediate\write\solout{\noexpand\processsol{\thetexercise}{#1}}}%
+\def\closeoutsol{\immediate\closeout\solout}
+\def\inputsol{\IfFileExists{\jobname.sol}{\input{\jobname.sol}}{}}
+\end{dispListing}
+\tcbusetemp
+
+\begin{itemize}
+\item Before the first exercise is given,
+ |\openoutsol| has to be called to start logging.
+\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),
+ |\closeoutsol| has to be called to stop logging.
+\item The solutions are loaded by |\inputsol|.
+\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 new keys. Since exercises and solutions should
+be numbered, we force to use a label \meta{marker} while using the style |texercise|.
+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},
+texercise/.code={\refstepcounter{texercise}\label{exe:#1}\writesol{#1}%
+ \pgfkeysalso{texercisestyle,
+ listing file={\solfile\thetexercise},
+ title={Exercise \arabic{texercise}\hfill\mdseries Solution on page \pageref{sol:#1}}
+ }}
+}
+\end{dispListing}
+\tcbusetemp
+
+With these preparations, the kernel environment |texercise| for our
+exercises is created quickly:
+
+\begin{dispListing}
+\newenvironment{texercise}[2][]{%
+ \tcolorbox[texercise=#2,savedelimiter=texercise,#1]}%
+ {\endtcolorbox}
+\end{dispListing}
+\tcbusetemp
+
+The following examples demonstrate the application.
+\openoutsol
+
+
+\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
+\subsection{Solutions for the given \LaTeX\ Exercises}
+
+For all solutions, a macro |\processsol| was written to the file |\jobname.sol|.
+Now, we need a definition for this macro to use the solutions.
+
+\begin{dispListing}
+\newcommand{\processsol}[2]{%
+ \tcbinputlisting{texercisestyle,listing only,
+ title={Solution for Exercise \ref{exe:#2} on page \pageref{exe:#2}\label{sol:#2}},
+ listing file={\solfile#1}%
+ }}
+\end{dispListing}
+\tcbusetemp
+
+The loading of all solutions is done by:
+
+\begin{dispListing}
+\inputsol
+\end{dispListing}
+
+With this, we get:
+
+\tcbusetemp
+
+