From 61c55238595df570c21065d29f9a80930db212a9 Mon Sep 17 00:00:00 2001 From: Karl Berry Date: Tue, 12 Sep 2023 20:14:39 +0000 Subject: minted (12sep23) git-svn-id: svn://tug.org/texlive/trunk@68252 c570f23f-e606-0410-a88d-b1316a301751 --- Master/texmf-dist/source/latex/minted/minted.dtx | 183 +++++++++++++++-------- 1 file changed, 120 insertions(+), 63 deletions(-) (limited to 'Master/texmf-dist/source/latex') diff --git a/Master/texmf-dist/source/latex/minted/minted.dtx b/Master/texmf-dist/source/latex/minted/minted.dtx index 6ff75d90698..b326c9baeeb 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-2022 by Geoffrey M. Poore +% Copyright (C) 2013-2023 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> - [2022/12/12 v2.7 Yet another Pygments shim for LaTeX] + [2023/09/12 v2.8 Yet another Pygments shim for LaTeX] % %<*driver> \documentclass{ltxdoc} @@ -50,6 +50,7 @@ \usepackage{textcomp} \usepackage[cache, langlinenos]{minted} +\usepackage{calc} \usepackage{environ} \usepackage{graphicx} \usepackage{multicol} @@ -208,7 +209,7 @@ % % \fi % -% \CheckSum{2548} +% \CheckSum{2565} % % \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 @@ -229,6 +230,19 @@ % % % +% \begin{changelog}{v2.8}{2023/09/12} +% \item Under non-Windows operating systems, detect executables with \Verb{command -v} rather than \Verb{which} to provide better cross-platform support (\#345). +% \item Added new package option \Verb{inputlanglinenos}. This extends the existing \Verb{langlinenos} to cover \Verb{\inputminted} as well (\#361). +% \item Improved and updated Pygments documentation (\#339). +% \item Improved \Verb{\mintinline} documentation to address packages that redefine \Verb{\section} (\#368). +% \item Added support for \texpkg{fvextra} options \texttt{breakafterinrun} and \texttt{breakbeforeinrun} (\#358). In \texpkg{fvextra} version 1.5, \texttt{breakaftergroup} and \texttt{breakbeforegroup} were renamed to \texttt{breakafterinrun} and \texttt{breakbeforeinrun} to avoid naming ambiguity with new options. The old options \texttt{breakaftergroup} and \texttt{breakbeforegroup} are no longer supported. +% \item Added \texttt{DEPENDS.txt} (\#331). +% \item Removed unnecessary dependency on \texpkg{calc} package (\#313). +% \item Added documentation in FAQ about copy and paste limitations (\#302). +% \item Added note on \texttt{text} lexer to documentation (\#274). +% \end{changelog} +% +% % \begin{changelog}{v2.7}{2022/12/12} % \item Reimplemented \texttt{\string\mintinline} to use \texttt{fvextra}'s argument reading and processing macros, and to use \texttt{fvextra}'s \texttt{\string\Verb} internally. \texttt{\string\mintinline} now works with all line breaking options supported by \texttt{fvextra}'s \texttt{\string\Verb}, including \texttt{breakanywhere} (\#329, \#340). It now gives better results when used inside other commands, since it uses \texttt{fvextra}'s retokenization macros. It is now compatible with \texttt{hyperref} for PDF strings such as bookmarks. % \item Reimplemented \texttt{\string\newmintinline} based on new \texttt{\string\mintinline}. @@ -463,9 +477,12 @@ % \noindent\texpkg{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. +% +% \vspace{0.5in} +% \noindent\textbf{Development status:} \pkg{minted} version 3.0 is now under development, thanks to a \href{https://tug.org/tc/devfund/grants.html}{\TeX\ Development Fund grant} from the \href{https://tug.org/}{\TeX\ Users Group}. This will bring a new Python executable that replaces |pygmentize|. The new executable will be compatible with restricted shell escape, so no more |-shell-escape| with associated security vulnerabilities. The new executable will also make it possible to extend \pkg{minted} using Python, not just \LaTeX\ macros. This will bring official support for custom lexers, allow including snippets of external files based on regular expressions, and make possible a number of other improvements and bugfixes. For compatibility purposes, the final version of \pkg{minted} v2.x will be released as the compatibility package \pkg{minted2}. Initial beta versions of minted v3.0 are expected by early 2024. A final minted v3.x release including all planned features is expected before the end of summer 2024. % \end{abstract} % -% \vspace{2in} +% \vspace{0.5in} % % \subsection*{License} % \href{http://www.latex-project.org/lppl.txt}{LaTeX Project Public License (LPPL)} version 1.3. @@ -684,6 +701,8 @@ % Optionally, the environment accepts a number of options in |key=value| notation, which are described % in more detail below. % +% To use \texpkg{minted} with a language that is not supported by Pygments, or simply to disable highlighting, set the language to |text|: |\begin{minted}{text}|. +% % % \DescribeMacro{\mint} % For a single line of source code, you can alternatively use a shorthand notation: @@ -711,7 +730,9 @@ % % The syntax is \cmd\mintinline\oarg{options}\marg{language}\meta{delim}\meta{code}\meta{delim}. The delimiters can be a single repeated character, just like for \cmd{\verb}. They can also be a pair of curly braces, |{}|. Curly braces are required when \cmd{\mintinline} is used in a movable argument, such as in a \cmd{\section}. % -% \cmd{\mintinline} has been carefully crafted so that in most cases it will function correctly when used inside other commands. The main exception is when the code contains the percent \texttt{\%} or hash \texttt{\#} characters, or unmatched curly braces. For example, \cmd{\mintinline} works in \cmd{\footnote} and \cmd{\section}! The code typesetting for \cmd{\mintinline} is based on \texpkg{fvextra}'s \cmd{\Verb}. See the \href{https://github.com/gpoore/fvextra/}{\texpkg{fvextra} documentation on \cmd{\Verb}} for details about functionality and limitations. +% Unlike \cmd{\verb}, \cmd{\mintinline} can usually be used inside other commands. The main exception is when the code contains the percent \texttt{\%} or hash \texttt{\#} characters, or unmatched curly braces. For example, \cmd{\mintinline} typically works in \cmd{\footnote} and \cmd{\section}! Note that some document classes or packages, such as \texpkg{memoir}, redefine \cmd{\section} or have options that modify it in ways that are incompatible with \cmd{\mintinline}. If you use \cmd{\mintinline} inside \cmd{\section} or otherwise in a movable argument, you should experiment to make sure it is compatible with your document configuration. You may also want to consider \texpkg{fvextra}'s \cmd{\Verb} or \cmd{\EscVerb} as an alternative. +% +% The code typesetting for \cmd{\mintinline} is based on \texpkg{fvextra}'s \cmd{\Verb}. See the \href{https://github.com/gpoore/fvextra/}{\texpkg{fvextra} documentation on \cmd{\Verb}} for additional details about functionality and limitations. % % \DescribeMacro{\inputminted} % Finally, there's the |\inputminted| command to read and format whole files. @@ -729,7 +750,7 @@ % % 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: +% Highlighting styles with examples can be viewed online at \href{https://pygments.org/styles/}{pygments.org/styles}. It is possible to preview your code with different styles using the online demo at \href{http://pygments.org/demo/}{pygments.org/demo}. Available styles can also be listed by executing the following command on the command line: % % \begin{Verbatim}[gobble=3,commandchars=\\\{\}] % \$ pygmentize -L styles @@ -742,7 +763,7 @@ % % \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 +% \app{Pygments} supports hundreds of 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 @@ -889,6 +910,12 @@ % 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{inputlanglinenos=\meta{boolean} (default:~false)} +% This enables |langlinenos| and causes it to apply to |\inputminted| (and custom commands based on it) in addition to |minted| environments and |\mint| commands (and custom environments/commands based on them). +% +% The regular |langlinenos| option treats all code within a document's |.tex| files as having one set of line numbering per language, and then treats each inputted source file as having its own separate numbering. |inputlanglinenos| defines a single numbering per language, regardless of where code originates. +% +% % \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 \texpkg{minted} to work with such configurations. % @@ -898,6 +925,8 @@ % % % \DescribeMacro{langlinenos=\meta{boolean} (default:~false)} +% This allows all |minted| environments and |\mint| commands (and custom environments/commands based on them) for a given language to share line numbering when |firstnumber=last|, so that each subsequent command/environment has line numbering that continues from the previous one. This does not apply to |\inputminted| (and custom commands based on it); see the package option |inputlanglinenos| for that. +% % \texpkg{minted} uses the \texpkg{fancyvrb} package behind the scenes for the code typesetting. \texpkg{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} @@ -1033,12 +1062,55 @@ % Give the |<| and |>| characters their normal text meanings when used with |escapeinside| and |texcomments|, so that \texpkg{beamer} overlays of the form |\only<1>{...}| will work. % % +% \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 \texpkg{framed} package, which supports breaks across pages. (Prior to \texpkg{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 \texpkg{mdframed} or \texpkg{tcolorbox}. It is easy to add framing to \texpkg{minted} commands and environments using the \texpkg{etoolbox} package, which is automatically loaded by \texpkg{minted}. For example, using \texpkg{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, \texpkg{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} +% \texpkg{tcolorbox} even provides a built-in framing environment with \texpkg{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=