From 630a0032b5287429446b8ed9f02af719e9aa563e Mon Sep 17 00:00:00 2001 From: Karl Berry Date: Thu, 9 Jun 2016 22:52:48 +0000 Subject: minted (8jun16) git-svn-id: svn://tug.org/texlive/trunk@41329 c570f23f-e606-0410-a88d-b1316a301751 --- Master/texmf-dist/doc/latex/minted/README | 2 +- Master/texmf-dist/doc/latex/minted/minted.pdf | Bin 675082 -> 715677 bytes Master/texmf-dist/source/latex/minted/minted.dtx | 804 ++++++++++++++++++----- Master/texmf-dist/source/latex/minted/minted.ins | 2 +- Master/texmf-dist/tex/latex/minted/minted.sty | 584 +++++++++++----- Master/texmf-dist/tex/latex/minted/minted1.sty | 2 +- 6 files changed, 1056 insertions(+), 338 deletions(-) (limited to 'Master/texmf-dist') diff --git a/Master/texmf-dist/doc/latex/minted/README b/Master/texmf-dist/doc/latex/minted/README index 9364f4ed335..2aeb42f497d 100644 --- a/Master/texmf-dist/doc/latex/minted/README +++ b/Master/texmf-dist/doc/latex/minted/README @@ -1,4 +1,4 @@ -minted — highlighted source code for LaTeX +minted - highlighted source code for LaTeX minted is a package that facilitates expressive syntax highlighting in LaTeX using the Pygments library. The package also provides options to customize diff --git a/Master/texmf-dist/doc/latex/minted/minted.pdf b/Master/texmf-dist/doc/latex/minted/minted.pdf index 15ed8369a7f..fbc05ca2385 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 e0db8bd3bd5..48c45077068 100644 --- a/Master/texmf-dist/source/latex/minted/minted.dtx +++ b/Master/texmf-dist/source/latex/minted/minted.dtx @@ -1,6 +1,6 @@ % \iffalse meta-comment % -% Copyright (C) 2013-2015 by Geoffrey M. Poore +% Copyright (C) 2013-2016 by Geoffrey M. Poore % Copyright (C) 2010-2011 by Konrad Rudolph % --------------------------------------------------------------------------- % This work may be distributed and/or modified under the @@ -31,7 +31,7 @@ %\NeedsTeXFormat{LaTeX2e} %\ProvidesPackage{minted} %<*package> - [2015/09/09 v2.1 Yet another Pygments shim for LaTeX] + [2016/06/08 v2.2 Yet another Pygments shim for LaTeX] % %<*driver> \documentclass{ltxdoc} @@ -40,7 +40,6 @@ %\DisableCrossrefs %\RecordChanges %\OnlyDescription -\usepackage{fixltx2e} \usepackage[utf8]{inputenc} \usepackage[T1]{fontenc} \usepackage{lmodern} @@ -171,7 +170,7 @@ % % \fi % -% \CheckSum{3283} +% \CheckSum{3835} % % \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 +190,24 @@ % % % +% +% \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 \texttt{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}. @@ -449,6 +466,8 @@ % \item xstring % \item xcolor % \item lineno +% \item framed +% \item shellesc (for luatex 0.87+) % \end{list} % \endgroup % \end{multicols} @@ -715,7 +734,33 @@ % \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 spaces, even under Windows. % -% Note that this directory is relative to the |outputdir|, if an |outputdir| is specified. +% 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 \texttt{XeTeX} engine since it lacks the built-in MD5 capabilities that \texttt{pdfTeX} and \texttt{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)} @@ -777,9 +822,9 @@ % % % \DescribeMacro{outputdir=\meta{directory} (default: \meta{none})} -% The |-output-directory| and |-aux-directory| (MiKTeX) command-line options for \LaTeX\ causes 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| 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. Paths that include spaces are not allowed. +% 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. % % % \DescribeMacro{section} @@ -875,6 +920,8 @@ % \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}). % +% 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' @@ -882,7 +929,7 @@ % \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{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}. @@ -907,6 +954,27 @@ % % \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}). +% +% 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. % @@ -917,7 +985,11 @@ % \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}. 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.) +% 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}. +% +% 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.) % % \begin{example} % ...text. @@ -998,9 +1070,9 @@ % The separation between the \texttt{breaksymbolright} and the adjacent code. % % \item[bgcolor (string) (\meta{none})] -% Background color of the listing. -% Notice that 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: +% 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} @@ -1011,11 +1083,15 @@ % \end{minted} % \end{example} % -% This option puts \texttt{minted} environments and \texttt{\string\mint} commands in a minipage with a colored background. It puts \texttt{\string\mintinline} inside a \texttt{\string\colorbox}. 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. +% 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{This option will prevent \texttt{breaklines} from working with \texttt{\string\mintinline}.} A \texttt{\string\colorbox} cannot break across lines. +% \textbf{Framing alternatives} % -% \textbf{This option will prevent environments from breaking across pages.} If you want support for page breaks and advanced options, you should consider a framing package such as \pkg{framed}, \pkg{mdframed}, or \pkg{tcolorbox}. It is easy to add framing to \pkg{minted} commands and environments using the \pkg{etoolbox} package. For example, using \pkg{mdframed}: +% 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}} @@ -1024,7 +1100,16 @@ %\begin{Verbatim} %\surroundwithmdframed{minted} %\end{Verbatim} -% \pkg{tcolorbox} even provides a built-in framing environment with \pkg{minted} support. +% \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=