diff options
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 | 269 |
1 files changed, 206 insertions, 63 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 index 544afba872b..fbbdd3971d6 100644 --- a/Master/texmf-dist/doc/latex/tcolorbox/tcolorbox.doc.listings.tex +++ b/Master/texmf-dist/doc/latex/tcolorbox/tcolorbox.doc.listings.tex @@ -1,26 +1,86 @@ % !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: +\section{Libraries + \mylib{listings}, + \mylib{listingsutf8}, and + \mylib{minted}}\label{sec: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, +you should take \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{heinz:2007a} 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{heinz:2007a}. -Alternatively, if your sources are encoded with UTF-8, you can use the support from +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}} +To extend |listings| for UTF-8 encoded sources, you can use the support from the package |listingsutf8| \cite{oberdiek:2011a} by loading the library -variant 'listingsutf8'. +variant \mylib{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} +This also loads the library \mylib{listings} +and the packages |listings| \cite{heinz:2007a} and |listingsutf8| \cite{oberdiek:2011a}. +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{rudolph:2011a} 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{rudolph:2011a}. + +\begin{marker} +The |minted| package uses the external tool |Pygments| \cite{pygments:2013} +to apply syntax highlighting. It has to be installed and set up, before the +library can be used, see \cite{rudolph:2011a} and \cite{pygments:2013}. +The |tcolorbox| library \mylib{minted} does not work, if the package +|minted| \cite{rudolph:2011a} 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{Macros of the Library} +\subsection{Common Macros of the Libraries} \begin{docEnvironment}{tcblisting}{\marg{options}} Creates a colored box based on a \refEnv{tcolorbox}. @@ -35,8 +95,11 @@ This is a \LaTeX\ example which displays the text as source code and in compiled form. \end{tcblisting} \end{dispExample} + \clearpage + \begin{dispExample} +% \usetikzlibrary{listings} /or/ \usetikzlibrary{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}}} @@ -49,6 +112,24 @@ and in compiled form. \end{tcblisting} \end{dispExample} +\enlargethispage*{10mm} + +\begin{dispExample} +% \usetikzlibrary{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 !!) % \usetikzlibrary{skins} @@ -62,7 +143,7 @@ and in compiled form. \end{docEnvironment} -%\clearpage +\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 @@ -75,7 +156,6 @@ This \textbf{text} is written to a standardized file for later usage. \end{docEnvironment} -\clearpage \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, @@ -194,49 +274,21 @@ This is my \LaTeX\ box. {\jobname.tcbtemp} \end{dispExample} -% \begin{dispExample*}{sbs,lefthand ratio=0.6} -% \newtcbinputlisting{\mybox}{colback=red!5!white, - % colframe=red!75!black} -% -% \mybox{This is my own box.} -% \end{dispExample*} -% -% \begin{dispExample*}{sbs,lefthand ratio=0.6} -% \newtcbinputlisting{\mybox}[1]{colback=red!5!white, - % colframe=red!75!black,fonttitle=\bfseries, - % title=#1} -% -% \mybox{Hello there}{This is my own box.} -% \end{dispExample*} -% -% \begin{dispExample*}{sbs,lefthand ratio=0.6} -% \newtcbinputlisting{\mybox}[2][]{colback=red!5!white, - % colframe=red!75!black,fonttitle=\bfseries, - % title=#2,#1} -% -% \mybox[colback=yellow]{Hello there}% - % {This is my own box.} -% \end{dispExample*} -% -% \inputpreamblelisting{B} -% -% \begin{dispExample*}{sbs,lefthand ratio=0.6} -% \pbbox[colback=yellow]{Hello there}% - % {This is my own box.} -% \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} - \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} +\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{heinz:2007a} @@ -252,6 +304,7 @@ and in compiled form. Additionally, we use line numbers here. \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. @@ -265,7 +318,6 @@ All \textit{listings} options removed. \end{dispExample} \end{docTcbKey} -\clearpage \begin{docTcbKey}{listing style}{=\meta{style}}{no default, initially |tcblatex|} Abbreviation for |listing options={style=...}|. This key sets a \meta{style} @@ -279,24 +331,122 @@ Here, we use the predefined style. \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 'documentation'. + 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{=\meta{boolean value}}}{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} + +See further options in \Vref{sec:commonlistingkeys}. + +\subsection{Option Keys of the \mylib{listingsutf8} Library} +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:2011a}. - This option is available only for the library variant 'listingsutf8'. + 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:2011a}, e.\,g.\ |latin1|. \end{docTcbKey} +See further options in \Vref{sec:commonlistingkeys}. + + +\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:2013}. +\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} + +\clearpage +\begin{docTcbKey}{minted options}{=\meta{key list}}{no default, initially |tabsize=2,fontsize=\textbackslash small|} + Sets the options from the package |minted| \cite{rudolph:2011a} + 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,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} + + +\begin{docTcbKey}{minted style}{=\meta{style}}{no default, initially unset} +Sets a \meta{style} known to |Pygments| \cite{pygments:2013}. 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 |listings|, if library \mylib{listings} or + \mylib{listingsutf8} is loaded. + \item |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. @@ -327,6 +477,8 @@ This is a \LaTeX\ example. \end{dispExample} \end{docTcbKey} + +\clearpage \begin{docTcbKey}{text only}{}{no value} Typesets the environment content as compiled text. \begin{dispExample} @@ -337,7 +489,7 @@ This is a \LaTeX\ example. \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} @@ -364,7 +516,7 @@ This is a \LaTeX\ example. \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. @@ -430,16 +582,6 @@ This is a \LaTeX\ example. \end{docTcbKey} -\clearpage -\begin{docTcbKey}{listing remove caption}{\colOpt{=\meta{boolean value}}}{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} \clearpage \subsection{Creation of \LaTeX\ Tutorials}\label{sec:latextutorial} @@ -833,3 +975,4 @@ With this, we get: \tcbusetemp + |