% \iffalse meta-comment % % Copyright (C) 2013-2017 by Geoffrey M. Poore % Copyright (C) 2010-2011 by Konrad Rudolph % --------------------------------------------------------------------------- % This work may be distributed and/or modified under the % conditions of the LaTeX Project Public License, either version 1.3 % of this license or (at your option) any later version. % The latest version of this license is in % http://www.latex-project.org/lppl.txt % and version 1.3 or later is part of all distributions of LaTeX % version 2005/12/01 or later. % % Additionally, the project may be distributed under the terms of the 3-Clause % ("New") BSD license: http://opensource.org/licenses/BSD-3-Clause. % % This work has the LPPL maintenance status `maintained'. % % The Current Maintainer of this work is Geoffrey M. Poore. % % This work consists of the files minted.dtx and minted.ins % and the derived file minted.sty. % % % \fi % % \iffalse %<*driver> \ProvidesFile{minted.dtx} % %\NeedsTeXFormat{LaTeX2e} %\ProvidesPackage{minted} %<*package> [2017/07/19 v2.5 Yet another Pygments shim for LaTeX] % %<*driver> \documentclass{ltxdoc} \EnableCrossrefs \CodelineIndex %\DisableCrossrefs %\RecordChanges %\OnlyDescription \usepackage[utf8]{inputenc} \usepackage[T1]{fontenc} \usepackage{lmodern} \usepackage{dingbat} \usepackage{microtype} \usepackage[svgnames]{xcolor} \usepackage{textcomp} \usepackage[cache, langlinenos]{minted} % Need to set the style here so that it is defined and brought in here. % If the style is set later, then docstrip interferes with any comments in % the style definition so that they appear as literal text in the document. \setminted{style=default} \usepackage{environ} \usepackage{graphicx} \usepackage{multicol} \usepackage{hyperref} \makeatletter % Create a short verbatim pipe that handles quotation marks properly \begingroup \catcode`\|=\active \gdef\pipe@active@verbatim{% \begingroup \let\do\@makeother\dospecials \catcode`\|=\active \catcode`\`=\active \catcode`\'=\active \catcode`\<=\active \catcode`\>=\active \catcode`\-=\active \catcode`\,=\active \catcode`\ =\active \pipe@active@verbatim@i} \gdef\pipe@active@verbatim@i#1|{% \endgroup \begingroup \def\FV@SV@pipe@active@verbatim{% \FV@Gobble \expandafter\FV@ProcessLine\expandafter{#1}}% %\let\FV@BeginVBox\relax %\let\FV@EndVBox\relax %\def\FV@BProcessLine##1{\FancyVerbFormatLine{##1}}% \BUseVerbatim{pipe@active@verbatim}% \endgroup} \AtBeginDocument{\let|\pipe@active@verbatim} \endgroup \newcommand{\changestext}{} \NewEnviron{changelog}[2]{% \g@addto@macro\changestext{\item[#1] (#2) \begin{itemize}}% \expandafter\g@addto@macro\expandafter\changestext\expandafter{\BODY}% \g@addto@macro\changestext{\end{itemize}}% } \newcommand{\PrintChangelog}{% \addcontentsline{toc}{section}{Version History} \section*{Version History}% \label{sec:version-history} \begin{description}% \changestext \end{description}% } \def\MacroFont{% \fontencoding\encodingdefault% \fontfamily\ttdefault% \fontseries\mddefault% \fontshape\updefault% \small} \definecolor{minted@mint}{HTML}{0B610B} \definecolor{minted@samplebg}{HTML}{F0F0E0} \colorlet{minted@linkcolor}{minted@mint} % \def\PrintDescribeMacro#1{\strut \MacroFont\textcolor{minted@linkcolor}{\string #1\ }} \let\PrintDescribeEnv\PrintDescribeMacro \let\PrintMacroName\PrintDescribeMacro \let\PrintEnvName\PrintDescribeEnv \def\theCodelineNo{\textcolor{minted@linkcolor}{\sffamily\footnotesize\oldstylenums{\arabic{CodelineNo}}}} % \hypersetup{ pdftitle=The minted package: Highlighted source code in LaTeX, pdfauthor=Geoffrey M. Poore, pdfsubject={Minted LaTeX package manual}, colorlinks=true, allcolors=minted@linkcolor, } % % Shamelessly stolen from http://blog.karssen.org/2009/11/15/a-latex-example-environment/ \newenvironment{example} {\VerbatimEnvironment \begin{VerbatimOut}[gobble=3]{example.out}} {\end{VerbatimOut}% \vspace{1ex}% \setlength{\parindent}{0pt}% \fbox{\begin{minipage}{0.5\linewidth}% \inputminted[resetmargins]{latex}{example.out}% \end{minipage}% \hspace{0.05\linewidth}% \begin{minipage}{0.45\linewidth-2\fboxsep}% \input{example.out}% \end{minipage}% \vspace{1ex}}} \newenvironment{longexample} {\VerbatimEnvironment \begin{VerbatimOut}[gobble=3]{example.out}} {\end{VerbatimOut}% \vspace{1ex}% \setlength{\parindent}{0pt}% \fbox{\begin{minipage}{\linewidth-2\fboxsep}% \inputminted[resetmargins]{latex}{example.out}% ~\hrulefill~ \input{example.out}% \end{minipage}% \vspace{1ex}}} \def\minted@printopt#1(#2) (#3){% \vspace{0.1in}% \leavevmode% \marginpar{\raggedleft\texttt{\textcolor{minted@linkcolor}{\small #1}}\ }% \kern-\parindent\textsf{(#2)}\hfill(default: \texttt{#3})\\} \newenvironment{optionlist}% {% ~\par\vspace{-14pt}% \def\pipechar{|} \let\|\pipechar \newcommand*\mintednext{}% \renewcommand*\item[1][]{% \mintednext% \renewcommand*\mintednext{\par}% \minted@printopt##1% \ignorespaces}} {% \par} \edef\hashchar{\string#} \makeatother \newcommand{\hide}[1]{} \setlength{\parindent}{0pt} \addtolength{\parskip}{0.5\baselineskip} \begin{document} \DocInput{minted.dtx} \PrintIndex \end{document} % % \fi % % \CheckSum{2604} % % \CharacterTable % {Upper-case \A\B\C\D\E\F\G\H\I\J\K\L\M\N\O\P\Q\R\S\T\U\V\W\X\Y\Z % Lower-case \a\b\c\d\e\f\g\h\i\j\k\l\m\n\o\p\q\r\s\t\u\v\w\x\y\z % Digits \0\1\2\3\4\5\6\7\8\9 % Exclamation \! Double quote \" Hash (number) \# % Dollar \$ Percent \% Ampersand \& % Acute accent \' Left paren \( Right paren \) % Asterisk \* Plus \+ Comma \, % Minus \- Point \. Solidus \/ % Colon \: Semicolon \; Less than \< % Equals \= Greater than \> Question mark \? % Commercial at \@ Left bracket \[ Backslash \\ % Right bracket \] Circumflex \^ Underscore \_ % Grave accent \` Left brace \{ Vertical bar \| % Right brace \} Tilde \~} % % % % % \begin{changelog}{v2.5}{2017/07/19} % \item The default placement for the \texttt{listing} float is now \texttt{tbp} instead of \texttt{h}, to parallel \texttt{figure} and \texttt{table} and also avoid warnings caused by \texttt{h} (\#165). The documentation now contains information about changing default placement. The \texttt{float} package is no longer loaded when the \texttt{newfloat} package option is used. % \item Added support for \texttt{*nchars} options from \texttt{fvextra} v1.3 that allow setting \texttt{breaklines}-related indentation in terms of a number of characters, rather than as a fixed dimension. % \item Fixed incompatibility with \texttt{babel magyar} (\#158). % \item Added support for \texttt{beamer} overlays with \texttt{beameroverlays} option (\#155). % \item Comments in the Pygments \LaTeX\ style files no longer appear as literal text when \texttt{minted} is used in \texttt{.dtx} files (\#161). % \item \texttt{autogobble} now works with package option \texttt{kpsewhich} (\#151). Under Windows, the \texttt{kpsewhich} option no longer requires PowerShell. % \item Fixed a bug that prevented \texttt{finalizecache} from working with \texttt{outputdir} (\#149). % \item Fixed a bug with \texttt{firstline} and \texttt{lastline} that prevented them from working with the \texttt{minted} environment (\#145). % \item Added note on \texttt{breqn} conflicts to FAQ (\#163). % \end{changelog} % % % \begin{changelog}{v2.4.1}{2016/10/31} % \item Single quotation marks in \texttt{\string\jobname} are now replaced with underscores in \texttt{\string\minted@jobname} to prevent quoting errors (\#137). % \item The \texttt{autogobble} option now takes \texttt{firstline} and \texttt{lastline} into account (\#130). % \item Fixed \texttt{numberblanklines}, which had been lost in the transition to v2.0+ (\#135). % \end{changelog} % % % \begin{changelog}{v2.4}{2016/07/20} % \item Line breaking and all associated options are now completely delegated to \texttt{fvextra}. % \item Fixed a bug from v2.2 that could cause the first command or environment to vanish when \texttt{cache=false} (related to work on \texttt{\string\MintedPygmentize}). % \end{changelog} % % % \begin{changelog}{v2.3}{2016/07/14} % \item The \texttt{fvextra} package is now required. \texttt{fvextra} extends and patches \texttt{fancyvrb}, and includes improved versions of \texttt{fancyvrb} extensions that were formerly in \texttt{minted}. % \item As part of \texttt{fvextra}, the \texttt{upquote} package is always loaded. \texttt{fvextra} brings the new option \texttt{curlyquotes}, which allows curly single quotation marks instead of the literal backtick and typewriter single quotation mark produced by \texttt{upquote}. This allows the default \texttt{upquote} behavior to be disabled when desired. % \item Thanks to \texttt{fvextra}, the options \texttt{breakbefore}, \texttt{breakafter}, and \texttt{breakanywhere} are now compatible with non-ASCII characters under pdfTeX (\#123). % \item Thanks to \texttt{fvextra}, \texttt{obeytabs} no longer causes lines in multi-line comments or strings to vanish (\#88), and is now compatible with \texttt{breaklines} (\#99). \texttt{obeytabs} will now always give correct results with tabs used for indentation. However, tab stops are not guaranteed to be correct for tabs in the midst of text. % \item \texttt{fvextra} brings the new options \texttt{space}, \texttt{spacecolor}, \texttt{tab}, and \texttt{tabcolor} that allow these characters and their colors to be redefined (\#98). The tab may now be redefined to a flexible-width character such as \texttt{\string\rightarrowfill}. The visible tab will now always be black by default, instead of changing colors depending on whether it is part of indentation for a multiline string or comment. % \item \texttt{fvextra} brings the new options \texttt{highlightcolor} and \texttt{highlightlines}, which allow single lines or ranges of lines to be highlighted based on line number (\#124). % \item \texttt{fvextra} brings the new options \texttt{numberfirstline}, \texttt{stepnumberfromfirst}, and \texttt{stepnumberoffsetvalues} that provide better control over line numbering when \texttt{stepnumber} is not 1. % \item Fixed a bug from v2.2.2 that prevented \texttt{upquote} from working. % \end{changelog} % % % \begin{changelog}{v2.2.2}{2016/06/21} % \item Fixed a bug introduced in v2.2 that prevented setting the Pygments style in the preamble. Style definitions are now more compatible with using \texttt{\string\MintedPygmentize} to call a custom \texttt{pygmentize}. % \end{changelog} % % % \begin{changelog}{v2.2.1}{2016/06/15} % \item The \texttt{shellesc} package is loaded before \texttt{ifplatform} and other packages that might invoke \texttt{\string\write18} (\#112). % \item When caching is enabled, XeTeX uses the new \texttt{\string\mdfivesum} macro from TeX Live 2016 to hash cache content, rather than using \texttt{\string\ShellEscape} with Python to perform hashing. % \end{changelog} % % % \begin{changelog}{v2.2}{2016/06/08} % \item All uses of \texttt{\string\ShellEscape} (\texttt{\string\write18}) no longer wrap file names and paths with double quotes. This allows a cache directory to be specified relative to a user's home directory, for example, \texttt{\string~/minted\_cache}. \texttt{cachedir} and \texttt{outputdir} paths containing spaces will now require explicit quoting of the parts of the paths that contain spaces, since \texttt{minted} no longer supplies quoting. See the updated documentation for examples (\#89). % \item Added \texttt{breakbefore}, \texttt{breakbeforegroup}, \texttt{breakbeforesymbolpre}, and \texttt{breakbeforesymbolpost}. These parallel \texttt{breakafter*}. It is possible to use \texttt{breakbefore} and \texttt{breakafter} for the same character, so long as \texttt{breakbeforegroup} and \texttt{breakaftergroup} have the same setting (\#117). % \item Added package options \texttt{finalizecache} and \texttt{frozencache}. These allow the cache to be prepared for (\texttt{finalizecache}) and then used (\texttt{frozencache}) in an environment in which \texttt{-shell-escape}, Python, and/or Pygments are not available. Note that this only works if \texttt{minted} content does not need to be modified, and if no settings that depend on Pygments or Python need to be changed (\#113). % \item Style names containing hyphens and underscores (\texttt{paraiso-light}, \texttt{paraiso-dark}, \texttt{algol\_nu}) now work (\#111). % \item The \texttt{shellesc} package is now loaded, when available, for compatibility with LuaTeX 0.87+ (TeX Live 2016+, etc.). \texttt{\string\ShellEscape} is now used everywhere instead of \texttt{\string\immediate\string\write18}. If \texttt{shellesc} is not available, then a \texttt{\string\ShellEscape} macro is created. When \texttt{shellesc} is loaded, there is a check for versions before v0.01c to patch a bug in v0.01b (present in TeX Live 2015) (\#112). % \item The \texttt{bgcolor} option now uses the \texttt{snugshade*} environment from the \texttt{framed} package, so \texttt{bgcolor} is now compatible with page breaks. When \texttt{bgcolor} is in use, immediately preceding text will no longer push the \texttt{minted} environment into the margin, and there is now adequate spacing from surrounding text (\#121). % \item Added missing support for \texttt{fancyvrb}'s \texttt{labelposition} (\#102). % \item Improved fix for TikZ externalization, thanks to Patrick Vogt (\#73). % \item Fixed \texttt{breakautoindent}; it was disabled in version 2.1 due to a bug in \texttt{breakanywhere}. % \item Properly fixed handling of \texttt{\string\MintedPygmentize} (\#62). % \item Added note on incompatibility of \texttt{breaklines} and \texttt{obeytabs} options. Trying to use these together will now result in a package error (\#99). Added note on issues with \texttt{obeytabs} and multiline comments (\#88). Due to the various \texttt{obeytabs} issues, the docs now discourage using \texttt{obeytabs}. % \item Added note to FAQ on \texttt{fancybox} and \texttt{fancyvrb} conflict (\#87). % \item Added note to docs on the need for \texttt{\string\VerbatimEnvironment} in environment definitions based on \texttt{minted} environments. % \end{changelog} % % % \begin{changelog}{v2.1}{2015/09/09} % \item Changing the highlighting style now no longer involves re-highlighing code. Style may be changed with almost no overhead. % \item Improved control of automatic line breaks. New option \texttt{breakanywhere} allows line breaks anywhere when \texttt{breaklines=true}. The pre-break and post-break symbols for these types of breaks may be set with \texttt{breakanywheresymbolpre} and \texttt{breakanywheresymbolpost} (\#79). New option \texttt{breakafter} allows specifying characters after which line breaks are allowed. Breaks between adjacent, identical characters may be controlled with \texttt{breakaftergroup}. The pre-break and post-break symbols for these types of breaks may be set with \texttt{breakaftersymbolpre} and \texttt{breakaftersymbolpost}. % \item \texttt{breakbytoken} now only breaks lines between tokens that are separated by spaces, matching the documentation. The new option \texttt{breakbytokenanywhere} allows for breaking between tokens that are immediately adjacent. Fixed a bug in \texttt{\string\mintinline} that produced a following linebreak when \texttt{\string\mintinline} was the first thing in a paragraph and \texttt{breakbytoken} was true (\#77). % \item Fixed a bug in draft mode option handling for \texttt{\string\inputminted} (\#75). % \item Fixed a bug with \texttt{\string\MintedPygmentize} when a custom \texttt{pygmentize} was specified and there was no \texttt{pygmentize} on the default path (\#62). % \item Added note to docs on caching large numbers of code blocks under OS~X (\#78). % \item Added discussion of current limitations of \texttt{texcomments} (\#66) and \texttt{escapeinside} (\#70). % \item PGF/Ti\textit{k}Z externalization is automatically detected and supported (\#73). % \item The package is now compatible with \LaTeX\ files whose names contain spaces (\#85). % \end{changelog} % % % \begin{changelog}{v2.0}{2015/01/31} % \item Added the compatibility package \texttt{minted1}, which provides the \pkg{minted} 1.7 code. This may be loaded when 1.7 compatibility is required. This package works with other packages that \texttt{\string\RequirePackage\{minted\}}, so long as it is loaded first. % \item Moved all old \texttt{\string\changes} into \texttt{changelog}. % \end{changelog} % % % \begin{changelog}{Development releases for 2.0}{2014--January 2015} % \item Caching is now on by default. % \item Fixed a bug that prevented compiling under Windows when file names contained commas. % \item Added \texttt{breaksymbolleft}, \texttt{breaksymbolsepleft}, \texttt{breaksymbolindentleft}, \texttt{breaksymbolright}, \texttt{breaksymbolsepright}, and \texttt{breaksymbolindentright} options. \texttt{breaksymbol}, \texttt{breaksymbolsep}, and \texttt{breaksymbolindent} are now aliases for the correspondent \texttt{*left} options. % \item Added \texttt{kpsewhich} package option. This uses \texttt{kpsewhich} to locate the files that are to be highlighted. This provides compatibility with build tools like \texttt{texi2pdf} that function by modifying \texttt{TEXINPUTS} (\#25). % \item Fixed a bug that prevented \texttt{\string\inputminted} from working with \texttt{outputdir}. % \item Added informative error messages when Pygments output is missing. % \item Added \texttt{final} package option (opposite of \texttt{draft}). % \item Renamed the default cache directory to \texttt{\_minted-} (replaced leading period with underscore). The leading period caused the cache directory to be hidden on many systems, which was a potential source of confusion. % \item \texttt{breaklines} and \texttt{breakbytoken} now work with \texttt{\string\mintinline} (\#31). % \item \texttt{bgcolor} may now be set through \texttt{\string\setminted} and \texttt{\string\setmintedinline}. % \item When math is enabled via \texttt{texcomments}, \texttt{mathescape}, or \texttt{escapeinside}, space characters now behave as in normal math by vanishing, instead of appearing as literal spaces. Math need no longer be specially formatted to avoid undesired spaces. % \item In default value of \texttt{\string\listoflistingscaption}, capitalized ``Listings'' so that capitalization is consistent with default values for other lists (figures, tables, algorithms, etc.). % \item Added \texttt{newfloat} package option that creates the \texttt{listing} environment using \texttt{newfloat} rather than \texttt{float}, thus providing better compatibility with the \texttt{caption} package (\#12). % \item Added support for Pygments option \texttt{stripall}. % \item Added \texttt{breakbytoken} option that prevents \texttt{breaklines} from breaking lines within Pygments tokens. % \item \texttt{\string\mintinline} uses a \texttt{\string\colorbox} when \texttt{bgcolor} is set, to give more reasonable behavior (\#57). % \item For PHP, \texttt{\string\mintinline} automatically begins with \texttt{startinline=true} (\#23). % \item Fixed a bug that threw off line numbering in \texttt{minted} when \texttt{langlinenos=false} and \texttt{firstnumber=last}. Fixed a bug in \texttt{\string\mintinline} that threw off subsequent line numbering when \texttt{langlinenos=false} and \texttt{firstnumber=last}. % \item Improved behavior of \texttt{\string\mint} and \texttt{\string\mintinline} in \texttt{draft} mode. % \item The \texttt{\string\mint} command now has the additional capability to take code delimited by paired curly braces \texttt{\{\}}. % \item It is now possible to set options only for \texttt{\string\mintinline} using the new \texttt{\string\setmintedinline} command. Inline options override options specified via \texttt{\string\setminted}. % \item Completely rewrote option handling. \pkg{fancyvrb} options are now handled on the \LaTeX\ side directly, rather than being passed to Pygments and then returned. This makes caching more efficient, since code is no longer rehighlighted just because \pkg{fancyvrb} options changed. % \item Fixed buffer size error caused by using \texttt{cache} with a very large number of files (\#61). % \item Fixed \texttt{autogobble} bug that caused failure under some operating systems. % \item Added support for \texttt{escapeinside} (requires Pygments 2.0+; \#38). % \item Fixed issues with XeTeX and caching (\#40). % \item The \texttt{upquote} package now works correctly with single quotes when using Pygments 1.6+ (\#34). % \item Fixed caching incompatibility with Linux and OS X under xelatex (\#18 and \#42). % \item Fixed \texttt{autogobble} incompatibility with Linux and OS X. % \item \texttt{\string\mintinline} and derived commands are now robust, via \texttt{\string\newrobustcmd} from \texttt{etoolbox}. % \item Unused styles are now cleaned up when caching. % \item Fixed a bug that could interfere with caching (\#24). % \item Added \texttt{draft} package option (\#39). This typesets all code using \texttt{fancyvrb}; Pygments is not used. This trades syntax highlighting for maximum speed in compiling. % \item Added automatic line breaking with \texttt{breaklines} and related options (\#1). % \item Fixed a bug with boolean options that needed a False argument to cooperate with \texttt{\string\setminted} (\#48). % \end{changelog} % % \begin{changelog}{v2.0-alpha3}{2013/12/21} % \item Added \texttt{autogobble} option. This sends code through Python's \texttt{textwrap.dedent()} to remove common leading whitespace. % \item Added package option \texttt{cachedir}. This allows the directory in which cached content is saved to be specified. % \item Added package option \texttt{outputdir}. This allows an output directory for temporary files to be specified, so that the package can work with LaTeX's \texttt{-output-directory} command-line option. % \item The \texttt{kvoptions} package is now required. It is needed to process key-value package options, such as the new \texttt{cachedir} option. % \item Many small improvements, including better handling of paths under Windows and improved key system. % \end{changelog} % % \begin{changelog}{v2.0-alpha2}{2013/08/21} % \item \texttt{\string\DeleteFile} now only deletes files if they do indeed exist. This eliminates warning messages due to missing files. % \item Fixed a bug in the definition of \texttt{\string\DeleteFile} for non-Windows systems. % \item Added support for Pygments option \texttt{stripnl}. % \item Settings macros that were previously defined globally are now defined locally, so that \texttt{\string\setminted} may be confined by \texttt{\string\begingroup...\string\endgroup} as expected. % \item Macro definitions for a given style are now loaded only once per document, rather than once per command/environment. This works even without caching. % \item A custom script/executable may now be substituted for \texttt{pygmentize} by redefining \texttt{\string\MintedPygmentize}. % \end{changelog} % % % \begin{changelog}{v2.0alpha}{2013/07/30} % \item Added the package option \texttt{cache}. This significantly increases compilation speed by caching old output. For example, compiling the documentation is around 5x faster. % \item New inline command \texttt{\string\mintinline}. Custom versions can be created via \texttt{\string\newmintinline}. The command works inside other commands (for example, footnotes) in most situations, so long as the percent and hash characters are avoided. % \item The new \texttt{\string\setminted} command allows options to be specified at the document and language levels. % \item All extended characters (Unicode, etc.) supported by \texttt{inputenc} now work under the pdfTeX engine. This involved using \texttt{\string\detokenize} on everything prior to saving. % \item New package option \texttt{langlinenos} allows line numbering to pick up where it left off for a given language when \texttt{firstnumber=last}. % \item New options, including \texttt{style}, \texttt{encoding}, \texttt{outencoding}, \texttt{codetagify}, \texttt{keywordcase}, \texttt{texcomments} (same as \texttt{texcl}), \texttt{python3} (for the \texttt{PythonConsoleLexer}), and \texttt{numbers}. % \item \texttt{\string\usemintedstyle} now takes an optional argument to specify the style for a particular language, and works anywhere in the document. % \item \texttt{xcolor} is only loaded if \texttt{color} isn't, preventing potential package clashes. % \end{changelog} % % % \begin{changelog}{1.7}{2011/09/17} % \item Options for float placement added [2011/09/12] % \item Fixed \texttt{tabsize} option [2011/08/30] % \item More robust detection of the \texttt{-shell-escape} option [2011/01/21] % \item Added the \texttt{label} option [2011/01/04] % \item Installation instructions added [2010/03/16] % \item Minimal working example added [2010/03/16] % \item Added PHP-specific options [2010/03/14] % \item Removed unportable flag from Unix shell command [2010/02/16] % \end{changelog} % % % \begin{changelog}{1.6}{2010/01/31} % \item Added font-related options [2010/01/27] % \item Windows support added [2010/01/27] % \item Added command shortcuts [2010/01/22] % \item Simpler versioning scheme [2010/01/22] % \end{changelog} % % % \begin{changelog}{0.1.5}{2010/01/13} % \item Added \texttt{fillcolor} option [2010/01/10] % \item Added float support [2010/01/10] % \item Fixed \texttt{firstnumber} option [2010/01/10] % \item Removed \texttt{caption} option [2010/01/10] % \end{changelog} % % % \begin{changelog}{0.0.4}{2010/01/08} % \item Initial version [2010/01/08] % \end{changelog} % % % %\DoNotIndex{\newcommand,\newenvironment} % %\DoNotIndex{\#,\$,\%,\&,\@,\\,\{,\},\^,\_,\~,\ } % %\DoNotIndex{\@ne} % %\DoNotIndex{\advance,\begingroup,\catcode,\closein} % %\DoNotIndex{\closeout,\day,\def,\edef,\else,\empty,\endgroup} % %\DoNotIndex{\begin,\end,\bgroup,\egroup} % %\DoNotIndex{\@namedef,\@nameuse,=,\csname,\endcsname} % % % \GetFileInfo{minted.sty} % % \newcommand\pkg[1]{\textsf{#1}} % \newcommand\app[1]{\textsf{#1}} % % \title{The \textcolor{minted@mint}{\pkg{minted}} package:\\Highlighted source code in \LaTeX} % \author{Geoffrey M.\ Poore \\ \url{gpoore@gmail.com} \\ \href{https://github.com/gpoore/minted}{\texttt{github.com/gpoore/minted}} \\ ~\\ Originally created and maintained (2009--2013) by \\ Konrad Rudolph} % \date{\fileversion~from \filedate} % % \maketitle % % \begin{abstract} % \noindent\pkg{minted} is a package that facilitates expressive syntax highlighting % using the powerful \app{Pygments} library. The package also provides options to % customize the highlighted source code output. % \end{abstract} % % \vspace{2in} % % \subsection*{License} % \href{http://www.latex-project.org/lppl.txt}{LaTeX Project Public License (LPPL)} version 1.3. % % Additionally, the project may be distributed under the terms of the 3-Clause % (``New'') BSD license: \url{http://opensource.org/licenses/BSD-3-Clause}. % % \pagebreak % % \tableofcontents % % \fvset{ % codes={\catcode`\%=9}, ^^A Ignore initial |%| % numbersep=5pt, % } % \setlength{\fboxsep}{1ex} % % \mbox{}\newpage % \section{Introduction} % % % % \pkg{minted} is a package that allows formatting source code in \LaTeX. % For example: % \begin{VerbatimOut}[gobble=1]{minted.doc.out} % \begin{minted}{} % % \end{minted} % \end{VerbatimOut} % \inputminted[gobble=2,frame=lines]{latex}{minted.doc.out} % % will highlight a piece of code in a chosen language. % The appearance can be customized with a number of options and color schemes. % % Unlike some other packages, most notably \pkg{listings}, \pkg{minted} requires % the installation of additional software, \app{Pygments}. % This may seem like a disadvantage, but there are also significant advantages. % % \app{Pygments} provides superior syntax highlighting compared to conventional packages. % For example, \pkg{listings} basically only highlights strings, comments and keywords. % \app{Pygments}, on the other hand, can be completely customized to highlight any kind of token the % source language might support. % This might include special formatting sequences inside strings, numbers, different kinds of % identifiers and exotic constructs such as HTML tags. % % Some languages make this especially desirable. % Consider the following Ruby code as an extreme, but at the same time typical, example: % % \begin{minted}[gobble=3]{ruby} % class Foo % def init % pi = Math::PI % @var = "Pi is approx. #{pi}" % end % end % \end{minted} % % Here we have four different colors for identifiers (five, if you count keywords) and escapes from % inside strings, none of which pose a problem for \app{Pygments}. % % Additionally, installing \app{Pygments} is actually incredibly easy (see the next section). % % % \section{Installation} % % \subsection{Prerequisites} % % \app{Pygments} is written in Python, so make sure that you have Python 2.6 or later installed on your system. This may be easily checked from the command line: % % \begin{Verbatim}[gobble=3,commandchars=\\\{\}] % \$ python --version % Python 2.7.5 % \end{Verbatim} % % If you don't have Python installed, you can download it from the \href{http://www.python.org/download/}{Python website} or % use your operating system's package manager. % % Some Python distributions include \pkg{Pygments} (see some of the options under ``Alternative Implementations'' on the Python site). Otherwise, you will need to install \pkg{Pygments} manually. This may be done by installing \href{http://pypi.python.org/pypi/setuptools}{\app{setuptools}}, which facilitates the distribution of Python applications. You can then install \app{Pygments} using the following command: % \begin{Verbatim}[gobble=3,commandchars=\\\{\}] % \$ sudo easy_install Pygments % \end{Verbatim} % Under Windows, you will not need the |sudo|, but may need to run the command prompt as administrator. \pkg{Pygments} may also be installed with |pip|: % \begin{Verbatim}[gobble=3,commandchars=\\\{\}] % \$ pip install Pygments % \end{Verbatim} % % If you already have \app{Pygments} installed, be aware that the latest version is recommended (at least 1.4 or later). Some features, such as |escapeinside|, will only work with 2.0+. \pkg{minted} may work with versions as early as 1.2, but there are no guarantees. % % % \subsection{Required packages} % % \pkg{minted} requires that the following packages be available and reasonably up to date on your system. All of these ship with recent \TeX\ distributions. % % \begin{multicols}{3} % \begingroup % \setlength\parskip{0pt} % \setlength\topsep{0pt} % \begin{list}{\textrm{\labelitemi}}{\ttfamily} % \item keyval % \item kvoptions % \item fancyvrb % \item fvextra % \item upquote % \item float % \item ifthen % \item calc % \item ifplatform % \item pdftexcmds % \item etoolbox % \item xstring % \item xcolor % \item lineno % \item framed % \item shellesc (for luatex 0.87+) % \end{list} % \endgroup % \end{multicols} % % % \subsection{Installing \pkg{minted}} % \label{sec:installing:installing} % % You can probably install \pkg{minted} with your \TeX\ distribution's package manager. Otherwise, or if you want the absolute latest version, you can install it manually by following the directions below. % % You may download |minted.sty| from the % \href{https://github.com/gpoore/minted}{project's homepage}. We have to install the file so that \TeX\ is able to find it. % In order to do that, please refer to the % \href{http://www.tex.ac.uk/cgi-bin/texfaq2html?label=inst-wlcf}{\TeX{} FAQ}. % If you just want to experiment with the latest version, you could locate your current |minted.sty| in your \TeX\ installation and replace it with the latest version. Or you could just put the latest |minted.sty| in the same directory as the file you wish to use it with. % % % \section{Basic usage} % % \subsection{Preliminary} % \label{sec:basic:preliminary} % % Since \pkg{minted} makes calls to the outside world (that is, \app{Pygments}), you need to tell the % \LaTeX{} processor about this by passing it the |-shell-escape| option or it won't allow such calls. % In effect, instead of calling the processor like this: % \begin{Verbatim}[gobble=3,commandchars=\\\{\}] % \$ latex input % \end{Verbatim} % % you need to call it like this: % % \begin{Verbatim}[gobble=3,commandchars=\\\{\}] % \$ latex -shell-escape input % \end{Verbatim} % % The same holds for other processors, such as |pdflatex| or |xelatex|. % % You should be aware that using |-shell-escape| allows \LaTeX\ to run potentially arbitrary commands on your system. It is probably best to use |-shell-escape| only when you need it, and to use it only with documents from trusted sources. % % % \subsubsection*{Working with OS X} % % If you are using \pkg{minted} with some versions/configurations of OS X, and are using caching with a large number of code blocks ($>256$), you may receive an error like %\begin{Verbatim} %OSError: [Errno 24] Too many open files: %\end{Verbatim} % This is due to the way files are handled by the operating system, combined with the way that caching works. To resolve this, you may use the OS X commands |launchctl limit maxfiles| or |ulimit -n| to increase the number of files that may be used. % % % % \subsection{A minimal complete example} % % The following file |minimal.tex| shows the basic usage of \pkg{minted}. % % \begin{VerbatimOut}[gobble=1]{minted.doc.out} % \documentclass{article} % % \usepackage{minted} % % \begin{document} % \begin{minted}{c} % int main() { % printf("hello, world"); % return 0; % } % \end{minted} % \end{document} % \end{VerbatimOut} % \inputminted[gobble=2,frame=lines]{latex}{minted.doc.out} % % By compiling the source file like this: % % \begin{Verbatim}[gobble=3,commandchars=\\\{\}] % \$ pdflatex -shell-escape minimal % \end{Verbatim} % % we end up with the following output in |minimal.pdf|: % % \hfill % \colorbox{minted@samplebg}{\begin{minipage}{0.6\textwidth} % \inputminted[firstline=7,lastline=10]{c}{minted.doc.out} % \end{minipage}} % \hfill\hfill % % % \subsection{Formatting source code} % % \DescribeEnv{minted} % Using \pkg{minted} is straightforward. For example, to highlight some Python source code we might use % the following code snippet (result on the right): % % \begin{example} % \begin{minted}{python} % def boring(args = None): % pass % \end{minted} % \end{example} % % Optionally, the environment accepts a number of options in |key=value| notation, which are described % in more detail below. % % % \DescribeMacro{\mint} % For a single line of source code, you can alternatively use a shorthand notation: % % \begin{example} % \mint{python}|import this| % \end{example} % % This typesets a single line of code using a command rather than an environment, so it saves a little typing, but its output is equivalent to that of the |minted| environment. % % The code is delimited by a pair of identical characters, similar to how |\verb| works. The complete syntax is \cmd\mint\oarg{options}\marg{language}\meta{delim}\meta{code}\meta{delim}, % where the code delimiter can be almost any punctuation character. % The \meta{code} may also be delimited with matched curly braces |{}|, so long as \meta{code} itself does not contain unmatched curly braces. % Again, this command supports a number of options described below. % % Note that the |\mint| command \textbf{is not for inline use}. Rather, it is a shortcut for |minted| when only a single line of code is present. The |\mintinline| command is provided for inline use. % % % \DescribeMacro{\mintinline} % Code can be typeset inline: % % \begin{example} % X\mintinline{python}{print(x**2)}X % \end{example} % % The syntax is \cmd\mintinline\oarg{options}\marg{language}\meta{delim}\meta{code}\meta{delim}. The delimiters can be a pair of characters, as for \cmd\mint. They can also be a matched pair of curly braces, |{}|. % % The command has been carefully crafted so that in most cases it will function correctly when used inside other commands.\footnote{For example, \mintinline{latex}{\mintinline} works in footnotes! The main exception is when the code contains the percent \texttt{\%} or hash \texttt{\#} characters, or unmatched curly braces.} % % \DescribeMacro{\inputminted} % Finally, there's the |\inputminted| command to read and format whole files. % Its syntax is \cmd\inputminted\oarg{options}\marg{language}\marg{filename}. % % % \subsection{Using different styles} % % \DescribeMacro{\usemintedstyle} % Instead of using the default style you may choose another stylesheet provided by \app{Pygments}. This may be done via the following: % % \mint[frame=lines]{latex}/\usemintedstyle{name}/ % % The full syntax is \cmd\usemintedstyle\oarg{language}\marg{style}. The style may be set for the document as a whole (no language specified), or only for a particular language. Note that the style may also be set via \cmd\setminted\ and via the optional argument for each command and environment.\footnote{Version 2.0 added the optional language argument and removed the restriction that the command be used in the preamble.} % % To get a list of all available stylesheets, see the online demo at the \href{http://pygments.org/demo/}{Pygments website} or execute the following command on the command line: % % \begin{Verbatim}[gobble=3,commandchars=\\\{\}] % \$ pygmentize -L styles % \end{Verbatim} % % % Creating your own styles is also easy. Just follow the instructions provided on the % \href{http://pygments.org/docs/styles/#creating-own-styles}{\pkg{Pygments} website}. % % % \subsection{Supported languages} % % \app{Pygments} supports over 300 different programming languages, template languages, and other markup languages. To see an exhaustive list of the currently supported languages, use the command % % \begin{Verbatim}[gobble=3,commandchars=\\\{\}] % \$ pygmentize -L lexers % \end{Verbatim} % % % \section{Floating listings}\label{sec:float} % % \DescribeEnv{listing} % \pkg{minted} provides the |listing| environment to wrap around a source code block. This puts the code into a floating box, with the default placement |tbp| like figures and tables. You can also provide a |\caption| and a |\label| for such a listing in the usual way (that is, as for the |figure| and |table| environments): % \begin{VerbatimOut}[gobble=1]{minted.doc.out} % \begin{listing}[H] % \mint{cl}/(car (cons 1 '(2)))/ % \caption{Example of a listing.} % \label{lst:example} % \end{listing} % % Listing \ref{lst:example} contains an example of a listing. % \end{VerbatimOut} % \inputminted[gobble=2,frame=lines]{latex}{minted.doc.out} % % will yield: % % \hfill % \colorbox{minted@samplebg}{\begin{minipage}{0.6\textwidth} % \input{minted.doc.out} % \end{minipage}} % \hfill\hfill % % The default |listing| placement can be modified easily. When the package option |newfloat=false| (default), the \pkg{float} package is used to create the |listing| environment. Placement can be modified by redefining |\fps@listing|. For example, %\begin{verbatim} %\makeatletter %\renewcommand{\fps@listing}{htp} %\makeatother %\end{verbatim} % When |newfloat=true|, the more powerful \pkg{newfloat} package is used to create the |listing| environment. In that case, \pkg{newfloat} commands are available to customize |listing|: %\begin{verbatim} %\SetupFloatingEnvironment{listing}{placement=htp} %\end{verbatim} % % % \DescribeMacro{\listoflistings} % The |\listoflistings| macro will insert a list of all (floated) listings in the document: % % \begin{example} % \listoflistings % \end{example} % % \subsection*{Customizing the \texttt{listing} environment} % By default, the |listing| environment is created using the \pkg{float} package. In that case, the |\listingscaption| and |\listoflistingscaption| macros described below may be used to customize the caption and list of listings. If \pkg{minted} is loaded with the |newfloat| option, then the |listing| environment will be created with the more powerful \href{http://www.ctan.org/pkg/newfloat}{\pkg{newfloat}} package instead. \pkg{newfloat} is part of \href{http://www.ctan.org/pkg/caption}{\pkg{caption}}, which provides many options for customizing captions. % % When \pkg{newfloat} is used to create the |listing| environment, customization should be achieved using \pkg{newfloat}'s |\SetupFloatingEnvironment| command. For example, the string ``Listing'' in the caption could be changed to ``Program code'' using %\begin{verbatim} %\SetupFloatingEnvironment{listing}{name=Program code} %\end{verbatim} % And ``List of Listings'' could be changed to ``List of Program Code'' with %\begin{verbatim} %\SetupFloatingEnvironment{listing}{listname=List of Program Code} %\end{verbatim} % Refer to the \pkg{newfloat} and \pkg{caption} documentation for additional information. % % \DescribeMacro{\listingscaption} % (Only applies when package option |newfloat| is not used.) The string ``Listing'' in a listing's caption can be changed. % To do this, simply redefine the macro |\listingscaption|, for example: % % \mint[frame=lines]{latex}/\renewcommand{\listingscaption}{Program code}/ % % \DescribeMacro{\listoflistingscaption} % (Only applies when package option |newfloat| is not used.) Likewise, the caption of the listings list, ``List of Listings,'' can be changed by redefining % |\listoflistingscaption|: % % \mint[frame=lines]{latex}/\renewcommand{\listoflistingscaption}{List of Program Code}/ % % % \section{Options} % % % % \subsection{Package options} % % \DescribeMacro{chapter} % To control how \LaTeX{} counts the |listing| floats, you can pass either the % |section| or |chapter| option when loading the \pkg{minted} package. % For example, the following will cause listings to be counted by chapter: % % \mint[frame=lines]{latex}/\usepackage[chapter]{minted}/ % % % \DescribeMacro{cache=\meta{boolean} (default:~true)} % \pkg{minted} works by saving code to a temporary file, highlighting the code via \app{Pygments} and saving the output to another temporary file, and inputting the output into the \LaTeX\ document. This process can become quite slow if there are several chunks of code to highlight. To avoid this, the package provides a |cache| option. This is on by default. % % The |cache| option creates a directory |_minted-|\meta{jobname} in the document's root directory (this may be customized with the |cachedir| option).\footnote{The directory is actually named using a ``sanitized'' copy of \meta{jobname}, in which spaces and asterisks have been replaced by underscores, and double quotation marks have been stripped. If the file name contains spaces, \texttt{\string\jobname} will contain a quote-wrapped name, except under older versions of MiKTeX which used the name with spaces replaced by asterisks. Using a ``sanitized'' \meta{jobname} is simpler than accomodating the various escaping conventions.} Files of highlighted code are stored in this directory, so that the code will not have to be highlighted again in the future. In most cases, caching will significantly speed up document compilation. % % Cached files that are no longer in use are automatically deleted.\footnote{This depends on the main auxiliary file not being deleted or becoming corrupted. If that happens, you could simply delete the cache directory and start over.} % % % \DescribeMacro{cachedir=\meta{directory} (def:~\_minted-\meta{jobname})} % This allows the directory in which cached files are stored to be specified. Paths should use forward slashes, even under Windows. % % Special characters must be escaped. For example, |cachedir=~/mintedcache| would not work because the tilde |~| would be converted into the \LaTeX\ commands for a non-breaking space, rather than being treated literally. Instead, use |\string~/mintedcache|, |\detokenize{~/mintedcache}|, or an equivalent solution. % % Paths may contain spaces, but only if the entire \meta{directory} is wrapped in curly braces |{}|, and only if the spaces are quoted. For example, %\begin{Verbatim} %cachedir = {\detokenize{~/"minted cache"/"with spaces"}} %\end{Verbatim} % % Note that the cache directory is relative to the |outputdir|, if an |outputdir| is specified. % % % \DescribeMacro{finalizecache=\meta{boolean} (default:~false)} % In some cases, it may be desirable to use \pkg{minted} in an environment in which |-shell-escape| is not allowed. A document might be submitted to a publisher or preprint server or used with an online service that does not support |-shell-escape|. This is possible as long as \pkg{minted} content does not need to be modified. % % Compiling with the |finalizecache| option prepares the cache for use in an environment without |-shell-escape|.\footnote{Ordinarily, cache files are named using an MD5 hash of highlighting settings and highlighted text. \texttt{finalizecache} renames cache files using a \texttt{listing.pygtex} scheme. This makes it simpler to match up document content and cache files, and is also necessary for the XeTeX engine since prior to TeX Live 2016 it lacked the built-in MD5 capabilities that pdfTeX and LuaTeX have.} Once this has been done, the |finalizecache| option may be swapped for the |frozencache| option, which will then use the frozen (static) cache in the future, without needing |-shell-escape|. % % % \DescribeMacro{frozencache=\meta{boolean} (default:~false)} % Use a frozen (static) cache created with the |finalizecache| option. When |frozencache| is on, |-shell-escape| is not needed, and Python and Pygments are not required. In addition, any external files accessed through |\inputminted| are no longer necessary. % % \textbf{This option must be used with care. A document \emph{must} be in final form, as far as \pkg{minted} is concerned, \emph{before} \texttt{frozencache} is turned on, and the document \emph{must} have been compiled with \texttt{finalizecache}. When this option is on, \pkg{minted} content cannot be modified, except by editing the cache files directly. Changing any \pkg{minted} settings that require Pygments or Python is not possible. If \pkg{minted} content is incorrectly modified after \texttt{frozencache} is turned on, \pkg{minted} \emph{cannot} detect the modification.} % % If you are using |frozencache|, and want to verify that \pkg{minted} settings or content have not been modified in an invalid fashion, you can test the cache using the following procedure. % \begin{enumerate} % \item Obtain a copy of the cache used with |frozencache|. % \item Compile the document in an environment that supports |-shell-escape|, with |finalizecache=true| and |frozencache=false|. This essentially regenerates the frozen (static) cache. % \item Compare the original cache with the newly generated cache. Under Linux and OS X, you could use |diff|; under Windows, you probably want |fc|. If \pkg{minted} content and settings have not been modified in an invalid fashion, all files will be identical (assuming that compatible versions of Pygments are used for both caches). % \end{enumerate} % % % \DescribeMacro{draft=\meta{boolean} (default:~false)} % This uses \pkg{fancyvrb} alone for all typesetting; \app{Pygments} is not used. This trades syntax highlighting and some other \app{minted} features for faster compiling. Performance should be essentially the same as using \pkg{fancyvrb} directly; no external temporary files are used. Note that if you are not changing much code between compiles, the difference in performance between caching and draft mode may be minimal. Also note that |draft| settings are typically inherited from the document class. % % Draft mode does not support |autogobble|. Regular |gobble|, |linenos|, and most other options not related to syntax highlighting will still function in draft mode. % % Documents can usually be compiled without shell escape in draft mode. The \pkg{ifplatform} package may issue a warning about limited functionality due to shell escape being disabled, but this may be ignored in almost all cases. (Shell escape is only really required if you have an unusual system configuration such that the |\ifwindows| macro must fall back to using shell escape to determine the system. See the \pkg{ifplatform} documentation for more details: \url{http://www.ctan.org/pkg/ifplatform}.) % % If the |cache| option is set, then all existing cache files will be kept while draft mode is on. This allows caching to be used intermitently with draft mode without requiring that the cache be completely recreated each time. Automatic cleanup of cached files will resume as soon as draft mode is turned off. (This assumes that the auxiliary file has not been deleted in the meantime; it contains the cache history and allows automatic cleanup of unused files.) % % % \DescribeMacro{final=\meta{boolean} (default:~true)} % This is the opposite of |draft|; it is equivalent to |draft=false|. Again, note that |draft| and |final| settings are typically inherited from the document class. % % % \DescribeMacro{kpsewhich=\meta{boolean} (default:~false)} % This option uses |kpsewhich| to locate files that are to be highlighted. Some build tools such as |texi2pdf| function by modifying |TEXINPUTS|; in some cases, users may customize |TEXINPUTS| as well. The |kpsewhich| option allows \pkg{minted} to work with such configurations. % % This option may add a noticeable amount of overhead on some systems, or with some system configurations. % % This option does \emph{not} make \pkg{minted} work with the |-output-directory| and |-aux-directory| command-line options for \LaTeX. For those, see the |outputdir| package option. % % % \DescribeMacro{langlinenos=\meta{boolean} (default:~false)} % \pkg{minted} uses the \pkg{fancyvrb} package behind the scenes for the code typesetting. \pkg{fancyvrb} provides an option |firstnumber| that allows the starting line number of an environment to be specified. For convenience, there is an option |firstnumber=last| that allows line numbering to pick up where it left off. The |langlinenos| option makes |firstnumber| work for each language individually with all |minted| and |\mint| usages. For example, consider the code and output below. % % \begin{VerbatimOut}[gobble=1]{minted.doc.out} % \begin{minted}[linenos]{python} % def f(x): % return x**2 % \end{minted} % % \begin{minted}[linenos]{ruby} % def func % puts "message" % end % \end{minted} % % \begin{minted}[linenos, firstnumber=last]{python} % def g(x): % return 2*x % \end{minted} % \end{VerbatimOut} % \inputminted[frame=single, rulecolor=minted@linkcolor]{latex}{minted.doc.out} % \hfill % \colorbox{minted@samplebg}{\begin{minipage}{0.6\textwidth} % \input{minted.doc.out} % \end{minipage}} % \hfill\hfill % % Without the |langlinenos| option, the line numbering in the second Python environment would not pick up where the first Python environment left off. Rather, it would pick up with the Ruby line numbering. % % % \DescribeMacro{newfloat=\meta{boolean} (default:~false)} % By default, the |listing| environment is created using the \pkg{float} package. The |newfloat| option creates the environment using \pkg{newfloat} instead. This provides better integration with the \pkg{caption} package. % % % \DescribeMacro{outputdir=\meta{directory} (default:~\meta{none})} % The |-output-directory| and |-aux-directory| (MiKTeX) command-line options for \LaTeX\ cause problems for \pkg{minted}, because the \pkg{minted} temporary files are saved in ||, but \pkg{minted} still looks for them in the document root directory. There is no way to access the value of the command-line option so that \pkg{minted} can automatically look in the right place. But it is possible to allow the output directory to be specified manually as a package option. % % The output directory should be specified using an absolute path or a path relative to the document root directory. Paths should use forward slashes, even under Windows. Special characters must be escaped, while spaces require quoting and need the entire \meta{directory} to be wrapped in curly braces |{}|. See |cachedir| above for examples of escaping and quoting. % % % \DescribeMacro{section} % To control how \LaTeX{} counts the |listing| floats, you can pass either the % |section| or |chapter| option when loading the \pkg{minted} package. % % % \subsection{Macro option usage} % % All \pkg{minted} highlighting commands accept the same set of options. % Options are specified as a comma-separated list of |key=value| pairs. % For example, we can specify that the lines should be numbered: % % \begin{example} % \begin{minted}[linenos=true]{c++} % #include % int main() { % std::cout << "Hello " % << "world" % << std::endl; % } % \end{minted} % \end{example} % % An option value of |true| may also be omitted entirely (including the ``|=|''). % To customize the display of the line numbers further, override the |\theFancyVerbLine| command. % Consult the \pkg{fancyvrb} documentation for details. % % |\mint| accepts the same options: % % \begin{example} % \mint[linenos]{perl}|$x=~/foo/| % \end{example} % % Here's another example: we want to use the \LaTeX{} math mode inside comments: % % \begin{example} % \begin{minted}[mathescape]{python} % # Returns $\sum_{i=1}^{n}i$ % def sum_from_one_to(n): % r = range(1, n + 1) % return sum(r) % \end{minted} % \end{example} % % To make your \LaTeX{} code more readable you might want to indent the code inside a |minted| % environment. % The option |gobble| removes these unnecessary whitespace characters from the output. There is also an |autogobble| option that detects the length of this whitespace automatically. % % \begin{example} % \begin{minted}[gobble=2, % showspaces]{python} % def boring(args = None): % pass % \end{minted} % % versus % % \begin{minted}[showspaces]{python} % def boring(args = None): % pass % \end{minted} % \end{example} % % \DescribeMacro{\setminted} % You may wish to set options for the document as a whole, or for an entire language. This is possible via \cmd\setminted\oarg{language}\marg{key=value,...}. Language-specific options override document-wide options. Individual command and environment options override language-specific options. % % \DescribeMacro{\setmintedinline} % You may wish to set separate options for \cmd\mintinline, either for the document as a whole or for a specific language. This is possible via \cmd\setmintedinline. The syntax is % \cmd\setmintedinline\oarg{language}\marg{key=value,...}. Language-specific options override document-wide options. Individual command options override language-specific options. All settings specified with \cmd\setmintedinline\ override those set with \cmd\setminted. That is, inline settings always have a higher precedence than general settings. % % \subsection{Available options} % % \newcommand\appliesto[1]{\textsf{[For #1 only]}} % % Following is a full list of available options. % For more detailed option descriptions please refer to the \pkg{fancyvrb} and \app{Pygments} documentation. % % \begin{optionlist} % \item[autogobble (boolean) (false)] % Remove (gobble) all common leading whitespace from code. Essentially a version of |gobble| that automatically determines what should be removed. Good for code that originally is not indented, but is manually indented after being pasted into a \LaTeX\ document. % % \begin{example} % ...text. % \begin{minted}[autogobble]{python} % def f(x): % return x**2 % \end{minted} % \end{example} % % \item[baselinestretch (dimension) (\meta{document default})] % Value to use as for baselinestretch inside the listing. % % % \item[beameroverlays (boolean) (false)] % Give the |<| and |>| characters their normal text meanings when used with |escapeinside| and |texcomments|, so that \pkg{beamer} overlays of the form |\only<1>{...}| will work. % % % \item[breakafter (string) (\meta{none})] % Break lines after specified characters, not just at spaces, when \texttt{breaklines=true}. Does not apply to |\mintinline|. % % For example, \texttt{breakafter=-/} would allow breaks after any hyphens or slashes. Special characters given to \texttt{breakafter} should be backslash-escaped (usually \texttt{\hashchar}, \texttt{\{}, \texttt{\}}, \texttt{\%}, \texttt{[}, \texttt{]}; the backslash \texttt{\textbackslash} may be obtained via \texttt{\textbackslash\textbackslash}). % % For an alternative, see \texttt{breakbefore}. When \texttt{breakbefore} and \texttt{breakafter} are used for the same character, \texttt{breakbeforegroup} and \texttt{breakaftergroup} must both have the same setting. % % \begin{longexample} % \begin{minted}[breaklines, breakafter=d]{python} % some_string = 'SomeTextThatGoesOnAndOnForSoLongThatItCouldNeverFitOnOneLine' % \end{minted} % \end{longexample} % % \item[breakaftergroup] (boolean) (true) % When \texttt{breakafter} is used, group all adjacent identical characters together, and only allow a break after the last character. When \texttt{breakbefore} and \texttt{breakafter} are used for the same character, \texttt{breakbeforegroup} and \texttt{breakaftergroup} must both have the same setting. % % \item[breakaftersymbolpre (string) (\string\,\string\footnotesize\string\ensuremath\{\_\string\rfloor\}, \,\footnotesize\ensuremath{_\rfloor})] % The symbol inserted pre-break for breaks inserted by \texttt{breakafter}. % % \item[breakaftersymbolpost (string) (\meta{none})] % The symbol inserted post-break for breaks inserted by \texttt{breakafter}. % % \item[breakanywhere (boolean) (false)] % Break lines anywhere, not just at spaces, when \texttt{breaklines=true}. Does not apply to |\mintinline|. % % \begingroup % \fvset{xrightmargin=1em} % \begin{longexample} % \begin{minted}[breaklines, breakanywhere]{python} % some_string = 'SomeTextThatGoesOnAndOnForSoLongThatItCouldNeverFitOnOneLine' % \end{minted} % \end{longexample} % \endgroup % % \item[breakanywheresymbolpre (string) (\string\,\string\footnotesize\string\ensuremath\{\_\string\rfloor\}, \,\footnotesize\ensuremath{_\rfloor})] % The symbol inserted pre-break for breaks inserted by \texttt{breakanywhere}. % % \item[breakanywheresymbolpost (string) (\meta{none})] % The symbol inserted post-break for breaks inserted by \texttt{breakanywhere}. % % \item[breakautoindent (boolean) (true)] % When a line is broken, automatically indent the continuation lines to the indentation level of the first line. When \texttt{breakautoindent} and \texttt{breakindent} are used together, the indentations add. This indentation is combined with \texttt{breaksymbolindentleft} to give the total actual left indentation. Does not apply to \texttt{\string\mintinline}. % % \item[breakbefore (string) (\meta{none})] % Break lines before specified characters, not just at spaces, when \texttt{breaklines=true}. Does not apply to |\mintinline|. % % For example, \texttt{breakbefore=A} would allow breaks before capital A's. Special characters given to \texttt{breakbefore} should be backslash-escaped (usually \texttt{\hashchar}, \texttt{\{}, \texttt{\}}, \texttt{\%}, \texttt{[}, \texttt{]}; the backslash \texttt{\textbackslash} may be obtained via \texttt{\textbackslash\textbackslash}). % % For an alternative, see \texttt{breakafter}. When \texttt{breakbefore} and \texttt{breakafter} are used for the same character, \texttt{breakbeforegroup} and \texttt{breakaftergroup} must both have the same setting. % % \begin{longexample} % \begin{minted}[breaklines, breakbefore=A]{python} % some_string = 'SomeTextThatGoesOnAndOnForSoLongThatItCouldNeverFitOnOneLine' % \end{minted} % \end{longexample} % % \item[breakbeforegroup] (boolean) (true) % When \texttt{breakbefore} is used, group all adjacent identical characters together, and only allow a break before the first character. When \texttt{breakbefore} and \texttt{breakafter} are used for the same character, \texttt{breakbeforegroup} and \texttt{breakaftergroup} must both have the same setting. % % \item[breakbeforesymbolpre (string) (\string\,\string\footnotesize\string\ensuremath\{\_\string\rfloor\}, \,\footnotesize\ensuremath{_\rfloor})] % The symbol inserted pre-break for breaks inserted by \texttt{breakbefore}. % % \item[breakbeforesymbolpost (string) (\meta{none})] % The symbol inserted post-break for breaks inserted by \texttt{breakbefore}. % % \item[breakbytoken (boolean) (false)] % Only break lines at locations that are not within tokens; prevent tokens from being split by line breaks. By default, \texttt{breaklines} causes line breaking at the space nearest the margin. While this minimizes the number of line breaks that are necessary, it can be inconvenient if a break occurs in the middle of a string or similar token. % % This is not compatible with \texttt{draft} mode. A complete list of Pygments tokens is available at \url{http://pygments.org/docs/tokens/}. If the breaks provided by \texttt{breakbytoken} occur in unexpected locations, it may indicate a bug or shortcoming in the Pygments lexer for the language. % % \item[breakbytokenanywhere (boolean) (false)] % Like \texttt{breakbytoken}, but also allows line breaks between immediately adjacent tokens, not just between tokens that are separated by spaces. Using \texttt{breakbytokenanywhere} with \texttt{breakanywhere} is redundant. % % \item[breakindent (dimension) (\meta{breakindentnchars})] % When a line is broken, indent the continuation lines by this amount. When |breakautoindent| and |breakindent| are used together, the indentations add. This indentation is combined with |breaksymbolindentleft| to give the total actual left indentation. % % Does not apply to \texttt{\string\mintinline}. % % \item[breakindentnchars (integer) (0)] % This allows |breakindent| to be specified as an integer number of characters rather than as a dimension (assumes a fixed-width font). % % \item[breaklines (boolean) (false)] % Automatically break long lines in \texttt{minted} environments and \texttt{\string\mint} commands, and wrap longer lines in \texttt{\string\mintinline}. % % By default, automatic breaks occur at space characters. Use \texttt{breakanywhere} to enable breaking anywhere; use \texttt{breakbytoken}, \texttt{breakbytokenanywhere}, \texttt{breakbefore}, and \texttt{breakafter} for more fine-tuned breaking. Currently, only \texttt{breakbytoken} and \texttt{breakbytokenanywhere} work with |\mintinline|. Using \texttt{escapeinside} to escape to \LaTeX\ and then insert a manual break is also an option. For example, use \texttt{escapeinside=||}, and then insert \texttt{|\textbackslash\textbackslash|} at the appropriate point. (Note that \texttt{escapeinside} does not work within strings.) % % \begin{example} % ...text. % \begin{minted}[breaklines]{python} % def f(x): % return 'Some text ' + str(x) % \end{minted} % \end{example} % % Breaking in \texttt{minted} and \texttt{\string\mint} may be customized in several ways. To customize the indentation of broken lines, see \texttt{breakindent} and \texttt{breakautoindent}. To customize the line continuation symbols, use \texttt{breaksymbolleft} and \texttt{breaksymbolright}. To customize the separation between the continuation symbols and the code, use \texttt{breaksymbolsepleft} and \texttt{breaksymbolsepright}. To customize the extra indentation that is supplied to make room for the break symbols, use \texttt{breaksymbolindentleft} and \texttt{breaksymbolindentright}. Since only the left-hand symbol is used by default, it may also be modified using the alias options \texttt{breaksymbol}, \texttt{breaksymbolsep}, and \texttt{breaksymbolindent}. Note than none of these options applies to \texttt{\string\mintinline}, since they are not relevant in the inline context. % % An example using these options to customize the \texttt{minted} environment is shown below. This uses the \texttt{\string\carriagereturn} symbol from the \pkg{dingbat} package. % % \begingroup % \fvset{breaklines, xleftmargin=2em, xrightmargin=2em} % \begin{longexample} % \begin{minted}[breaklines, % breakautoindent=false, % breaksymbolleft=\raisebox{0.8ex}{ % \small\reflectbox{\carriagereturn}}, % breaksymbolindentleft=0pt, % breaksymbolsepleft=0pt, % breaksymbolright=\small\carriagereturn, % breaksymbolindentright=0pt, % breaksymbolsepright=0pt]{python} % def f(x): % return 'Some text ' + str(x) + ' some more text ' + str(x) + ' even more text that goes on for a while' % \end{minted} % \end{longexample} % \endgroup % % Automatic line breaks are limited with \app{Pygments} styles that use a colored background behind large chunks of text. This coloring is accomplished with \texttt{\string\colorbox}, which cannot break across lines. It may be possible to create an alternative to \texttt{\string\colorbox} that supports line breaks, perhaps with \pkg{TikZ}, but the author is unaware of a satisfactory solution. The only current alternative is to redefine \texttt{\string\colorbox} so that it does nothing. For example, %\begin{Verbatim} %\AtBeginEnvironment{minted}{\renewcommand{\colorbox}[3][]{#3}} %\end{Verbatim} % uses the \pkg{etoolbox} package to redefine \texttt{\string\colorbox} within all \texttt{minted} environments. % % Automatic line breaks will not work with \texttt{showspaces=true} unless you use \texttt{breakanywhere} or \texttt{breakafter=\string\space}. % % \item[breaksymbol (string) (breaksymbolleft)] % Alias for \texttt{breaksymbolleft}. % % \item[breaksymbolleft (string) (\string\tiny\string\ensuremath\{\string\hookrightarrow\}, {\tiny\ensuremath{\hookrightarrow}})] % The symbol used at the beginning (left) of continuation lines when \texttt{breaklines=true}. To have no symbol, simply set \texttt{breaksymbolleft} to an empty string (``\texttt{=,}'' or ``\texttt{=\{\}}''). The symbol is wrapped within curly braces \texttt{\{\}} when used, so there is no danger of formatting commands such as \texttt{\string\tiny} ``escaping.'' % % The \texttt{\string\hookrightarrow} and \texttt{\string\hookleftarrow} may be further customized by the use of the \texttt{\string\rotatebox} command provided by \pkg{graphicx}. Additional arrow-type symbols that may be useful are available in the \pkg{dingbat} (\texttt{\string\carriagereturn}) and \pkg{mnsymbol} (hook and curve arrows) packages, among others. % % Does not apply to \texttt{\string\mintinline}. % % \item[breaksymbolright (string) (\meta{none})] % The symbol used at breaks (right) when \texttt{breaklines=true}. Does not appear at the end of the very last segment of a broken line. % % % \item[breaksymbolindent (dimension) (\meta{breaksymbolindentleftnchars})] % Alias for |breaksymbolindentleft|. % % \item[breaksymbolindentnchars (integer) (\meta{breaksymbolindentleftnchars})] % Alias for |breaksymbolindentleftnchars|. % % % \item[breaksymbolindentleft (dimension) (\meta{breaksymbolindentleftnchars})] % The extra left indentation that is provided to make room for |breaksymbolleft|. This indentation is only applied when there is a |breaksymbolleft|. % % Does not apply to \texttt{\string\mintinline}. % % \item[breaksymbolindentleftnchars (integer) (4)] % This allows |breaksymbolindentleft| to be specified as an integer number of characters rather than as a dimension (assumes a fixed-width font). % % \item[breaksymbolindentright (dimension) (\meta{breaksymbolindentrightnchars})] % The extra right indentation that is provided to make room for |breaksymbolright|. This indentation is only applied when there is a |breaksymbolright|. % % \item[breaksymbolindentrightnchars (integer) (4)] % This allows |breaksymbolindentright| to be specified as an integer number of characters rather than as a dimension (assumes a fixed-width font). % % % \item[breaksymbolsep (dimension) (\meta{breaksymbolsepleftnchars})] % Alias for |breaksymbolsepleft|. % % \item[breaksymbolsepnchars (integer) (\meta{breaksymbolsepleftnchars})] % Alias for |breaksymbolsepleftnchars|. % % % \item[breaksymbolsepleft (dimension) (\meta{breaksymbolsepleftnchars})] % The separation between the |breaksymbolleft| and the adjacent text. % % \item[breaksymbolsepleftnchars (integer) (2)] % Allows |breaksymbolsepleft| to be specified as an integer number of characters rather than as a dimension (assumes a fixed-width font). % % % \item[breaksymbolsepright (dimension) (\meta{breaksymbolseprightnchars})] % The \emph{minimum} separation between the |breaksymbolright| and the adjacent text. This is the separation between |breaksymbolright| and the furthest extent to which adjacent text could reach. In practice, |\linewidth| will typically not be an exact integer multiple of the character width (assuming a fixed-width font), so the actual separation between the |breaksymbolright| and adjacent text will generally be larger than |breaksymbolsepright|. This ensures that break symbols have the same spacing from the margins on both left and right. If the same spacing from text is desired instead, |breaksymbolsepright| may be adjusted. (See the definition of |\FV@makeLineNumber| in \pkg{fvextra} for implementation details.) % % \item[breaksymbolseprightnchars (integer) (2)] % Allows |breaksymbolsepright| to be specified as an integer number of characters rather than as a dimension (assumes a fixed-width font). % % % \item[bgcolor (string) (\meta{none})] % Background color of the listing. Be aware that this option has several limitations (described below); see ``Framing alternatives'' below for more powerful alternatives. % % The value of this option must \emph{not} be a color command. Instead, it must be a color \emph{name}, given as a string, of a previously-defined color: % % \begin{example} % \definecolor{bg}{rgb}{0.95,0.95,0.95} % \begin{minted}[bgcolor=bg]{php} % % \end{minted} % \end{example} % % This option puts \texttt{minted} environments and \texttt{\string\mint} commands in a \texttt{snugshade*} environment from the \pkg{framed} package, which supports breaks across pages. (Prior to \pkg{minted} 2.2, a \texttt{minipage} was used, which prevented page breaks and gave undesirable spacing from surrounding text.) Be aware that if \texttt{bgcolor} is used with \texttt{breaklines=true}, and a line break occurs just before a page break, then text may extend below the colored background in some instances. It is best to use a more advanced framing package in those cases; see ``Framing alternatives'' below. % % This option puts \texttt{\string\mintinline} inside a \texttt{\string\colorbox}, which \textbf{does not allow line breaks}. If you want to use \texttt{\string\setminted} to set background colors, and only want background colors on \texttt{minted} and \texttt{\string\mint}, you may use \texttt{\string\setmintedinline\{bgcolor=\{\}\}} to turn off the coloring for inline commands. % % ~ % % \textbf{Framing alternatives} % % If you want more reliable and advanced options for background colors and framing, you should consider a more advanced framing package such as \pkg{mdframed} or \pkg{tcolorbox}. It is easy to add framing to \pkg{minted} commands and environments using the \pkg{etoolbox} package, which is automatically loaded by \pkg{minted}. For example, using \pkg{mdframed}: %\begin{Verbatim} %\BeforeBeginEnvironment{minted}{\begin{mdframed}} %\AfterEndEnvironment{minted}{\end{mdframed}} %\end{Verbatim} % Some framing packages also provide built-in commands for such purposes. For example, \pkg{mdframed} provides a \texttt{\string\surroundwithmdframed} command, which could be used to add a frame to all \texttt{minted} environments: %\begin{Verbatim} %\surroundwithmdframed{minted} %\end{Verbatim} % \pkg{tcolorbox} even provides a built-in framing environment with \pkg{minted} support. Simply use \texttt{\string\tcbuselibrary\{minted\}} in the preamble, and then put code within a \texttt{tcblisting} environment: %\begin{Verbatim} %\begin{tcblisting}{, % minted language=, % minted style=