diff options
author | Karl Berry <karl@freefriends.org> | 2013-04-09 16:31:58 +0000 |
---|---|---|
committer | Karl Berry <karl@freefriends.org> | 2013-04-09 16:31:58 +0000 |
commit | d6730e96b1acc94ef3a26f9079e57099be823dff (patch) | |
tree | 2bc872d6369d464c590c9a071de5274beca219c7 /Master/texmf-dist/doc/latex/tcolorbox/tcolorbox.doc.listings.tex | |
parent | 92897266fb13289d7ef1da636a65bd9c444864f3 (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.tex | 553 |
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 + + |