summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/doc/latex/tcolorbox/tcolorbox.doc.listings.tex
diff options
context:
space:
mode:
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.tex269
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
+