From 98c2bca5edfb6ec04214316a66cadd924dd45d62 Mon Sep 17 00:00:00 2001 From: Karl Berry Date: Thu, 14 Jul 2016 21:40:55 +0000 Subject: minted (14jul16) git-svn-id: svn://tug.org/texlive/trunk@41698 c570f23f-e606-0410-a88d-b1316a301751 --- Master/texmf-dist/doc/latex/minted/minted.pdf | Bin 717251 -> 802895 bytes Master/texmf-dist/source/latex/minted/minted.dtx | 1227 +++++----------------- Master/texmf-dist/tex/latex/minted/minted.sty | 489 +-------- 3 files changed, 285 insertions(+), 1431 deletions(-) (limited to 'Master/texmf-dist') diff --git a/Master/texmf-dist/doc/latex/minted/minted.pdf b/Master/texmf-dist/doc/latex/minted/minted.pdf index be23581983f..01d4da99503 100644 Binary files a/Master/texmf-dist/doc/latex/minted/minted.pdf and b/Master/texmf-dist/doc/latex/minted/minted.pdf differ diff --git a/Master/texmf-dist/source/latex/minted/minted.dtx b/Master/texmf-dist/source/latex/minted/minted.dtx index 710e0bf8388..a98819a41d9 100644 --- a/Master/texmf-dist/source/latex/minted/minted.dtx +++ b/Master/texmf-dist/source/latex/minted/minted.dtx @@ -31,7 +31,7 @@ %\NeedsTeXFormat{LaTeX2e} %\ProvidesPackage{minted} %<*package> - [2016/06/21 v2.2.2 Yet another Pygments shim for LaTeX] + [2016/07/14 v2.3 Yet another Pygments shim for LaTeX] % %<*driver> \documentclass{ltxdoc} @@ -43,26 +43,54 @@ \usepackage[utf8]{inputenc} \usepackage[T1]{fontenc} \usepackage{lmodern} -\usepackage{lstdoc} -\usepackage{xcolor} -\usepackage{upquote} +\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{courier} % Useful monospace font (= has \bfseries). -\usepackage{textcomp} -\usepackage{microtype} + \usepackage{environ} \usepackage{graphicx} -\usepackage{dingbat} \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}}% @@ -85,11 +113,6 @@ \fontshape\updefault% \small} -% FIXME This is incredibly hacky and overrides size commands around tt-text. -% But I don't get the font inside the main body to change otherwise. :-( -\let\mintedttold\ttfamily -\def\ttfamily{\mintedttold\fontsize{9}{9}\selectfont} -% \definecolor{minted@mint}{HTML}{0B610B} \definecolor{minted@samplebg}{HTML}{F0F0E0} \colorlet{minted@linkcolor}{minted@mint} @@ -104,6 +127,7 @@ pdftitle=The minted package: Highlighted source code in LaTeX, pdfauthor=Geoffrey M. Poore, pdfsubject={Minted LaTeX package manual}, + colorlinks=true, allcolors=minted@linkcolor, } % @@ -118,7 +142,7 @@ \inputminted[resetmargins]{latex}{example.out}% \end{minipage}% \hspace{0.05\linewidth}% - \begin{minipage}{0.4\linewidth}% + \begin{minipage}{0.45\linewidth-2\fboxsep}% \input{example.out}% \end{minipage}% \vspace{1ex}}} @@ -129,7 +153,7 @@ {\end{VerbatimOut}% \vspace{1ex}% \setlength{\parindent}{0pt}% - \fbox{\begin{minipage}{0.95\linewidth}% + \fbox{\begin{minipage}{\linewidth-2\fboxsep}% \inputminted[resetmargins]{latex}{example.out}% ~\hrulefill~ \input{example.out}% @@ -137,22 +161,23 @@ \vspace{1ex}}} \def\minted@printopt#1(#2) (#3){% + \vspace{0.1in}% \leavevmode% \marginpar{\raggedleft\texttt{\textcolor{minted@linkcolor}{#1}}\ }% - \textsf{(#2)}\hfill(default: #3)\\} + \kern-\parindent\textsf{(#2)}\hfill(default: \texttt{#3})\\} -\newenvironment{optionlist}{% - \par% +\newenvironment{optionlist}% + {% + ~\par\vspace{-14pt}% + \def\pipechar{|} + \let\|\pipechar \newcommand*\mintednext{}% \renewcommand*\item[1][]{% \mintednext% \renewcommand*\mintednext{\par}% \minted@printopt##1% - \ignorespaces} - \DeleteShortVerb{\|}% - \MakeShortVerb{\+}}{% - \DeleteShortVerb{\+}% - \MakeShortVerb{\|}% + \ignorespaces}} + {% \par} \edef\hashchar{\string#} @@ -170,7 +195,7 @@ % % \fi % -% \CheckSum{3841} +% \CheckSum{2928} % % \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 @@ -191,6 +216,16 @@ % % % +% \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} @@ -382,7 +417,6 @@ % \fvset{ % codes={\catcode`\%=9}, ^^A Ignore initial |%| % numbersep=5pt, -% fontsize=\small % } % \setlength{\fboxsep}{1ex} % @@ -470,6 +504,8 @@ % \item keyval % \item kvoptions % \item fancyvrb +% \item fvextra +% \item upquote % \item float % \item ifthen % \item calc @@ -498,27 +534,6 @@ % 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{Transitioning to version 2} -% -% Transitioning from \pkg{minted} 1.7 to 2.0+ should require no changes in almost all cases. Version 2 provides the same interface and all of the same features. -% -% In cases when custom code was used to hook into the \pkg{minted} internals, it may still be desirable to use the old \pkg{minted} 1.7. For those cases, the new package \pkg{minted1} is provided. Simply load this before any other package attempts to load \pkg{minted}, and you will have the code from 1.7. -% -% A brief summary of new features in version 2.0 is provided below. More detail is available in the \hyperref[sec:version-history]{Version History}. -% \begin{itemize} -% \item New inline command |\mintinline|. -% \item Support for caching highlighted code with new package option |cache|. This drastically reduces package overhead. Caching is on by default. A cache directory called |_minted-|\meta{document~name} will be created in the document root directory. This may be modified with the |cachedir| package option. -% \item Automatic line breaking for all commands and environments with new option |breaklines|. Many additional options for customizing line breaking. -% \item Support for Unicode under the pdfTeX engine. -% \item Set document-wide options using |\setminted{|\meta{opts}|}|. Set language-specific options using |\setminted[|\meta{lang}|]{|\meta{opts}|}|. Similarly, set inline-specific options using |\setmintedinline|. -% \item Package option |langlinenos|: do line numbering by language. -% \item Many new options, including |encoding|, |autogobble|, and |escapeinside| (requires Pygments 2.0+). -% \item New package option |outputdir| provides compatibility with command-line options |-output-directory| and |-aux-directory|. -% \item New package option |draft| disables Python use to give maximum performance. -% \item |\mint| can now take code delimited by matched curly braces |{}|. -% \end{itemize} -% -% % \section{Basic usage} % % \subsection{Preliminary} @@ -736,7 +751,7 @@ % \mint[frame=lines]{latex}/\usepackage[chapter]{minted}/ % % -% \DescribeMacro{cache=\meta{boolean} (default: true)} +% \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. @@ -757,13 +772,13 @@ % Note that the cache directory is relative to the |outputdir|, if an |outputdir| is specified. % % -% \DescribeMacro{finalizecache=\meta{boolean} (default: false)} +% \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)} +% \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.} @@ -776,7 +791,7 @@ % \end{enumerate} % % -% \DescribeMacro{draft=\meta{boolean} (default: false)} +% \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. @@ -786,11 +801,11 @@ % 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)} +% \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)} +% \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. @@ -800,7 +815,7 @@ % Under Windows, this option currently requires that PowerShell be installed. It may need to be installed in versions of Windows prior to Windows 7. % % -% \DescribeMacro{langlinenos=\meta{boolean} (default: false)} +% \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} @@ -820,7 +835,7 @@ % return 2*x % \end{minted} % \end{VerbatimOut} -% \inputminted{latex}{minted.doc.out} +% \inputminted[frame=single, rulecolor=minted@linkcolor]{latex}{minted.doc.out} % \hfill % \colorbox{minted@samplebg}{\begin{minipage}{0.6\textwidth} % \input{minted.doc.out} @@ -830,11 +845,11 @@ % 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)} +% \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})} +% \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 spaces, 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. @@ -915,9 +930,10 @@ % % 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. +% \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. @@ -927,11 +943,13 @@ % \end{minted} % \end{example} % -% \item[baselinestretch (+auto+\textbar dimension) (+auto+)] +% \item[baselinestretch (dimension) (\meta{document default})] % Value to use as for baselinestretch inside the listing. % -% \item[breakafter (string) (+\meta{none}+)] -% Break lines after specified characters, not just at spaces, when \texttt{breaklines=true}. 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}). +% \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. % @@ -941,35 +959,40 @@ % \end{minted} % \end{longexample} % -% \item[breakaftergroup] (boolean) (+true+) +% \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}+)] +% \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}+)] +% \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}. +% \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}+)] +% \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}+)] +% \item[breakanywheresymbolpost (string) (\meta{none})] % The symbol inserted post-break for breaks inserted by \texttt{breakanywhere}. % -% \item[breakautoindent (boolean) (+true+)] +% \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}. 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}). +% \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. % @@ -979,30 +1002,30 @@ % \end{minted} % \end{longexample} % -% \item[breakbeforegroup] (boolean) (+true+) +% \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}+)] +% \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}+)] +% \item[breakbeforesymbolpost (string) (\meta{none})] % The symbol inserted post-break for breaks inserted by \texttt{breakbefore}. % -% \item[breakbytoken (boolean) (+false+)] +% \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+)] +% \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) (+0pt+)] +% +% \item[breakindent (dimension) (0pt)] % When a line is broken, indent the continuation lines by this amount. 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[breaklines (boolean) (+false+)] -% Automatically break long lines in \texttt{minted} environments and \texttt{\string\mint} commands, and wrap longer lines in \texttt{\string\mintinline}. % -% \textbf{This is not compatible with the option \texttt{obeytabs}.} Additional information about the incompatibility is on \href{https://github.com/gpoore/minted/issues/99}{GitHub}. +% \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}, and \texttt{breakafter} for more fine-tuned breaking. 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.) +% 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. @@ -1040,12 +1063,12 @@ %\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}. You may be able to change the definition of \texttt{\string\FV@Space} if you need this; see the \pkg{fancyvrb} implementation for details. +% Automatic line breaks will not work with \texttt{showspaces=true} unless you use \texttt{breakanywhere} or \texttt{breakafter=\string\space}. % -% \item[breaksymbol (string) (+breaksymbolleft+)] +% \item[breaksymbol (string) (breaksymbolleft)] % Alias for \texttt{breaksymbolleft}. % -% \item[breaksymbolleft (string) (+\string\tiny\string\ensuremath\{\string\hookrightarrow\}+, {\tiny\ensuremath{\hookrightarrow}})] +% \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. @@ -1055,10 +1078,10 @@ % \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) (+breaksymbolindentleft+)] +% \item[breaksymbolindent (dimension) (breaksymbolindentleft)] % Alias for \texttt{breaksymbolindentleft}. % -% \item[breaksymbolindentleft (dimension) (width of 4 characters in teletype font at default point size)] +% \item[breaksymbolindentleft (dimension) (\meta{width of 4 characters in default teletype font})] % The extra left indentation that is provided to make room for \texttt{breaksymbolleft}. This indentation is only applied when there is a \texttt{breaksymbolleft}. % % This may be set to the width of a specific number of (fixed-width) characters by using an approach such as @@ -1070,16 +1093,16 @@ % % Does not apply to \texttt{\string\mintinline}. % -% \item[breaksymbolindentright (dimension) (width of 4 characters in teletype font at default point size)] +% \item[breaksymbolindentright (dimension) (\meta{width of 4 characters in default teletype font})] % The extra right indentation that is provided to make room for \texttt{breaksymbolright}. This indentation is only applied when there is a \texttt{breaksymbolright}. % -% \item[breaksymbolsep (dimension) (+breaksymbolsepleft+)] +% \item[breaksymbolsep (dimension) (breaksymbolsepleft)] % Alias for \texttt{breaksymbolsepleft} % -% \item[breaksymbolsepleft (dimension) (+1em+)] +% \item[breaksymbolsepleft (dimension) (1em)] % The separation between the \texttt{breaksymbolleft} and the adjacent code. Does not apply to \texttt{\string\mintinline}. % -% \item[breaksymbolsepright (dimension) (+1em+)] +% \item[breaksymbolsepright (dimension) (1em)] % The separation between the \texttt{breaksymbolright} and the adjacent code. % % \item[bgcolor (string) (\meta{none})] @@ -1124,15 +1147,21 @@ %\end{Verbatim} % \pkg{tcolorbox} provides other commands and environments for fine-tuning listing appearance and for working with external code files. % -% \item[codetagify (list of strings) (highlight +XXX+, +TODO+, +BUG+, and +NOTE+)] +% \item[codetagify (list of strings) (\textrm{highlight \texttt{XXX}, \texttt{TODO}, \texttt{BUG}, and \texttt{NOTE}})] % Highlight special code tags in comments and docstrings. -% \item[encoding (string) (system-specific)] -% Sets the file encoding that \app{Pygments} expects. See also +outencoding+. +% +% \item[curlyquotes (boolean) (false)] +% By default, the backtick \texttt{\textasciigrave} and typewriter single quotation mark \texttt{\textquotesingle} always appear literally, instead of becoming the left and right curly single quotation marks \texttt{`'}. This option allows these characters to be replaced by the curly quotation marks when that is desirable. +% +% \item[encoding (string) (\meta{system-specific})] +% Sets the file encoding that \app{Pygments} expects. See also |outencoding|. % \item[escapeinside (string) (\meta{none})] -% Escape to \LaTeX\ between the two characters specified in \texttt{\string(string\string)}. All code between the two characters will be interpreted as \LaTeX\ and typeset accordingly. This allows for additional formatting. The escape characters need not be identical. Special \LaTeX\ characters must be escaped when they are used as the escape characters (for example, \texttt{escapeinside=\textbackslash\#\textbackslash\%}). Requires \app{Pygments} 2.0\string+. +% Escape to \LaTeX\ between the two characters specified in \texttt{\string(string\string)}. All code between the two characters will be interpreted as \LaTeX\ and typeset accordingly. This allows for additional formatting. The escape characters need not be identical. Special \LaTeX\ characters must be escaped when they are used as the escape characters (for example, \texttt{escapeinside=\textbackslash\#\textbackslash\%}). Requires \app{Pygments} 2.0+. % % \textbf{Escaping does not work inside strings and comments (for comments, there is \texttt{texcomments}). As of Pygments 2.0.2, this means that escaping is ``fragile'' with some lexers.} Due to the way that Pygments implements \texttt{escapeinside}, any ``escaped'' \LaTeX\ code that resembles a string or comment for the current lexer may break \texttt{escapeinside}. There is a \href{https://bitbucket.org/birkenfeld/pygments-main/issue/1118}{Pygments issue} for this case. Additional details and a limited workaround for some scenarios are available on the \href{https://github.com/gpoore/minted/issues/70#issuecomment-111729930}{\pkg{minted} GitHub site}. % +% \begingroup ^^A Need to prevent active "|" from causing problems +% \catcode`\|=11 % \begin{example} % \begin{minted}[escapeinside=||]{py} % def f(x): @@ -1140,50 +1169,61 @@ % return y % \end{minted} % \end{example} +% \endgroup % -% \textbf{Note that when math is used inside escapes, in a few cases ligature handling may need to be modified.} The single-quote character (\texttt{\textquotesingle}) is normally a shortcut for \texttt{\string^\string\prime} in math mode, but this is disabled in verbatim content as a byproduct of ligatures being disabled. For the same reason, any package that relies on active characters in math mode (for example, \pkg{icomma}) will produce errors along the lines of \texttt{TeX capacity exceeded} and \texttt{\string\leavevmode \string\kern \string\z@}. This may be fixed by modifying \texttt{\string\@noligs}, as described at \url{http://tex.stackexchange.com/questions/223876}. \pkg{minted} currently does not attempt to patch \texttt{\string\@noligs} due to the potential for package conflicts. -% \item[firstline (integer) (+1+)] +% \textbf{Note that when math is used inside escapes, any active characters beyond those that are normally active in verbatim can cause problems.} Any package that relies on special active characters in math mode (for example, \pkg{icomma}) will produce errors along the lines of \texttt{TeX capacity exceeded} and \texttt{\string\leavevmode \string\kern \string\z@}. This may be fixed by modifying \texttt{\string\@noligs}, as described at \url{http://tex.stackexchange.com/questions/223876}. +% \item[firstline (integer) (1)] % The first line to be shown. % All lines before that line are ignored and do not appear in the output. -% \item[firstnumber (+auto+\textbar integer) (+auto+ = 1)] +% \item[firstnumber (auto \| last \| integer) (auto = 1)] % Line number of the first line. -% \item[fontfamily (family name) (+tt+)] +% \item[fontfamily (family name) (tt)] % The font family to use. -% +tt+, +courier+ and +helvetica+ are pre-defined. -% \item[fontseries (series name) (+auto+ -- the same as the current font)] +% |tt|, |courier| and |helvetica| are pre-defined. +% \item[fontseries (series name) (auto \textrm{-- the same as the current font})] % The font series to use. -% \item[fontsize (font size) (+auto+ -- the same as the current font)] -% The size of the font to use, as a size command, e.g. +\footnotesize+. -% \item[fontshape (font shape) (+auto+ -- the same as the current font)] +% \item[fontsize (font size) (auto \textrm{-- the same as the current font})] +% The size of the font to use, as a size command, e.g. |\footnotesize|. +% \item[fontshape (font shape) (auto \textrm{-- the same as the current font})] % The font shape to use. % \item[formatcom (command) (\meta{none})] % A format to execute before printing verbatim text. -% \item[frame (+none+\textbar +leftline+\textbar +topline+\textbar +bottomline+\textbar +lines+\textbar +single+) (+none+)] +% \item[frame (none \| leftline \| topline \| bottomline \| lines \| single) (none)] % The type of frame to put around the source code listing. -% \item[framerule (dimension) (+0.4pt+)] +% \item[framerule (dimension) (0.4pt)] % Width of the frame. % \item[framesep (dimension) (\cmd\fboxsep)] % Distance between frame and content. -% \item[funcnamehighlighting (boolean) (+true+)] \appliesto{PHP} -% If +true+, highlights built-in function names. -% \item[gobble (integer) (+0+)] +% \item[funcnamehighlighting (boolean) (true)] \appliesto{PHP} +% If |true|, highlights built-in function names. +% \item[gobble (integer) (0)] % Remove the first $n$ characters from each input line. -% \item[keywordcase] (string) (+'lower'+) -% Changes capitalization of keywords. Takes +'lower'+, +'upper'+, or +'capitalize'+. +% +% \item[highlightcolor (string) (LightCyan)] +% Set the color used for |highlightlines|, using a predefined color name from \pkg{color} or \pkg{xcolor}, or a color defined via |\definecolor|. +% +% +% \item[highlightlines (string) (\meta{none})] +% This highlights a single line or a range of lines based on line numbers. For example, |highlightlines={1, 3-4}|. The line numbers refer to the line numbers that would appear if |linenos=true|, etc. They do not refer to original or actual line numbers before adjustment by |firstnumber|. +% +% The highlighting color can be customized with |highlightcolor|. +% +% +% \item[keywordcase] (string) (lower) +% Changes capitalization of keywords. Takes |lower|, |upper|, or |capitalize|. % \item[label (string) (\emph{empty})] % Add a label to the top, the bottom or both of the frames around the code. % See the \pkg{fancyvrb} documentation for more information and examples. -% \emph{Note:} This does \emph{not} add a +\label+ to the current listing. +% \emph{Note:} This does \emph{not} add a |\label| to the current listing. % To achieve that, use a floating environment (section \ref{sec:float}) instead. -% \item[labelposition (+none+\textbar +topline+\textbar +bottomline+\textbar +all+) (+topline+, +all+ or \emph{none})] -% Position where to print the label (see above; default: +topline+ if one label is defined, +all+ if two are defined, \emph{none} else). +% \item[labelposition (none \| topline \| bottomline \| all) (topline, all, \textrm{or} none)] +% Position where to print the label (see above; default: |topline| if one label is defined, |all| if two are defined, |none| else). % See the \pkg{fancyvrb} documentation for more information. -% \item[lastline (integer) (\emph{last line of input})] +% \item[lastline (integer) (\meta{last line of input})] % The last line to be shown. -% \item[linenos (boolean) (+false+)] +% \item[linenos (boolean) (false)] % Enables line numbers. -% In order to customize the display style of line numbers, you need to redefine the +\theFancyVerbLine+ -% macro: +% In order to customize the display style of line numbers, you need to redefine the |\theFancyVerbLine| macro: % % \begin{example} % \renewcommand{\theFancyVerbLine}{\sffamily @@ -1200,66 +1240,96 @@ % \end{minted} % \end{example} % -% \item[numbers (+left+\textbar+right+) (\emph{none})] -% Essentially the same as +linenos+, except the side on which the numbers appear may be specified. -% \item[mathescape (boolean) (+false+)] +% \item[numberfirstline (boolean) (false)] +% Always number the first line, regardless of |stepnumber|. +% +% +% \item[numbers (left \| right \| both \| none) (none)] +% Essentially the same as |linenos|, except the side on which the numbers appear may be specified. +% \item[mathescape (boolean) (false)] % Enable \LaTeX{} math mode inside comments. % Usage as in package \pkg{listings}. % See the note under \texttt{escapeinside} regarding math and ligatures. -% \item[numberblanklines (boolean) (+true+)] +% \item[numberblanklines (boolean) (true)] % Enables or disables numbering of blank lines. -% \item[numbersep (dimension) (+12pt+)] +% \item[numbersep (dimension) (12pt)] % Gap between numbers and start of line. -% \item[obeytabs (boolean) (+false+)] -% \textbf{\textcolor{red}{Due to the many issues with \pkg{fancyvrb}'s implementation of \texttt{obeytabs}, this option should be avoided if possible.}} +% \item[obeytabs (boolean) (false)] +% Treat tabs as tabs instead of converting them to spaces---that is, expand them to tab stops determined by |tabsize|. \textcolor{DarkRed}{\textbf{While this will correctly expand tabs within leading indentation, usually it will not correctly expand tabs that are preceded by anything other than spaces or other tabs. It should be avoided in those case.}} % -% Treat tabs as tabs instead of converting them to spaces. -% -% \textbf{This is not compatible with the option \texttt{breaklines}.} -% -% \textbf{This will cause errors with tabbed indentation inside multiline comments.} -% -% There is a \href{https://github.com/gpoore/minted/issues/99}{GitHub issue} with additional technical details. -% \item[outencoding (string) (system-specific)] -% Sets the file encoding that \app{Pygments} uses for highlighted output. Overrides any encoding previously set via +encoding+. -% \item[python3 (boolean) (+false+)] \appliesto{PythonConsoleLexer} +% \item[outencoding (string) (\meta{system-specific})] +% Sets the file encoding that \app{Pygments} uses for highlighted output. Overrides any encoding previously set via |encoding|. +% \item[python3 (boolean) (false)] \appliesto{PythonConsoleLexer} % Specifies whether Python 3 highlighting is applied. -% \item[resetmargins (boolean) (+false+)] +% \item[resetmargins (boolean) (false)] % Resets the left margin inside other environments. -% \item[rulecolor (color command) (\emph{black})] +% \item[rulecolor (color command) (black)] % The color of the frame. -% \item[samepage (boolean) (+false+)] +% \item[samepage (boolean) (false)] % Forces the whole listing to appear on the same page, even if it doesn't fit. -% \item[showspaces (boolean) (+false+)] +% \item[showspaces (boolean) (false)] % Enables visible spaces: \verb*/visible spaces/. -% \item[showtabs (boolean) (+false+)] -% Enables visible tabs---only works in combination with +obeytabs+. -% \item[startinline (boolean) (+false+)] \appliesto{PHP} -% Specifies that the code starts in PHP mode, i.e., leading +|, are used indirectly. All code is highlighted with |commandprefix=PYG|, so that it uses |\PYG|. Then |\PYG| is |\let| to |\PYG