summaryrefslogtreecommitdiff
path: root/macros/latex/contrib/fvextra/fvextra.dtx
diff options
context:
space:
mode:
Diffstat (limited to 'macros/latex/contrib/fvextra/fvextra.dtx')
-rw-r--r--macros/latex/contrib/fvextra/fvextra.dtx919
1 files changed, 651 insertions, 268 deletions
diff --git a/macros/latex/contrib/fvextra/fvextra.dtx b/macros/latex/contrib/fvextra/fvextra.dtx
index ca5877ee0f..ae05d4e6a9 100644
--- a/macros/latex/contrib/fvextra/fvextra.dtx
+++ b/macros/latex/contrib/fvextra/fvextra.dtx
@@ -1,6 +1,6 @@
% \iffalse meta-comment
%
-% Copyright (C) 2016-2023 by Geoffrey M. Poore <gpoore@gmail.com>
+% Copyright (C) 2016-2024 by Geoffrey M. Poore <gpoore@gmail.com>
% ---------------------------------------------------------------------------
% This work may be distributed and/or modified under the
% conditions of the LaTeX Project Public License, either version 1.3
@@ -26,7 +26,7 @@
%<package>\NeedsTeXFormat{LaTeX2e}[1999/12/01]
%<package>\ProvidesPackage{fvextra}
%<*package>
- [2023/11/28 v1.6.1 fvextra - extensions and patches for fancyvrb]
+ [2024/09/14 v1.8.0 fvextra - extensions and patches for fancyvrb]
%</package>
%
%<*driver>
@@ -66,23 +66,7 @@
\usepackage{tcolorbox}
\tcbuselibrary{listings}
-% strip leading percent symbols
-\def\tcbverbatimwrite#1{%
- \@bsphack
- \tcb@set@verbatim@finish%
- \tcb@allocate@tcb@out%
- \immediate\openout\tcb@out #1
- \tcb@verbatim@begin@hook%
- \let\do\@makeother\dospecials
- \tcb@verbatim@change@percent\catcode`\^^M\active \catcode`\^^I=12
- \def\verbatim@processline{%
- \immediate\write\tcb@out
- {\expandafter\@gobble\the\verbatim@line}}%
- \verbatim@start}%
-
-% fix redefinition by tcolorbox
-\def\verbatim@processline{%
- \expandafter\check@percent\the\verbatim@line\par}
+\tcbset{verbatim ignore percent}
\usepackage{hyperref}
@@ -127,6 +111,10 @@
\AtBeginDocument{\let|\pipe@active@verbatim}
\endgroup
+\renewenvironment{verbatim}%
+ {\VerbatimEnvironment\begin{Verbatim}[gobble=1]}%
+ {\end{Verbatim}}
+
\newcommand{\todo}[1]{}
%\newcommand{\todo}[1]{\textcolor{red}{TO~DO: \scantokens{#1}}}
@@ -150,6 +138,48 @@
\def\theCodelineNo{\textcolor{DarkGreen}{\sffamily\scriptsize{\arabic{CodelineNo}}}}
+\renewenvironment{macro}{\macro@custom@arg}{}
+\def\macro@custom@arg{%
+ \begingroup\makeatletter\macro@custom@arg@i}
+\def\macro@custom@arg@i#1{%
+ \makeatother
+ \par\noindent
+ \ifstrempty{#1}%
+ {~\par}%
+ {\ttfamily\color{DarkGreen}\hspace*{-0.5in}%
+ \macro@custom@arg@split#1,\FV@Sentinel\par}%
+ \endgroup}
+\def\macro@custom@arg@spacegobble#1{#1}
+\def\macro@custom@arg@split#1,#2\FV@Sentinel{%
+ \expandafter\string\macro@custom@arg@spacegobble#1%
+ \if\relax\detokenize{#2}\relax
+ \expandafter\@firstoftwo
+ \else
+ \expandafter\@secondoftwo
+ \fi
+ {}{\\\hspace*{-0.5in}\macro@custom@arg@split#2\FV@Sentinel}}
+
+\renewenvironment{environment}{\env@custom@arg}{}
+\def\env@custom@arg{%
+ \begingroup\makeatletter\env@custom@arg@i}
+\def\env@custom@arg@i#1{%
+ \makeatother
+ \ifstrempty{#1}%
+ {~\par}%
+ {\ttfamily\color{DarkGreen}\hspace*{-0.5in}%
+ \env@custom@arg@split#1,\FV@Sentinel\par}%
+ \endgroup}
+\def\env@custom@arg@spacegobble#1{#1}
+\def\env@custom@arg@split#1,#2\FV@Sentinel{%
+ \env@custom@arg@spacegobble#1{\textrm{ \textit{(env.)}}}%
+ \if\relax\detokenize{#2}\relax
+ \expandafter\@firstoftwo
+ \else
+ \expandafter\@secondoftwo
+ \fi
+ {}{\\\hspace*{-0.5in}\env@custom@arg@split#2\FV@Sentinel}}
+
+
\let\orig@footnote\footnote
\renewcommand{\footnote}{%
\begingroup
@@ -163,25 +193,28 @@
\orig@footnote{\scantokens{#1}}}
-\def\fvextraprintopt#1(#2) (#3){%
+\def\fvextra@optionlist@printopt#1(#2) (#3){%
\vspace{0.1in}%
\leavevmode%
- \marginpar{\raggedleft\texttt{\small\textcolor{DarkGreen}{#1}}\ }%
+ \marginpar{\raggedleft\texttt{\textcolor{DarkGreen}{\small #1}}\ }%
\kern-\parindent\textsf{(#2)}\hfill(default: \texttt{#3})\\}
\newenvironment{optionlist}%
- {%
- ~\par\vspace{-14pt}%
+ {~\par\vspace{-14pt}%
\def\pipechar{|}
\let\|\pipechar
- \newcommand*\fvextranext{}%
+ \newcommand*\fvextra@optionlist@next{}%
+ \let\item@orig\item
\renewcommand*\item[1][]{%
- \fvextranext%
- \renewcommand*\fvextranext{\par}%
- \fvextraprintopt##1%
- \ignorespaces}}
- {%
- \par}
+ \ifdefstring{\@currenvir}{optionlist}%
+ {\fvextra@optionlist@next%
+ \renewcommand*\fvextra@optionlist@next{\par}%
+ \fvextra@optionlist@printopt##1%
+ \ignorespaces}%
+ {\ifstrempty{##1}%
+ {\vspace{-4pt}\item@orig}
+ {\vspace{-4pt}\item@orig[##1]}}}}
+ {\par}
\newenvironment{example}
@@ -223,22 +256,6 @@
\edef\hashchar{\string#}
-\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}{Changelog}
- %\section*{Changelog}%
- \section{Changelog}%
- \label{sec:changelog}
- \begin{description}%
- \changestext
- \end{description}%
-}
-
%\EnableCrossrefs
%\CodelineIndex
%\RecordChanges
@@ -253,89 +270,6 @@
% \fi
%
%
-% \begin{changelog}{v1.6.1}{2023/11/28}
-% \item Fixed bug from v1.6 that caused a space following a comma to be lost (\#21).
-% \end{changelog}
-%
-% \begin{changelog}{v1.6}{2023/11/19}
-% \item Added new environment \Verb{VerbatimWrite}. This is similar to \Verb{fancyvrb}'s \Verb{VerbatimOut}, except that it allows for writing to a file multiple times and guarantees truly verbatim output via \Verb{\detokenize}.
-% \item Added new environment \Verb{VerbatimBuffer}. This stores the contents of an environment verbatim in a ``buffer,'' a sequence of numbered macros each of which contains one line of the environment. The ``buffered'' lines can then be looped over for further processing or later use.
-% \item Added new command \Verb{\VerbatimInsertBuffer}. This inserts an existing buffer created by \Verb{VerbatimBuffer} as a \Verb{Verbatim} environment.
-% \item Redefined visible space \Verb{\FancyVerbSpace} so that it now has the correct width. It had previously been redefined as \Verb{\textvisiblespace}, but that was slightly too narrrow.
-% \item Added option \Verb{spacebreak}. This determines the line break that is inserted around spaces when \Verb{showspaces=true} or \Verb{breakcollapsespaces=false}, by defining the new macro \Verb{\FancyVerbSpaceBreak}.
-% \item \Verb{breakbefore}, \Verb{breakafter}, and \Verb{breakanywhere} now produce plain breaks around spaces when \Verb{showspaces=true}, instead of breaks with a break symbol at the end of wrapped lines. \Verb{\FancyVerbBreakAnywhereBreak}, \Verb{\FancyVerbBreakBeforeBreak}, and \Verb{\FancyVerbBreakAfterBreak} are no longer inserted next to spaces. Instead, \Verb{\FancyVerbSpaceBreak} is inserted or (depending on options) \Verb{\FV@Space} is defined to include \Verb{\FancyVerbSpaceBreak}.
-% \item Added option \Verb{breakcollapsespaces}. When \Verb{true} (default), a line break within a run of regular spaces (\Verb{showspaces=false}) replaces all spaces with a single break, and the wrapped line after the break starts with a non-space character. When \Verb{false}, a line break within a run of regular spaces preserves all spaces, and the wrapped line after the break may start with one or more spaces. This causes regular spaces to behave exactly like the visible spaces produced with \Verb{showspaces}; both give identical line breaks, with the only difference being the appearance of spaces.
-% \item \Verb{breaklines} now automatically enables breaks after space characters when \Verb{showspaces=true}.
-% \item Reimplemented definition of \Verb{\FV@Space} to work with new space options.
-% \item Added documentation about how reimplemented commands handle the \Verb{codes} option differently compared to \fancyvrb\ (\#17).
-% \item Starred commands such as \Verb{\Verb*} now use both visible spaces and visible tabs instead of just visible spaces. This is more similar to the current behavior of \Verb{\verb*}, except that \Verb{\verb*} converts tabs into visible spaces (\#19).
-% \item The \Verb{mathescape} option now resets the ampersand \Verb{&} catcode (\#18).
-% \end{changelog}
-%
-%
-% \begin{changelog}{v1.5}{2022/11/30}
-% \item Added \cmd{\FancyVerbFormatInline} for customizing the formatting of inline verbatim, such as \cmd{\Verb}. This parallels \cmd{\FancyVerbFormatLine} and \cmd{\FancyVerbFormatText}.
-% \item Added line breaking option \Verb{breaknonspaceingroup}. When \cmd{commandchars} is used to allow macros within verbatim, this inserts breaks within groups \Verb{{...}}.
-% \item Added \cmd{\FVExtraUnexpandedReadStarOArgMArgBVArg} to support reimplementation of \cmd{\mintinline} for \pkg{minted}.
-% \item Added \cmd{VerbEnv} environment, which is an environment variant of \cmd{\Verb}. This supports reimplementation of \cmd{\mintinline} for \pkg{minted}.
-% \item \cmd{breakbefore} and \cmd{breakafter} now support the escaped comma \cmd{\,} (\#15).
-% \item Fixed unintended line breaks after hyphens under LuaTeX (\#14).
-% \item Added documentation on Pandoc compatibility (\#11).
-% \item Replaced \Verb{breakbeforegroup} with \Verb{breakbeforeinrun}, and replaced \Verb{breakaftergroup} with \Verb{breakafterinrun}. With the introduction of \Verb{breaknonspaceingroup}, ``\Verb{group}'' is now reserved for referring to TeX groups \Verb{{...}}.
-% \item Removed dependency on \Verb{ifthen} package.
-% \item \Verb{breakautoindent} now works correctly with Pygments output that treats leading whitespace as a separate token or as part of a token.
-% \end{changelog}
-%
-% \begin{changelog}{v1.4}{2019/02/04}
-% \item Reimplemented \texttt{\string\Verb}. It now works as expected inside other commands (with a few limitations), including in movable arguments, and is compatible with \texttt{hyperref} for things like PDF bookmarks. It now supports \texttt{breaklines} and relevant line-breaking options.
-% \item Reimplemented \texttt{\string\SaveVerb} and \texttt{\string\UseVerb} to be equivalent to the new \texttt{\string\Verb}. The new option \texttt{retokenize} allows saved verbatim material to be retokenized under new \texttt{commandchars} and \texttt{codes} when it is inserted with \texttt{\string\UseVerb}.
-% \item New command \texttt{\string\EscVerb} works like the reimplemented \texttt{\string\Verb}, except that special characters can be escaped with a backslash. It works inside other commands without any limitations, including in movable arguments, and is compatible with \texttt{hyperref} for things like PDF bookmarks.
-% \item Added \texttt{extra} option for switching between the reimplemented \texttt{\string\Verb}, \texttt{\string\SaveVerb}, \texttt{\string\UseVerb} and the original \texttt{fancyvrb} definitions. Reimplemented versions are used by default. This option will apply to any future reimplemented commands and environments.
-% \item New command \texttt{\string\fvinlineset} only applies options to commands related to typesetting verbatim inline, like \texttt{\string\Verb}, \texttt{\string\SaveVerb}, \texttt{\string\UseVerb}. It only works with commands that are defined or reimplemented by \texttt{fvextra}. It overrides options from \texttt{\string\fvset}.
-% \item Patched \texttt{fancyvrb} so that \texttt{\string\Verb} (either reimplemented version or original) can use characters like \texttt{\%} for delimiters when used outside any commands.
-% \item \texttt{obeytabs} now works with the \texttt{calc} package's redefined \texttt{\string\setcounter}. Since \texttt{minted} loads \texttt{calc}, this also fixes \texttt{minted} compatibility (\texttt{minted} \#221).
-% \item Added new option \texttt{fontencoding} (\texttt{minted} \#208).
-% \item \texttt{highlightlines} now works correctly with \texttt{frame} (\#7).
-% \end{changelog}
-%
-% \begin{changelog}{v1.3.1}{2017/07/08}
-% \item \texttt{beameroverlays} now works with \texttt{VerbatimOut}.
-% \end{changelog}
-%
-% \begin{changelog}{v1.3}{2017/07/08}
-% \item Added \texttt{beameroverlays} option, which enables \texttt{beamer} overlays using the \texttt{<} and \texttt{>} characters.
-% \item Added options \texttt{breakindentnchars}, \texttt{breaksymbolsepleftnchars} (alias \texttt{breaksymbolsepnchars}), \texttt{breaksymbolseprightnchars}, \texttt{breaksymbolindentleftnchars} (alias \texttt{breaksymbolindentnchars}), and \texttt{breaksymbolindentrightnchars}. These are identical to the pre-existing options without the \texttt{nchars} suffix, except that they allow indentation to be specified as an integer number of characters rather than as a dimension. As a result of these new options, \texttt{\string\settowidth} is no longer used in the preamble, resolving some font incompatibilities (\#4).
-% \item Clarified in the docs that \texttt{breaksymbolsepright} is a \emph{minimum}, rather than exact, distance.
-% \end{changelog}
-%
-%
-% \begin{changelog}{v1.2.1}{2016/09/02}
-% \item The package is now compatible with classes and packages that redefine \texttt{\string\raggedright}.
-% \item Fixed a bug that introduced extra space in inline contexts such as \texttt{\string\mintinline} when \texttt{breaklines=true} (\#3).
-% \end{changelog}
-%
-%
-% \begin{changelog}{v1.2}{2016/07/20}
-% \item Added support for line breaking when working with Pygments for syntax highlighting.
-% \item The default \texttt{highlightcolor} is now defined with \texttt{rgb} for compatibility with the \texttt{color} package. Fixed a bug in the conditional color definition when \texttt{color} and \texttt{xcolor} are not loaded before \texttt{fvextra}.
-% \end{changelog}
-%
-%
-% \begin{changelog}{v1.1}{2016/07/14}
-% \item The options \texttt{rulecolor} and \texttt{fillcolor} now accept color names directly; using \texttt{\string\color\{<color\_name>\}} is no longer necessary, though it still works.
-% \item Added \texttt{tabcolor} and \texttt{spacecolor} options for use with \texttt{showtabs} and \texttt{showspaces}.
-% \item Added \texttt{highlightlines} option that takes a line number or range of line numbers and highlights the corresponding lines. Added \texttt{highlightcolor} option that controls hightlighting color.
-% \item \texttt{obeytabs} no longer causes lines to vanish when tabs are inside macro arguments. Tabs and spaces inside a macro argument but otherwise at the beginning of a line are expanded correctly. Tabs inside a macro argument that are preceded by non-whitespace characters (not spaces or tabs) are expanded based on the starting position of the run of whitespace in which they occur.
-% \item The line breaking options \texttt{breakanywhere}, \texttt{breakbefore}, and \texttt{breakafter} now work with multi-byte UTF-8 code points under pdfTeX with \texttt{inputenc}. They were already fully functional under XeTeX and LuaTeX.
-% \item Added \texttt{curlyquotes} option, which essentially disables the \texttt{uquote} package.
-% \end{changelog}
-%
-%
-% \begin{changelog}{v1.0}{2016/06/28}
-% \item Initial release.
-% \end{changelog}
-%
-%
% \DoNotIndex{\newcommand,\newenvironment}
% \DoNotIndex{\#,\$,\%,\&,\@,\\,\{,\},\^,\_,\~,\ }
% \DoNotIndex{\@ne}
@@ -405,7 +339,7 @@
%\hrule
%\vspace{2ex}
%\noindent\begin{minipage}{\linewidth}
-%\begin{Verbatim}[gobble=1]
+%\begin{verbatim}
%---
%header-includes:
% - |
@@ -416,7 +350,7 @@
% breaklines, breaknonspaceingroup, breakanywhere}
% ```
%---
-%\end{Verbatim}
+%\end{verbatim}
%\end{minipage}
%\vspace{2ex}
%\hrule
@@ -432,6 +366,50 @@
%
% \begin{optionlist}
%
+% \item[backgroundcolor (string) (none)]
+% Background color behind commands and environments. This is only a basic, lightweight implementation of background colors using |\colorbox|. For more control of background colors, consider \href{https://ctan.org/pkg/tcolorbox}{\pkg{tcolorbox}} or a similar package, or a custom background color implementation.
+%
+% Background colors are implemented with |\colorbox|, which prevents line breaking for |\Verb|, |\UseVerb|, and |\EscVerb|. Background colors are only compatible with \fvextra's reimplemented |\Verb| and |\UseVerb| (|extra=true|).
+%
+% See |backgroundcolorvphantom| to customize the height of the background for each line of text, especially for |\Verb|, |\EscVerb|, and |BVerbatim|.
+%
+% When |backgroundcolor| is used with |Verbatim| with a |frame|, it may be necessary to adjust |framesep| and |fillcolor| depending on the desired result. |backgroundcolorpadding| provides a shortcut for this.
+%
+%
+% \item[backgroundcolorpadding (length) (none)]
+% Padding when |backgroundcolor| is set. For |\Verb|, |\UseVerb|, |\EscVerb|, and |BVerbatim|, this sets |\fboxsep| for the |\colorbox| that is used to create the background color. For |Verbatim|, \fancyvrb's frame options are used instead, particularly |framesep| and |fillcolor|.
+%
+% For |Verbatim|, this amounts to a shortcut for a combination of frame-related settings that provide padding when there is a background color. This is only intended for cases with |frame=none| or |frame=single|. In other cases, it may be better to modify the \fancyvrb\ frame settings directly, and it may be necessary to modify the \fancyvrb\ internals to obtain padding on all sides.
+%
+% For |Verbatim|, if |frame=single|, then this is equivalent to the following settings:
+% \begin{itemize}
+% \item |framesep=|\meta{\texttt{backgroundcolorpadding}}
+% \item |fillcolor=\FancyVerbBackgroundColor|
+% \end{itemize}
+%
+% For |Verbatim|, if |frame| has any value other than |single|, then this is equivalent to the following settings:
+% \begin{itemize}
+% \item |frame=single|
+% \item |framerule=0pt|
+% \item |rulecolor=\FancyVerbBackgroundColor|
+% \item |framesep=|\meta{\texttt{backgroundcolorpadding}}
+% \item |fillcolor=\FancyVerbBackgroundColor|
+% \end{itemize}
+%
+%
+% \item[backgroundcolorvphantom (macro) (\Verb{\vphantom{\"Apgjy}})]
+% |\vphantom| or similar macro such as |\strut| that is inserted at the beginning of each line of text using |backgroundcolor|. This allows the height of the background for each line of text to be customized, especially for |\Verb|, |\EscVerb|, and |BVerbatim|. |backgroundcolorvphantom| will typically have no effect on |Verbatim|-based environments unless it is set to a size larger than |\strut|.
+%
+% \item[bgcolor (string) (none)]
+% Alias for |backgroundcolor|.
+%
+% \item[bgcolorpadding (length) (none)]
+% Alias for |backgroundcolorpadding|.
+%
+% \item[bgcolorvphantom (macro) (\Verb{\vphantom{\"Apgjy}})]
+% Alias for |backgroundcolorvphantom|.
+%
+%
% \item[beameroverlays (boolean) (false)]
% Give the |<| and |>| characters their normal text meanings, so that \pkg{beamer} overlays of the form |\only<1>{...}| will work. Note that something like |commandchars=\\\{\}| is required separately to enable macros. This is not incorporated in the |beameroverlays| option because essentially arbitrary command characters could be used; only the |<| and |>| characters are hard-coded for overlays.
%
@@ -637,6 +615,10 @@
% Set the color of visible tabs. By default (|none|), they take the color of their surroundings.
%
%
+% \item[vargsingleline (boolean) (false)]
+% This determines whether \fvextra's |\Verb| and |\SaveVerb| take multi-line (but not multi-paragraph) verbatim arguments, or if they instead require arguments to be on a single line like the original \fancyvrb\ commands.
+%
+%
% \end{optionlist}
%
%
@@ -700,6 +682,8 @@
%
% The new \cmd{\Verb} works as expected (with a few limitations) inside other commands. It even works in movable arguments (for example, in \cmd{\section}), and is compatible with \pkg{hyperref} for generating PDF strings (for example, PDF bookmarks). The \fancyvrb\ definition did work inside some other commands, but essentially functioned as \cmd{\texttt} in that context.
%
+% By default, \cmd{\Verb} takes a multi-line (but not multi-paragraph) verbatim argument. To restore the \fancyvrb\ behavior of requiring a single-line argument, set |vargsingleline=true|.
+%
% \cmd{\Verb} is compatible with |breaklines| and the relevant line-breaking options.
%
% Like the original \fancyvrb\ implementation, the new \cmd{\Verb} can be starred (|\Verb*|) and accepts optional arguments. While \fancyvrb's starred command |\Verb*| is a shortcut for |showspaces|, \fvextra's |\Verb*| is a shortcut for both |showspaces| and |showtabs|. This is more similar to the current behavior of \LaTeX's \Verb{\verb*}, except that \Verb{\verb*} converts tabs into visible spaces instead of displaying them as visible tabs.
@@ -726,6 +710,8 @@
%
% \cmd{\SaveVerb} is reimplemented so that it is equivalent to the reimplemented \cmd{\Verb}. Like the new \cmd{\Verb}, it accepts \meta{text} delimited by a pair of curly braces |{...}|. It supports \cmd{\fvinlineset}. It also adds support for the new |retokenize| option for \cmd{\UseVerb}.
%
+% By default, \cmd{\SaveVerb} takes a multi-line (but not multi-paragraph) verbatim argument. To restore the \fancyvrb\ behavior of requiring a single-line argument, set |vargsingleline=true|.
+%
%
% \subsection{\cmd{\UseVerb}}
%
@@ -918,23 +904,37 @@
% Shortcut for setting |bufferlengthname| and |bufferlinename| simultaneously, using the same root name. This sets |bufferlengthname| to |<buffername>length| and |bufferlinename| to |<buffername>line|.
%
% \item[globalbuffer (bool) (false)]
-% This determines whether buffer line macros are defined globally, that is, whether they are accessible after the end of the |VerbatimBuffer| environment. It does not affect any |afterbuffer| macro, since that is invoked inside the environment. |globalbuffer| also determines whether the buffer length counter contains the buffer length or is reset to zero after the end of the |VerbatimBuffer| environment.
+% This determines whether buffer line macros are defined globally, that is, whether they are accessible after the end of the |VerbatimBuffer| environment. If the line macros are defined globally, then the buffer length counter is also increased appropriately outside the environment. |globalbuffer| does not affect any |afterbuffer| macro, since that is invoked inside the environment.
%
% When buffered lines are used immediately, consider using |afterbuffer| instead of |globalbuffer|. When buffered lines must be used later in a document, consider using |globalbuffer| with custom (and perhaps unique) |bufferlinename| and |bufferlengthname|.
%
-% When |globalbuffer=false|, at the end of the environment all buffer line macros based on the current |bufferlinename| are ``deleted'' (|\let| to an undefined macro), and the buffer length counter from |bufferlengthname| is set to zero. This means that a |VerbatimBuffer| environment with |globalbuffer=false| will clear the buffer created by any previous |VerbatimBuffer| that had |globalbuffer=true| and shared the same |bufferlinename|.
+% When |globalbuffer=true|, |VerbatimBuffer| environments with the same buffer name will append to a single buffer, so that it ultimately contains the concatenated contents of all environments. A |VerbatimBuffer| environment with |globalbuffer=false| will append to the buffer created by any previous |VerbatimBuffer| that had |globalbuffer=true| and shared the same buffer name. Any |afterbuffer| macro will have access to a buffer containing the concatenated data. At the very end of the environment with |globalbuffer=false|, after any |afterbuffer|, this appended content will be removed. All buffer line macros (from |bufferlinename|) that were created by that environment are ``deleted'' (|\let| to an undefined macro), and the buffer length counter (from |bufferlengthname|) is reduced proportionally.
% \end{optionlist}
%
%
% \subsection{\cmd{\VerbatimInsertBuffer}}
% \DescribeMacro{\VerbatimInsertBuffer\oarg{options}}
%
-% This inserts an existing buffer created by |VerbatimBuffer| as a |Verbatim| environment. It customizes |Verbatim| internals to function with a buffer in a command context. See the |VerbatimBuffer| documentation for an example of usage.
+% This inserts an existing buffer created by |VerbatimBuffer| as a verbatim environment. The |Verbatim| environment is used by default, but this can be customized by setting |insertenvname|. |\VerbatimInsertBuffer| modifies |Verbatim| and |BVerbatim| internals to function with a buffer in a command context. See the |VerbatimBuffer| documentation for an example of usage.
%
% Options related to catcodes cause the buffer to be retokenized during typesetting. That is, the \fancyvrb\ options used for |\VerbatimInsertBuffer| are not restricted by those that were in effect when |VerbatimBuffer| originally created the buffer, so long as the buffer contains a complete representation of the original |VerbatimBuffer| environment contents.
%
% |\VerbatimInsertBuffer| is not implemented using the typical \fancyvrb\ command and environment implementation styles, so it is not compatible with |\RecustomVerbatimCommand| or |\RecustomVerbatimEnvironment|.
%
+% ~\par
+% \noindent Options defined specifically for \cmd{\VerbatimInsertBuffer}:
+%
+% \begin{optionlist}
+% \item[insertenvname (string) (Verbatim)]
+% This is the name of the verbatim environment used for inserting the buffer. |insertenvname| can be any |Verbatim|- or |BVerbatim|-based environment. Environments defined with |\CustomVerbatimEnvironment| and |\RecustomVerbatimEnvironment| are supported. User-implemented environments that serve as wrappers around |Verbatim| or |BVerbatim| should typically be compatible so long as they accept \pkg{fancyvrb}/\pkg{fvextra} optional arguments in the same way as |Verbatim| and |BVerbatim|.
+% \end{optionlist}
+%
+%
+% \subsection{\cmd{\VerbatimClearBuffer}}
+% \DescribeMacro{\VerbatimClearBuffer\oarg{options}}
+%
+% Clear an existing buffer created with \cmd{VerbatimBuffer}. |\global\let| all buffer line macros to an undefined macro and set the buffer length counter to zero.
+%
%
%
%
@@ -994,6 +994,17 @@
% The symbol inserted pre-break for breaks inserted by |breakanywhere|. This does not apply to breaks inserted next to spaces; see |spacebreak|.
%
%
+% \item[breakanywhereinlinestretch (length) (\meta{none})]
+% Stretch glue to insert at potential |breakanywhere| break locations in inline contexts, to give better line widths and avoid overfull |\hbox|. This allows the spacing between adjacent non-space characters to stretch, so it should not be used when column alignment is important. For typical line lengths, values between |0.01em| and |0.02em| should be sufficient to provide a cumulative stretch per line that is equal to or greater than the width of one character.
+%
+% This is typically not needed in cases where an overfull |\hbox| only overflows by tiny amount, perhaps a fraction of a pt. In those cases, the overfull |\hbox| could be ignored, |\hfuzz| could be set to 1pt or 2pt to suppress tiny overfull |\hbox| warnings, or |breakanywheresymbolpre| might be redefined to adjust spacing.
+%
+% Implementation: Before each |breakanywhere| break location, this inserts the following sequence of macros:
+%\begin{verbatim}
+%\nobreak\hspace{0pt plus \FV@breaknonspaceinlinestretch}
+%\end{verbatim}
+%
+%
% \item[breakanywheresymbolpost (string) (\meta{none})]
% The symbol inserted post-break for breaks inserted by |breakanywhere|. This does not apply to breaks inserted next to spaces; see |spacebreak|.
%
@@ -1040,7 +1051,11 @@
%
%
% \item[breaklines (boolean) (false)]
-% Automatically break long lines. When a line is broken, the result must fit on a single page. There is no support for breaking a line across multiple pages.\footnote{Following the implementation in \pkg{fancyvrb}, each line is typeset within an |\hbox|, so page breaks are not possible.}
+% Automatically break long lines.
+%
+% \textbf{Limitations for verbatim environments/block text}, such as |Verbatim|: When a line is broken, the result must fit on a single page. There is no support for breaking a line across multiple pages.\footnote{Following the implementation in \pkg{fancyvrb}, each line is typeset within an |\hbox|, so page breaks are not possible.}
+%
+% \textbf{Limitations for verbatim commands/inline text}, such as |\Verb|: When a line break is inserted, the text may still overflow into the margin or cause an overfull |\hbox|, depending on hyphenation settings and various penalties related to line breaks. It may be possible to avoid this by allowing additional break locations with |breakbefore|, |breakafter|, or |breakanywhere|. Small overfull |\hbox| warnings can be suppressed by setting |\hfuzz| to a larger value, for example setting it to |2pt| instead of the default |0.1pt|. It is also possible to combine |breakanywhere| with |breakanywhereinlinestretch| to allow flexible spacing between adjacent non-space characters. In cases where it is better to break before the margin rather than overflowing into the margin, consider setting |\emergencystretch|.
%
% By default, automatic breaks occur at spaces (even when |showspaces=true|). Use |breakanywhere| to enable breaking anywhere; use |breakbefore| and |breakafter| for more fine-tuned breaking.
%
@@ -1089,6 +1104,12 @@
% |breaknonspaceingroup| allows non-space breaks to be inserted within groups. This option should only be used when |commandchars| is including \LaTeX\ commands that do not take optional arguments and only take mandatory arguments that are typeset. Something like |\textit{text}| is fine, but |\textcolor{red}{text}| is not because one of the mandatory arguments is not typeset but rather provides a setting. For more complex commands, it is typically better to redefine them to insert breaks in appropriate locations using |\FancyVerbBreakStart...\FancyVerbBreakStop|.
%
%
+% \item[breakpreferspaces (boolean) (true)]
+% This determines whether line breaks are preferentially inserted at normal spaces (|breakcollapsespaces=true|, |showspaces=false|) rather than at other locations allowed by |breakbefore|, |breakafter|, or |breakanywhere|.
+%
+% Using |breakpreferspaces=false| with |breakanywhere=true| will typically result in all broken segments of a line going all the way to the right margin.
+%
+%
% \item[breaksymbol (string) (breaksymbolleft)]
% Alias for |breaksymbolleft|.
%
@@ -1478,6 +1499,9 @@
% \item[formatcom* (macro) (\meta{empty})]
% \fancyvrb's |formatcom| is used to execute commands before verbatim text. It overwrites any existing |formatcom|. |formatcom*| appends changes to existing settings.
%
+% \item[listparameters (macro) (\meta{empty})]
+% Set list-related lengths to modify spacing around lines of code. For example, |listparameters=\setlength{\topsep}{0pt}| will remove space before and after a |Verbatim| environment.
+%
% \end{optionlist}
%
%
@@ -1503,8 +1527,6 @@
%
%
%
-% \PrintChangelog
-%
% \StopEventually{\PrintIndex}
%
% \section{Implementation}
@@ -1617,7 +1639,7 @@
%
% There are two contexts in which sentinels may be needed. In delimited macro arguments, such as |\def\macro#1\sentinel{...}|, a sentinel is needed as the delimiter. Because the delimiting macro need not be defined, special delimiting macros need not be created for this case. The important thing is to ensure that the macro name is sufficiently unique to avoid collisions. Typically, using \cmd{\makeatletter} to allow something like \cmd{\@sentinel} will be sufficient. For added security, additional characters can be given catcode 11, to allow things like \cmd{\@sent!nel}.
%
-% The other context for sentinels is in scanning through a sequence of tokens that is delimited by a sentinel, and using \cmd{\ifx} comparisons to identify the sentinel and stop scanning. In this case, using an undefined macro is risky. Under normal conditions, the sequence of tokens could contain an undefined macro due to mistyping. In some \fvextra\ applications, the tokens will have been incorrectly tokenized under a normal catcode regime, and need to be retokenized as verbatim, in which case undefined macros must be expected. Thus, a sentinel macro whose expansion is resistent to collisions is needed.
+% The other context for sentinels is in scanning through a sequence of tokens that is delimited by a sentinel, and using \cmd{\ifx} comparisons to identify the sentinel and stop scanning. In this case, using an undefined macro is risky. Under normal conditions, the sequence of tokens could contain an undefined macro due to mistyping. In some \fvextra\ applications, the tokens will have been incorrectly tokenized under a normal catcode regime, and need to be retokenized as verbatim, in which case undefined macros must be expected. Thus, a sentinel macro whose expansion is resistant to collisions is needed.
%
% \begin{macro}{\FV@<Sentinel>}
% This is the standard default \fvextra\ delimited-macro sentinel. It is used with \cmd{\makeatletter} by changing |<| and |>| to catcode 11. The |<| and |>| add an extra level of collision resistance. Because it is undefined, it is \emph{only} appropriate for use in delimited macro arguments.
@@ -1931,12 +1953,14 @@
% \end{macro}
%
%
-% \begin{macro}{\FVExtraReadVArg}
-% Read a verbatim argument that is bounded by two identical characters or by paired curly braces. This uses the \cmd{\outer} |^^M| with \cmd{\FV@EOL} trick from \fancyvrb\ to prevent runaway arguments. An \cmd{\outer} |^^C| is used to prevent |^^C| from being part of arguments, so that it can be used later as a sentinel if retokenization is needed. |^^B| is handled in the same manner for symmetry with later usage, though technically it is not used as a sentinel so this is not strictly necessary. Alternate |UTF| macros, defined later, are invoked when under pdfTeX with \pkg{inputenc} using UTF-8.
+% \begin{macro}{\FVExtraReadVArg,\FVExtraReadVArgSingleLine}
+% Read a verbatim argument that is bounded by two identical characters or by paired curly braces. There are two variants: one reads a multi-line (but not multi-paragraph) argument, while the other restricts the argument to a single line via the \cmd{\outer} |^^M| trick from \fancyvrb. An \cmd{\outer} |^^C| is used to prevent |^^C| from being part of arguments, so that it can be used later as a sentinel if retokenization is needed. |^^B| is handled in the same manner for symmetry with later usage, though technically it is not used as a sentinel so this is not strictly necessary. Alternate |UTF| macros, defined later, are invoked when under pdfTeX with \pkg{inputenc} using UTF-8.
%
% The lookahead for the type of delimiting character is done under a verbatim catcode regime, except that the space catcode is preserved and curly braces are given their normal catcodes. This provides consistency with any \cmd{\FVExtra@ifnextcharVArg} or \cmd{\FVExtra@ifstarVArg} that may have been used previously, allows characters like |#| and |%| to be used as delimiters when the verbatim argument is read outside any other commands (untokenized), and allows paired curly braces to serve as delimiters. Any additional command-specific catcode modifications should only be applied to the argument after it has been read, since they do not apply to the delimiters.
%
% Once the delimiter lookahead is complete, catcodes revert to full verbatim, and are then modified appropriately given the type of delimiter. The space and tab must be \cmd{\active} to be preserved correctly when the verbatim argument is not inside any other commands (otherwise, they collapse into single spaces).
+%
+% Note that |\FVExtraReadVArg| will interpret a line break as a catcode 10 space, not as an |\active| space. Depending on usage, the argument may need to be processed with |\FVExtraDetokenizeVArg| and |\FVExtraRetokenizeVArg| to fix this.
% \begin{macrocode}
\def\FVExtraReadVArg#1{%
\begingroup
@@ -1951,6 +1975,34 @@
\FV@OuterDefSTXEmpty
\catcode`\^^C=\active
\FV@OuterDefETXEmpty
+ \begingroup
+ \catcode`\ =\FV@TmpSpaceCat\relax
+ \catcode`\{=1
+ \catcode`\}=2
+ \@ifnextchar\bgroup
+ {\endgroup
+ \catcode`\{=1
+ \catcode`\}=2
+ \catcode`\ =\active
+ \catcode`\^^I=\active
+ \FV@ReadVArg@Group{#1}}%
+ {\endgroup
+ \catcode`\ =\active
+ \catcode`\^^I=\active
+ \FV@ReadVArg@Char{#1}}}
+\def\FVExtraReadVArgSingleLine#1{%
+ \begingroup
+ \ifFV@pdfTeXinputenc
+ \ifdefstring{\inputencodingname}{utf8}%
+ {\let\FV@ReadVArg@Char\FV@ReadVArg@Char@UTF}%
+ {}%
+ \fi
+ \edef\FV@TmpSpaceCat{\the\catcode` }%
+ \let\do\@makeother\FVExtraDoSpecials
+ \catcode`\^^B=\active
+ \FV@OuterDefSTXEmpty
+ \catcode`\^^C=\active
+ \FV@OuterDefETXEmpty
\catcode`\^^M=\active
\FV@OuterDefEOLEmpty
\begingroup
@@ -1963,20 +2015,20 @@
\catcode`\}=2
\catcode`\ =\active
\catcode`\^^I=\active
- \FV@ReadVArg@Group{#1}\FV@EOL}%
+ \FV@ReadVArg@Group{#1}}%
{\endgroup
\catcode`\ =\active
\catcode`\^^I=\active
- \FV@ReadVArg@Char{#1}\FV@EOL}}
+ \FV@ReadVArg@Char{#1}}}
% \end{macrocode}
% \end{macro}
%
% \begin{macro}{\FV@ReadVArg@Group}
% The argument is read under the verbatim catcode regime already in place from \cmd{\FVExtraReadVArg}. The \cmd{\endgroup} returns to prior catcodes. Any command-specific catcodes can be applied later via \cmd{\scantokens}. Using them here in reading the argument would have no effect as far as later processing with \cmd{\scantokens} is concerned, unless the argument were read outside any other commands and additional characters were given catcodes 1 or 2 (like the curly braces). That scenario is not allowed because it makes reading the argument overly dependent on the argument content. (Technically, reading the argument is already dependent on the argument content in the sense that the argument cannot contain unescaped unpaired curly braces, given that it is delimited by curly braces.)
% \begin{macrocode}
-\def\FV@ReadVArg@Group#1#2#3{%
+\def\FV@ReadVArg@Group#1#2{%
\endgroup
- #1{#3}}
+ #1{#2}}
% \end{macrocode}
% \end{macro}
%
@@ -1985,9 +2037,9 @@
%
% It would be possible to read the argument using any command-specific catcode settings, but that would result in different behavior depending on whether the argument is already tokenized, and would make reading the argument overly dependent on the argument content.
% \begin{macrocode}
-\def\FV@ReadVArg@Char#1#2#3{%
+\def\FV@ReadVArg@Char#1#2{%
\expandafter\expandafter\expandafter
- \if\expandafter\expandafter\expandafter\relax\expandafter\@gobble\detokenize{#3}\relax
+ \if\expandafter\expandafter\expandafter\relax\expandafter\@gobble\detokenize{#2}\relax
\expandafter\@gobble
\else
\expandafter\@firstofone
@@ -1995,10 +2047,10 @@
{\PackageError{fvextra}%
{Verbatim delimiters must be single characters, not commands}%
{Try a different delimiter}}%
- \def\FV@ReadVArg@Char@i##1##2##3#3{%
+ \def\FV@ReadVArg@Char@i##1##2#2{%
\endgroup
- ##1{##3}}%
- \FV@ReadVArg@Char@i{#1}\FV@EOL}%
+ ##1{##2}}%
+ \FV@ReadVArg@Char@i{#1}}%
% \end{macrocode}
% \end{macro}
%
@@ -2013,9 +2065,9 @@
% \begin{macro}{\FV@ReadVArg@Char@UTF}
% This is a variant of \cmd{\FV@ReadVArg@Char} that allows non-ASCII codepoints as delimiters under the pdfTeX engine with \pkg{inputenc} using UTF-8. Under pdfTeX, non-ASCII codepoints must be handled as a sequence of bytes rather than as a single entity. \cmd{\FV@ReadVArg@Char} is automatically \cmd{\let} to this version when appropriate. This uses the \cmd{\FV@U8:<byte>} macros for working with \pkg{inputenc}'s UTF-8.
% \begin{macrocode}
-\def\FV@ReadVArg@Char@UTF#1#2#3{%
+\def\FV@ReadVArg@Char@UTF#1#2{%
\expandafter\expandafter\expandafter
- \if\expandafter\expandafter\expandafter\relax\expandafter\@gobble\detokenize{#3}\relax
+ \if\expandafter\expandafter\expandafter\relax\expandafter\@gobble\detokenize{#2}\relax
\expandafter\@gobble
\else
\expandafter\@firstofone
@@ -2023,23 +2075,23 @@
{\PackageError{fvextra}%
{Verbatim delimiters must be single characters, not commands}%
{Try a different delimiter}}%
- \ifcsname FV@U8:\detokenize{#3}\endcsname
+ \ifcsname FV@U8:\detokenize{#2}\endcsname
\expandafter\@firstoftwo
\else
\expandafter\@secondoftwo
\fi
{\def\FV@UTF@octets@after##1{\FV@ReadVArg@Char@UTF@i{#1}{##1}}%
- \csname FV@U8:\detokenize{#3}\endcsname#3}%
- {\FV@ReadVArg@Char@UTF@i{#1}{#3}}}
+ \csname FV@U8:\detokenize{#2}\endcsname#2}%
+ {\FV@ReadVArg@Char@UTF@i{#1}{#2}}}
% \end{macrocode}
%
% \begin{macro}{\FV@ReadVArg@Char@UTF@i}
% \begin{macrocode}
\def\FV@ReadVArg@Char@UTF@i#1#2{%
- \def\FV@ReadVArg@Char@i##1##2##3#2{%
+ \def\FV@ReadVArg@Char@i##1##2#2{%
\endgroup
- ##1{##3}}%
- \FV@ReadVArg@Char@i{#1}\FV@EOL}%
+ ##1{##2}}%
+ \FV@ReadVArg@Char@i{#1}}%
% \end{macrocode}
% \end{macro}
%
@@ -2050,6 +2102,18 @@
% \end{macro}
%
%
+% \begin{macro}{vargsingleline}
+% This determines whether |\Verb| and |\SaveVerb| use |\FVExtraReadVArg| or |\FVExtraReadVArgSingleLine| to read their arguments. It has no effect on |\EscVerb|, since that does not use special tokenization.
+% \begin{macrocode}
+\newbool{FV@vargsingleline}
+\define@booleankey{FV}{vargsingleline}%
+ {\booltrue{FV@vargsingleline}}
+ {\boolfalse{FV@vargsingleline}}
+\fvset{vargsingleline=false}
+% \end{macrocode}
+% \end{macro}
+%
+%
%
%
% \subsubsection{Reading and protecting arguments in expansion-only contexts}
@@ -2219,12 +2283,16 @@
% \begin{macrocode}
\def\FVExtraUnexpandedReadStarOArgMArgBVArg#1#{%
\FV@UnexpandedReadStarOArgMArgBVArg@i{#1}}
-\def\FV@UnexpandedReadStarOArgMArgBVArg@i#1#2#3{%
- \FVExtraAlwaysUnexpanded{\FVExtraUnexpandedReadStarOArgMArgBVArg#1{#2}{#3}}}
+\def\FV@UnexpandedReadStarOArgMArgBVArg@i#1#2{%
+ \FV@UnexpandedReadStarOArgMArgBVArg@ii{#1}{#2}}
+\def\FV@UnexpandedReadStarOArgMArgBVArg@ii#1#2#3#{%
+ \FV@UnexpandedReadStarOArgMArgBVArg@iii{#1}{#2}{#3}}
+\def\FV@UnexpandedReadStarOArgMArgBVArg@iii#1#2#3#4{%
+ \FVExtraAlwaysUnexpanded{\FVExtraUnexpandedReadStarOArgMArgBVArg#1{#2}#3{#4}}}
\FVExtrapdfstringdefDisableCommands{%
\makeatletter
- \def\FV@UnexpandedReadStarOArgMArgBVArg@i#1#2#3{%
- \FVExtraPDFStringVerbatimDetokenize{#3}}%
+ \def\FV@UnexpandedReadStarOArgMArgBVArg@iii#1#2#3#4{%
+ \FVExtraPDFStringVerbatimDetokenize{#4}}%
\makeatother}
% \end{macrocode}
% \end{macro}
@@ -3033,7 +3101,7 @@
% \end{macro}
%
%
-% \paragraph{Detokenize as if the original source were tokenized verbatim, except for backslash escapes of non-catcode 11 characters, then convert to PDF string}
+% \paragraph{Detokenize as if the original source were tokenized verbatim, except for backslash escapes of non-catcode 11 characters, then convert to PDF string}\hfill\\
%
% \begin{macro}{\FVExtraPDFStringEscapedVerbatimDetokenize}
% This is identical to \cmd{\FVExtraEscapedVerbatimDetokenize}, except that the output is converted to a valid PDF string. All spaces are represented with the octal escape \cmd{\040} to prevent adjacent spaces from being merged. There is no alternate implementation for restricting escapes to ASCII symbols and punctuation. Typically, this would be used in an expansion-only context to create something like bookmarks, while \cmd{\FVExtraEscapedVerbatimDetokenize} (potentially with escape restrictions) would be used in parallel to generate whatever is actually typeset. Escape errors can be handled in generating what is typeset.
@@ -3069,7 +3137,7 @@
% \end{macro}
%
% \begin{macro}{\FV@PDFStrEscVDetok@ScanCont}
-% This is modified to use |\040| for the space. In the unescaped case, using a normal space here is fine, but in the escaped case, the preceeding or following token could be an escaped space.
+% This is modified to use |\040| for the space. In the unescaped case, using a normal space here is fine, but in the escaped case, the preceding or following token could be an escaped space.
% \begin{macrocode}
\begingroup
\catcode`\!=0\relax
@@ -3165,7 +3233,7 @@
% \end{macro}
%
% \begin{macro}{\FV@PDFStrEscVDetok@ScanTokenNoSpace}
-% This was modifed to add \cmd{\FVExtraPDFStringEscapeChar}
+% This was modified to add \cmd{\FVExtraPDFStringEscapeChar}
% \begin{macrocode}
\gdef\FV@PDFStrEscVDetok@ScanTokenNoSpace#1#2^^C{%
\if\relax\detokenize{#2}\relax
@@ -3357,8 +3425,7 @@
% \subsection{Hooks}
%
%
-% \begin{macro}{\FV@FormattingPrep@PreHook}
-% \begin{macro}{\FV@FormattingPrep@PostHook}
+% \begin{macro}{\FV@FormattingPrep@PreHook,\FV@FormattingPrep@PostHook}
% These are hooks for extending |\FV@FormattingPrep|. |\FV@FormattingPrep| is inside a group, before the beginning of processing, so it is a good place to add extension code. These hooks are used for such things as tweaking math mode behavior and preparing for |breakbefore| and |breakafter|. The |PreHook| should typically be used, unless \pkg{fancyvrb}'s font settings, whitespace setup, and active character definitions are needed for extension code.
% \begin{macrocode}
\let\FV@FormattingPrep@PreHook\@empty
@@ -3367,7 +3434,6 @@
\expandafter\FV@FormattingPrep@PreHook\FV@FormattingPrep\FV@FormattingPrep@PostHook}
% \end{macrocode}
% \end{macro}
-% \end{macro}
%
%
% \begin{macro}{\FV@PygmentsHook}
@@ -3433,7 +3499,8 @@
% \begin{macro}{\FV@UseInlineKeyValues}
% \begin{macrocode}
\def\FV@UseInlineKeyValues{%
- \expandafter\fvset\expandafter{\FV@InlineKeyValues}}
+ \expandafter\fvset\expandafter{\FV@InlineKeyValues}%
+ \FV@ApplyBreakAnywhereInlineStretch}
% \end{macrocode}
% \end{macro}
%
@@ -3539,7 +3606,10 @@
% \begin{macrocode}
\def\FVC@Verb@Extra@i{%
\begingroup
- \FVExtraReadVArg{%
+ \ifbool{FV@vargsingleline}%
+ {\let\FV@Reader\FVExtraReadVArgSingleLine}%
+ {\let\FV@Reader\FVExtraReadVArg}%
+ \FV@Reader{%
\FV@UseInlineKeyValues\FV@UseKeyValues\FV@FormattingPrep
\FVExtraDetokenizeVArg{%
\FVExtraRetokenizeVArg{\FVC@Verb@Extra@ii}{\FV@CatCodes}}}}
@@ -3547,15 +3617,26 @@
% \end{macro}
%
% \begin{macro}{\FVC@Verb@Extra@ii}
+% |breaklines| is only applied when there is no background color, since |\colorbox| prevents line breaks.
% \begin{macrocode}
\def\FVC@Verb@Extra@ii#1{%
- \ifFV@breaklines
+ \ifx\FancyVerbBackgroundColor\relax
\expandafter\@firstoftwo
\else
\expandafter\@secondoftwo
\fi
- {\FV@InsertBreaks{\FancyVerbFormatInline}{#1}}%
- {\mbox{#1}}%
+ {\ifbool{FV@breaklines}%
+ {\FV@InsertBreaks{\FancyVerbFormatInline}{#1}}%
+ {\mbox{\FancyVerbFormatInline{#1}}}}%
+ {\setlength{\FV@TmpLength}{\fboxsep}%
+ \ifx\FancyVerbBackgroundColorPadding\relax
+ \setlength{\fboxsep}{0pt}%
+ \else
+ \setlength{\fboxsep}{\FancyVerbBackgroundColorPadding}%
+ \fi
+ \colorbox{\FancyVerbBackgroundColor}{%
+ \setlength{\fboxsep}{\FV@TmpLength}%
+ \FancyVerbBackgroundColorVPhantom\FancyVerbFormatInline{#1}}}%
\endgroup}
% \end{macrocode}
% \end{macro}
@@ -3595,7 +3676,10 @@
\@namedef{FV@SV@#1}{}%
\@namedef{FV@SVRaw@#1}{}%
\begingroup
- \FVExtraReadVArg{%
+ \ifbool{FV@vargsingleline}%
+ {\let\FV@Reader\FVExtraReadVArgSingleLine}%
+ {\let\FV@Reader\FVExtraReadVArg}%
+ \FV@Reader{%
\FVC@SaveVerb@Extra@i{#1}}}
% \end{macrocode}
% \end{macro}
@@ -3698,15 +3782,7 @@
%
% \begin{macro}{\FV@UseVerb@Extra}
% \begin{macrocode}
-\def\FV@UseVerb@Extra#1{%
- \ifFV@breaklines
- \expandafter\@firstoftwo
- \else
- \expandafter\@secondoftwo
- \fi
- {\FV@InsertBreaks{\FancyVerbFormatInline}{#1}}%
- {\mbox{#1}}%
- \endgroup}
+\let\FV@UseVerb@Extra\FVC@Verb@Extra@ii
% \end{macrocode}
% \end{macro}
%
@@ -3761,15 +3837,7 @@
%
% \begin{macro}{\FVC@EscVerb@ii}
% \begin{macrocode}
-\def\FVC@EscVerb@ii#1{%
- \ifFV@breaklines
- \expandafter\@firstoftwo
- \else
- \expandafter\@secondoftwo
- \fi
- {\FV@InsertBreaks{\FancyVerbFormatInline}{#1}}%
- {\mbox{#1}}%
- \endgroup}
+\let\FVC@EscVerb@ii\FVC@Verb@Extra@ii
% \end{macrocode}
% \end{macro}
%
@@ -3912,7 +3980,7 @@
% \end{macro}
%
%
-% \begin{macro}{writer, \FV@Writer}
+% \begin{macro}{writer,\FV@Writer}
% Define writer macro that processes each line before writing.
% \begin{macrocode}
\define@key{FV}{writer}{%
@@ -3927,7 +3995,7 @@
% \begin{macro}{VerbatimWrite}
% The environment implementation follows standard \fancyvrb\ environment style.
%
-% A special write counter is used to track line numbers while avoiding incrementing the regular counter that is used for typeset code. Some macros do nothing with the default |writer|, but are needed to enable \fancyvrb\ options when a custom |writer| is used in conjuction with optional environment arguments. These include |\FancyVerbDefineActive|, |\FancyVerbFormatCom|, and |\FV@DefineTabOut|.
+% A special write counter is used to track line numbers while avoiding incrementing the regular counter that is used for typeset code. Some macros do nothing with the default |writer|, but are needed to enable \fancyvrb\ options when a custom |writer| is used in conjunction with optional environment arguments. These include |\FancyVerbDefineActive|, |\FancyVerbFormatCom|, and |\FV@DefineTabOut|.
% \begin{macrocode}
\newcounter{FancyVerbWriteLine}
\def\VerbatimWrite{%
@@ -3965,7 +4033,7 @@
%
% By default, all \fancyvrb\ options except for |VerbatimBuffer|-specific options are ignored. This can be customized on a per-environment basis via environment optional arguments.
%
-% \begin{macro}{afterbuffer, \FV@afterbuffer}
+% \begin{macro}{afterbuffer,\FV@afterbuffer}
% Macro that is inserted after the last line of the environment is buffered, immediately before the environment ends.
% \begin{macrocode}
\define@key{FV}{afterbuffer}{%
@@ -3981,7 +4049,7 @@
% \end{macrocode}
% \end{macro}
%
-% \begin{macro}{bufferer, \FV@Bufferer, \FancyVerbDefaultBufferer}
+% \begin{macro}{bufferer,\FV@Bufferer,\FancyVerbDefaultBufferer}
% This is the macro that adds lines to the buffer. The default is designed to create a truly verbatim buffer via |\detokenize|.
% \begin{macrocode}
\define@key{FV}{bufferer}{%
@@ -4038,7 +4106,7 @@
% \begin{macro}{VerbatimBuffer}
% The environment implementation follows standard \fancyvrb\ environment style.
%
-% A special buffer counter is used to track line numbers while avoiding incrementing the regular counter that is used for typeset code. Some macros do nothing with the default |bufferer|, but are needed to enable \fancyvrb\ options when a custom |bufferer| is used in conjuction with optional environment arguments. These include |\FancyVerbDefineActive| and |\FancyVerbFormatCom|. Since counters are global, the location of |\setcounter| at the end of the environment relative to |\begingroup...\endgroup| is not important.
+% A special buffer counter is used to track line numbers while avoiding incrementing the regular counter that is used for typeset code. Some macros do nothing with the default |bufferer|, but are needed to enable \fancyvrb\ options when a custom |bufferer| is used in conjunction with optional environment arguments. These include |\FancyVerbDefineActive| and |\FancyVerbFormatCom|. Since counters are global, the exact location of the |\setcounter| commands at the end of the environment relative to |\begingroup...\endgroup| is not important.
% \begin{macrocode}
\newcounter{FancyVerbBufferLine}
\newcounter{FV@oldbufferlength}
@@ -4054,17 +4122,19 @@
\def\FVB@VerbatimBuffer{%
\@bsphack
\begingroup
- \setcounter{FancyVerbBufferLine}{0}%
- \let\c@FancyVerbLine\c@FancyVerbBufferLine
- \setcounter{FancyVerbBufferIndex}{0}%
- \setcounter{FV@oldbufferlength}{\expandafter\value\expandafter{\FV@bufferlengthname}}%
- \expandafter\setcounter\expandafter{\FV@bufferlengthname}{0}%
\FV@UseKeyValues
+ \setcounter{FancyVerbBufferLine}%
+ {\expandafter\value\expandafter{\FV@bufferlengthname}}%
+ \let\c@FancyVerbLine\c@FancyVerbBufferLine
+ \setcounter{FancyVerbBufferIndex}%
+ {\expandafter\value\expandafter{\FV@bufferlengthname}}%
\ifbool{FV@globalbuffer}%
{\global\booltrue{FV@globalbuffer@tmp}}%
- {\global\boolfalse{FV@globalbuffer@tmp}}%
- \global\let\FV@bufferlengthname@tmp\FV@bufferlengthname
- \global\let\FancyVerbBufferLineName@tmp\FancyVerbBufferLineName
+ {\global\boolfalse{FV@globalbuffer@tmp}%
+ \setcounter{FV@oldbufferlength}%
+ {\expandafter\value\expandafter{\FV@bufferlengthname}}%
+ \global\let\FV@bufferlengthname@tmp\FV@bufferlengthname
+ \global\let\FancyVerbBufferLineName@tmp\FancyVerbBufferLineName}%
\global\let\FV@afterbuffer@tmp\FV@afterbuffer
\FV@DefineWhiteSpace
\def\FV@ProcessLine{\stepcounter{FancyVerbBufferIndex}\FV@Bufferer}%
@@ -4074,28 +4144,27 @@
\FancyVerbFormatCom
\FV@Scan}
\def\FVE@VerbatimBuffer{%
- \endgroup
- \@esphack
- \expandafter\setcounter\expandafter{\FV@bufferlengthname@tmp}%
+ \expandafter\setcounter\expandafter{\FV@bufferlengthname}%
{\value{FancyVerbBufferIndex}}%
\setcounter{FancyVerbBufferIndex}{0}%
+ \endgroup
+ \@esphack
\begingroup
\FV@afterbuffer@tmp
+ \global\let\FV@afterbuffer@tmp\relax
\endgroup
\ifbool{FV@globalbuffer@tmp}%
{}%
- {\ifnum\value{FV@oldbufferlength}>%
- \expandafter\value\expandafter{\FV@bufferlengthname@tmp}\relax
- \expandafter\setcounter\expandafter{\FV@bufferlengthname@tmp}%
- {\value{FV@oldbufferlength}}%
- \fi
- \loop\unless\ifnum\expandafter\value\expandafter{\FV@bufferlengthname@tmp}=0\relax
+ {\loop\unless\ifnum\expandafter\value\expandafter{\FV@bufferlengthname@tmp}=
+ \value{FV@oldbufferlength}\relax
\expandafter\global\expandafter\let\csname
\FancyVerbBufferLineName@tmp
\expandafter\arabic\expandafter{\FV@bufferlengthname@tmp}%
\endcsname\FV@Undefined
\expandafter\addtocounter\expandafter{\FV@bufferlengthname@tmp}{-1}%
- \repeat}}
+ \repeat
+ \global\let\FV@bufferlengthname@tmp\relax
+ \global\let\FancyVerbBufferLineName@tmp\relax}}
\def\endVerbatimBuffer{\FVE@VerbatimBuffer}
% \end{macrocode}
% \end{macro}
@@ -4103,50 +4172,98 @@
%
%
% \subsubsection{\cmd{\VerbatimInsertBuffer}}
-% \begin{macro}{\VerbatimInsertBuffer}
-% This inserts an existing buffer created by |VerbatimBuffer| as a |Verbatim| environment. It customizes |Verbatim| internals to function with a buffer in a command context.
+% \begin{macro}{\VerbatimInsertBuffer, insertenvname}
+% This inserts an existing buffer created with |VerbatimBuffer| as a verbatim environment. By default, the inserted environment is |Verbatim|; this can be modified with the option |insertenvname| to any |Verbatim|- or |BVerbatim|-based environment, or any environment with a compatible implementation. The |Verbatim| and |BVerbatim| internals are customized to function with a buffer in a command context.
+%
+% Notes on the implementation of |\VerbatimInsertBuffer@i|:
+% \begin{itemize}
+% \item The active |^^M| allows a verbatim environment to read optional arguments in the usual way, without requiring modifications to argument-reading macros.
+% \item The |\begingroup\fvset{#1}\global\let\FV@CurrentVerbatimInsertEnvName...| is used to extract any |insertenvname| setting from optional arguments. Most optional arguments apply to the verbatim environment or to the customized verbatim internals that are invoked within it. However, |insertenvname| is needed earlier to determine which verbatim environment is in use. It is not possible simply to use |\fvset{#1}| before the verbatim environment to apply all settings, because that would conflict with the precedence of option processing in |\FV@Environment|.
+% \end{itemize}
% \begin{macrocode}
-\newcommand{\VerbatimInsertBuffer}[1][]{%
- \begingroup
+\define@key{FV}{insertenvname}{%
+ \def\FV@VerbatimInsertEnvName{#1}}
+\fvset{insertenvname=Verbatim}
+\def\FV@Environment@InsertBuffer#1#2{%
\def\FV@KeyValues{#1}%
- \def\FV@Scan{%
- \FV@CatCodes
- \xdef\FV@EnvironName{Verbatim}%
- \ifnum\expandafter\value\expandafter{\FV@bufferlengthname}=\z@\relax
- \PackageError{fvextra}%
- {Buffer length counter \FV@bufferlengthname\space is invalid or zero}%
- {}%
- \let\FV@GetLine\relax
+ \FV@GetKeyValues{\@nameuse{FVB@#2}}}
+\def\FV@Scan@InsertBuffer{%
+ \FV@CatCodes
+ \xdef\FV@EnvironName{\FV@VerbatimInsertEnvName}%
+ \ifnum\expandafter\value\expandafter{\FV@bufferlengthname}=\z@\relax
+ \PackageError{fvextra}%
+ {Buffer length counter \FV@bufferlengthname\space is invalid or zero}%
+ {}%
+ \let\FV@GetLine\relax
+ \fi
+ \FV@BeginScanning}%
+\def\VerbatimInsertBuffer@def@FV@Line#1{%
+ \FVExtraRetokenizeVArg{\def\FV@Line}{}{#1}}
+\def\FancyVerbGetLine@VerbatimInsertBuffer{%
+ \ifnum\value{FancyVerbBufferIndex}>%
+ \expandafter\value\expandafter{\FV@bufferlengthname}\relax
+ \global\let\FV@EnvironName\relax
+ \let\next\relax
+ \else
+ \ifcsname\FancyVerbBufferLineName\arabic{FancyVerbBufferIndex}\endcsname
+ \expandafter\let\expandafter\FV@Line@Buffer
+ \csname\FancyVerbBufferLineName\arabic{FancyVerbBufferIndex}\endcsname
+ \expandafter\VerbatimInsertBuffer@def@FV@Line\expandafter{\FV@Line@Buffer}%
+ \def\next{\FV@PreProcessLine\FV@GetLine}%
+ \stepcounter{FancyVerbBufferIndex}%
+ \else
+ \def\next{%
+ \PackageError{fvextra}%
+ {Buffer with line macro named
+ "\FancyVerbBufferLineName\arabic{FancyVerbBufferIndex}" does not exist}%
+ {Check bufferlinename, bufferlengthname, and globalbuffer settings}%
+ }%
\fi
- \FV@GetLine}%
+ \fi
+ \next}
+\newcommand{\VerbatimInsertBuffer}[1][]{%
+ \begingroup
+ \let\FV@Scan\FV@Scan@InsertBuffer
\let\FV@CheckScan\relax
+ \let\FV@Environment\FV@Environment@InsertBuffer
+ \let\FancyVerbGetLine\FancyVerbGetLine@VerbatimInsertBuffer
\setcounter{FancyVerbBufferIndex}{1}%
- \def\VerbatimInsertBuffer@def@FV@Line##1{%
- \FVExtraRetokenizeVArg{\def\FV@Line}{}{##1}}
- \def\FancyVerbGetLine{%
- \ifnum\value{FancyVerbBufferIndex}>%
- \expandafter\value\expandafter{\FV@bufferlengthname}\relax
- \global\let\FV@EnvironName\relax
- \let\next\relax
- \else
- \ifcsname \FancyVerbBufferLineName\arabic{FancyVerbBufferIndex}\endcsname
- \expandafter\let\expandafter\FV@Line@Buffer
- \csname\FancyVerbBufferLineName\arabic{FancyVerbBufferIndex}\endcsname
- \expandafter\VerbatimInsertBuffer@def@FV@Line\expandafter{\FV@Line@Buffer}%
- \def\next{\FV@PreProcessLine\FV@GetLine}%
- \stepcounter{FancyVerbBufferIndex}%
- \else
- \def\next{%
- \PackageError{fvextra}%
- {Buffer with line macro named
- "\FancyVerbBufferLineName\arabic{FancyVerbBufferIndex}" does not exist}%
- {Check bufferlinename, bufferlengthname, and globalbuffer settings}%
- }%
- \fi
- \fi
- \next}%
- \FVB@Verbatim
- \FVE@Verbatim
+ \VerbatimInsertBuffer@i{#1}%
+ \setcounter{FancyVerbBufferIndex}{0}%
+ \endgroup
+ \@doendpe}
+\begingroup
+\catcode`\^^M=\active
+\gdef\VerbatimInsertBuffer@i#1{%
+ \begingroup%
+ \fvset{#1}%
+ \global\let\FV@CurrentVerbatimInsertEnvName\FV@VerbatimInsertEnvName%
+ \endgroup%
+ \csname \FV@CurrentVerbatimInsertEnvName\endcsname[#1]^^M%
+ \csname end\FV@CurrentVerbatimInsertEnvName\endcsname%
+ \global\let\FV@CurrentVerbatimInsertEnvName\FV@Undefined}%
+\endgroup
+% \end{macrocode}
+% \end{macro}
+%
+%
+% \subsubsection{\cmd{\VerbatimClearBuffer}}
+% \begin{macro}{\VerbatimClearBuffer}
+% Clear an existing buffer.
+% \begin{macrocode}
+\newcommand{\VerbatimClearBuffer}[1][]{%
+ \begingroup
+ \def\FV@KeyValues{#1}%
+ \FV@UseKeyValues
+ \setcounter{FancyVerbBufferIndex}%
+ {\expandafter\value\expandafter{\FV@bufferlengthname}}%
+ \expandafter\setcounter\expandafter{\FV@bufferlengthname}{0}%
+ \loop\unless\ifnum\value{FancyVerbBufferIndex}<1\relax
+ \expandafter\global\expandafter\let
+ \csname\FancyVerbBufferLineName\arabic{FancyVerbBufferIndex}\endcsname
+ \FV@Undefined
+ \addtocounter{FancyVerbBufferIndex}{-1}%
+ \repeat
\setcounter{FancyVerbBufferIndex}{0}%
\endgroup}
% \end{macrocode}
@@ -4796,7 +4913,7 @@
%
%
% \begin{macro}{\FV@ListProcessLine@NoBreak}
-% Redefined |\FV@ListProcessLine| in which |\FancyVerbFormatText| is added and tab handling is explicit. The |@NoBreak| suffix is added because |\FV@ListProcessLine| will be |\let| to either this macro or to |\FV@ListProcessLine@Break| depending on whether line breaking is enabled.
+% Redefined |\FV@ListProcessLine| in which |bgcolor| support is added, |\FancyVerbFormatText| is added, and tab handling is explicit. The |@NoBreak| suffix is added because |\FV@ListProcessLine| will be |\let| to either this macro or to |\FV@ListProcessLine@Break| depending on whether line breaking is enabled.
% \begin{macrocode}
\def\FV@ListProcessLine@NoBreak#1{%
\hbox to \hsize{%
@@ -4804,9 +4921,10 @@
\hbox to \linewidth{%
\FV@LeftListNumber
\FV@LeftListFrame
- \FancyVerbFormatLine{%
- \FancyVerbHighlightLine{%
- \FV@ObeyTabs{\FancyVerbFormatText{#1}}}}\hss
+ \FV@BGColor@List{%
+ \FancyVerbFormatLine{%
+ \FancyVerbHighlightLine{%
+ \FV@ObeyTabs{\FancyVerbFormatText{#1}}}}}\hss
\FV@RightListFrame
\FV@RightListNumber}%
\hss}}
@@ -4819,6 +4937,10 @@
% \begin{macrocode}
\def\FV@BProcessLine#1{%
\hbox{\FancyVerbFormatLine{%
+ \ifx\FancyVerbBackgroundColor\relax
+ \else
+ \expandafter\FancyVerbBackgroundColorVPhantom
+ \fi
\FancyVerbHighlightLine{%
\FV@ObeyTabs{\FancyVerbFormatText{#1}}}}}}
% \end{macrocode}
@@ -5046,6 +5168,194 @@
%
%
%
+% \subsubsection{Background color}
+% \label{sec:impl:extensions:bgcolor}
+%
+% Define an option |backgroundcolor| that provides a basic implementation of a background color behind commands and environments. \pkg{tcolorbox} or a similar package should be used for more sophisticated background colors.
+% \begin{macro}{backgroundcolor,bgcolor,\FancyVerbBackgroundColor}
+% \begin{macrocode}
+\define@key{FV}{backgroundcolor}{%
+ \def\FancyVerbBackgroundColor{#1}%
+ \ifx\FancyVerbBackgroundColor\FV@None
+ \let\FancyVerbBackgroundColor\relax
+ \else\ifx\FancyVerbBackgroundColor\@empty
+ \let\FancyVerbBackgroundColor\relax
+ \fi\fi}%
+\fvset{backgroundcolor=none}
+\define@key{FV}{bgcolor}{%
+ \fvset{backgroundcolor=#1}}
+% \end{macrocode}
+% \end{macro}
+%
+%
+% \begin{macro}{backgroundcolorvphantom,bgcolorvphantom,\FancyVerbBackgroundColorVPhantom}
+% \begin{macrocode}
+\define@key{FV}{backgroundcolorvphantom}{%
+ \def\FancyVerbBackgroundColorVPhantom{#1}%
+ \ifx\FancyVerbBackgroundColorVPhantom\FV@None
+ \let\FancyVerbBackgroundColorVPhantom\relax
+ \else\ifx\FancyVerbBackgroundColorVPhantom\@empty
+ \let\FancyVerbBackgroundColorVPhantom\relax
+ \fi\fi}
+\fvset{backgroundcolorvphantom=\vphantom{\"Apgjy}}
+\define@key{FV}{bgcolorvphantom}{%
+ \fvset{backgroundcolorvphantom=#1}}
+% \end{macrocode}
+% \end{macro}
+%
+%
+% \begin{macro}{backgroundcolorpadding, bgcolorpadding, \FancyVerbBackgroundColorPadding}
+% \begin{macrocode}
+\let\FancyVerbBackgroundColorPadding\relax
+\def\FV@backgroundcolorpadding@none@framenotsingle{%
+ \fvset{frame=none,framerule,rulecolor=none}}
+\def\FV@backgroundcolorpadding@dim@framenotsingle{%
+ \fvset{frame=single,framerule=0pt,rulecolor=\FancyVerbBackgroundColor}}
+\define@key{FV}{backgroundcolorpadding}{%
+ \def\FancyVerbBackgroundColorPadding{#1}%
+ \ifx\FancyVerbBackgroundColorPadding\FV@None
+ \let\FancyVerbBackgroundColorPadding\relax
+ \else\ifx\FancyVerbBackgroundColorPadding\@empty
+ \let\FancyVerbBackgroundColorPadding\relax
+ \fi\fi
+ \let\FV@Next\relax
+ \ifx\FancyVerbBackgroundColorPadding\relax
+ \ifx\FV@BeginListFrame\FV@BeginListFrame@Single
+ \else
+ \let\FV@Next\FV@backgroundcolorpadding@none@framenotsingle
+ \fi
+ \ifx\FV@LeftListFrame\FV@LeftListFrame@Single
+ \else
+ \let\FV@Next\FV@backgroundcolorpadding@none@framenotsingle
+ \fi
+ \ifx\FV@RightListFrame\FV@RightListFrame@Single
+ \else
+ \let\FV@Next\FV@backgroundcolorpadding@none@framenotsingle
+ \fi
+ \ifx\FV@EndListFrame\FV@EndListFrame@Single
+ \else
+ \let\FV@Next\FV@backgroundcolorpadding@none@framenotsingle
+ \fi
+ \FV@Next
+ \fvset{framesep,fillcolor=none}%
+ \else
+ \ifx\FV@BeginListFrame\FV@BeginListFrame@Single
+ \else
+ \let\FV@Next\FV@backgroundcolorpadding@dim@framenotsingle
+ \fi
+ \ifx\FV@LeftListFrame\FV@LeftListFrame@Single
+ \else
+ \let\FV@Next\FV@backgroundcolorpadding@dim@framenotsingle
+ \fi
+ \ifx\FV@RightListFrame\FV@RightListFrame@Single
+ \else
+ \let\FV@Next\FV@backgroundcolorpadding@dim@framenotsingle
+ \fi
+ \ifx\FV@EndListFrame\FV@EndListFrame@Single
+ \else
+ \let\FV@Next\FV@backgroundcolorpadding@dim@framenotsingle
+ \fi
+ \FV@Next
+ \fvset{framesep=#1,fillcolor=\FancyVerbBackgroundColor}%
+ \fi}
+\define@key{FV}{bgcolorpadding}{\fvset{backgroundcolorpadding=#1}}
+% \end{macrocode}
+% \end{macro}
+%
+%
+% \begin{macro}{\FV@BGColor@List}
+% Background color for environments based on |Verbatim|. Puts each line in a colorbox. The |\FancyVerbBackgroundColorVPhantom| will not have any effect in this case, unless it is larger than |\strut|.
+% \begin{macrocode}
+\def\FV@BGColor@List#1{%
+ \ifx\FancyVerbBackgroundColor\relax
+ \expandafter\@firstoftwo
+ \else
+ \expandafter\@secondoftwo
+ \fi
+ {#1}%
+ {\setlength{\FV@TmpLength}{\fboxsep}%
+ \setlength{\fboxsep}{0pt}%
+ \colorbox{\FancyVerbBackgroundColor}{%
+ \setlength{\fboxsep}{\FV@TmpLength}%
+ \rlap{\FancyVerbBackgroundColorVPhantom\strut#1}%
+ \hspace{\linewidth}%
+ \ifx\FV@RightListFrame\relax\else
+ \hspace{-\FV@FrameSep}%
+ \hspace{-\FV@FrameRule}%
+ \fi
+ \ifx\FV@LeftListFrame\relax\else
+ \hspace{-\FV@FrameSep}%
+ \hspace{-\FV@FrameRule}%
+ \fi}%
+ \hss}}
+% \end{macrocode}
+% \end{macro}
+%
+%
+% \begin{macro}{\FV@BVerbatimBegin,\FV@BVerbatimEnd}
+% Reimplementation of |BVerbatim| macros to support |bgcolor|. Much of this follows the implementation of |SaveVerbatim| and |\BUseVerbatim|.
+%
+% Key values, formatting, and tabs must be configured immediately in the |bgcolor| case, so that the background color and other settings are available. |\FV@UseKeyValues| can be invoked multiple times, but that doesn't cause any issues since |\FV@UseKeyValues| applies keys and then redefines |\FV@KeyValues| to empty.
+%
+% The definition of |\FV@BProcessLine| already accounts for |\FancyVerbBackgroundColorVPhantom|.
+% \begin{macrocode}
+\let\FV@BVerbatimBegin@NoBGColor\FV@BVerbatimBegin
+\let\FV@BVerbatimEnd@NoBGColor\FV@BVerbatimEnd
+\def\FV@BVerbatimBegin{%
+ \begingroup
+ \FV@UseKeyValues
+ \FV@FormattingPrep
+ \let\FV@FormattingPrep\relax
+ \FV@ObeyTabsInit
+ \let\FV@ObeyTabsInit\relax
+ \ifx\FancyVerbBackgroundColor\relax
+ \expandafter\FV@BVerbatimBegin@NoBGColor
+ \else
+ \expandafter\FV@BVerbatimBegin@BGColor
+ \fi}
+\def\FV@BVerbatimEnd{%
+ \ifx\FancyVerbBackgroundColor\relax
+ \expandafter\FV@BVerbatimEnd@NoBGColor
+ \else
+ \expandafter\FV@BVerbatimEnd@BGColor
+ \fi
+ \endgroup}
+\def\FV@BVerbatimBegin@BGColor{%
+ \gdef\FV@TheVerbatim{}%
+ \ifx\FV@boxwidth\relax
+ \gdef\FV@boxwidth@tmp{0pt}%
+ \def\FV@ProcessLine##1{%
+ \sbox{\FV@LineBox}{\FV@BProcessLine{##1}}%
+ \ifdim\wd\FV@LineBox>\FV@boxwidth@tmp\relax
+ \xdef\FV@boxwidth@tmp{\the\wd\FV@LineBox}%
+ \fi
+ \expandafter\gdef\expandafter\FV@TheVerbatim\expandafter{%
+ \FV@TheVerbatim\FV@ProcessLine{##1}}}%
+ \else
+ \def\FV@ProcessLine##1{%
+ \expandafter\gdef\expandafter\FV@TheVerbatim\expandafter{%
+ \FV@TheVerbatim\FV@ProcessLine{##1}}}%
+ \fi}
+\def\FV@BVerbatimEnd@BGColor{%
+ \ifx\FV@boxwidth\relax
+ \let\FV@boxwidth\FV@boxwidth@tmp
+ \global\let\FV@boxwidth@tmp\FV@Undefined
+ \fi
+ \setlength{\FV@TmpLength}{\fboxsep}%
+ \ifx\FancyVerbBackgroundColorPadding\relax
+ \setlength{\fboxsep}{0pt}%
+ \else
+ \setlength{\fboxsep}{\FancyVerbBackgroundColorPadding}%
+ \fi
+ \colorbox{\FancyVerbBackgroundColor}{%
+ \setlength{\fboxsep}{\FV@TmpLength}%
+ \FV@BVerbatimBegin@NoBGColor\FV@TheVerbatim\FV@BVerbatimEnd@NoBGColor}%
+ \gdef\FV@TheVerbatim{}}
+% \end{macrocode}
+% \end{macro}
+%
+%
+%
% \subsubsection{Line highlighting or emphasis}
% \label{sec:impl:extensions:highlighting}
%
@@ -5221,6 +5531,32 @@
% \end{macro}
%
%
+% \begin{macro}{\FV@StepLineNo@Patch@HighlightLine}
+% Patch |\FV@StepLineNo| so that when |numberblanklines=false|, blank lines won't be highlighted. If the previous line is at the end of a highlighted range, then |\let| |\FV@HighlightLine:<n>| to |\FV@Undefined| to prevent further highlighting. Otherwise, leave everything as-is since the blank line(s) are within a highlighted range.
+% \begin{macrocode}
+\def\FV@StepLineNo@Patch@HighlightLine{%
+ \ifcsname FV@HighlightLine:\number\c@FancyVerbLine\endcsname
+ \@tempcnta=\c@FancyVerbLine
+ \advance\@tempcnta\@ne
+ \ifcsname FV@HighlightLine:\number\@tempcnta\endcsname
+ \else
+ \expandafter\let
+ \csname FV@HighlightLine:\number\c@FancyVerbLine\endcsname\FV@Undefined
+ \fi
+ \fi}
+\patchcmd{\FV@StepLineNo}%
+ {\ifx\FV@Line\empty}%
+ {\ifx\FV@Line\empty\FV@StepLineNo@Patch@HighlightLine}%
+ {}%
+ {\PackageError{fvextra}%
+ {Failed to patch \string\FV@StepLineNo\ to make highlightlines
+ compatible with numberblanklines}%
+ {Failed to patch \string\FV@StepLineNo\ to make highlightlines
+ compatible with numberblanklines}}
+% \end{macrocode}
+% \end{macro}
+%
+%
%
%
% \subsection{Line breaking}
@@ -5432,6 +5768,7 @@
%
%
% We need macros that contain the logic for typesetting the break symbols. By default, the symbol macros contain everything regarding the symbol and its typesetting, while these macros contain pure logic. The symbols should be wrapped in braces so that formatting commands (for example, |\tiny|) don't escape.
+%
% \begin{macro}{\FancyVerbBreakSymbolLeftLogic}
% The left break symbol should only appear with continuation lines. Note that |linenumber| here refers to local line numbering for the broken line, \emph{not} line numbering for all lines in the environment being typeset.
% \begin{macrocode}
@@ -5503,6 +5840,30 @@
% \end{macrocode}
% \end{macro}
%
+% \begin{macro}{breakanywhereinlinestretch,\FV@breakanywhereinlinestretch,\FV@ApplyBreakAnywhereInlineStretch}
+% Stretch glue to insert at potential |breakanywhere| break locations in inline contexts, to give better line widths and avoid overfull |\hbox|.
+%
+% |\FV@UseInlineKeyValues| invokes |\FV@ApplyBreakAnywhereInlineStretch| to redefine |\FancyVerbBreakAnywhereBreak| locally.
+% \begin{macrocode}
+\define@key{FV}{breakanywhereinlinestretch}{%
+ \def\FV@breakanywhereinlinestretch{#1}%
+ \ifx\FV@breakanywhereinlinestretch\FV@None
+ \let\FV@breakanywhereinlinestretch\relax
+ \else\ifx\FV@breakanywhereinlinestretch\@empty
+ \let\FV@breakanywhereinlinestretch\relax
+ \fi\fi}
+\fvset{breakanywhereinlinestretch=none}
+\def\FV@ApplyBreakAnywhereInlineStretch{%
+ \ifx\FV@breakanywhereinlinestretch\relax
+ \else
+ \let\FancyVerbBreakAnywhereBreak@Orig\FancyVerbBreakAnywhereBreak
+ \def\FancyVerbBreakAnywhereBreak{%
+ \nobreak\hspace{0pt plus \FV@breakanywhereinlinestretch}%
+ \FancyVerbBreakAnywhereBreak@Orig}%
+ \fi}
+% \end{macrocode}
+% \end{macro}
+%
%
% \begin{macro}{\FV@BreakBefore}
% Allow line breaking (almost) anywhere, but only before specified characters.
@@ -5534,7 +5895,7 @@
% \end{macro}
%
% \begin{macro}{\FV@BreakBeforePrep}
-% We need a way to break before characters if and only if they have been specified as breaking characters. It would be possible to do that via a nested conditional, but that would be messy. It is much simpler to create an empty macro whose name contains the character, and test for the existence of this macro. This needs to be done inside a |\begingroup...\endgroup| so that the macros do not have to be cleaned up manually. A good place to do this is in |\FV@FormattingPrep|, which is inside a group and before processing starts. The macro is added to |\FV@FormattingPrep@PreHook|, which contains \fvextra\ exntensions to |\FV@FormattingPrep|, after |\FV@BreakAfterPrep| is defined below.
+% We need a way to break before characters if and only if they have been specified as breaking characters. It would be possible to do that via a nested conditional, but that would be messy. It is much simpler to create an empty macro whose name contains the character, and test for the existence of this macro. This needs to be done inside a |\begingroup...\endgroup| so that the macros do not have to be cleaned up manually. A good place to do this is in |\FV@FormattingPrep|, which is inside a group and before processing starts. The macro is added to |\FV@FormattingPrep@PreHook|, which contains \fvextra\ extensions to |\FV@FormattingPrep|, after |\FV@BreakAfterPrep| is defined below.
%
% The procedure here is a bit roundabout. We need to use |\FV@EscChars| to handle character escapes, but the character redefinitions need to be kept local, requiring that we work within a |\begingroup...\endgroup|. So we loop through the breaking tokens and assemble a macro that will itself define character macros. Only this defining macro is declared global, and it contains \emph{expanded} characters so that there is no longer any dependence on |\FV@EscChars|.
%
@@ -5765,9 +6126,29 @@
% \end{macro}
%
%
+% \begin{macro}{breakpreferspaces,\FV@BreakHyphenation}
+% Adjust hyphenation settings for |breaklines|.
+%
+% When |breakbefore|, |breakafter|, or |breakanywhere| are in use, |\finalhyphendemerits=0| prevents the final ``word'' on a line from being put into a line segment by itself after line breaking. Otherwise, \TeX\ tries to avoid a line break (hyphenation) within a ``word'' on the penultimate line segment, and may accomplish this by introducing an unnecessary line break at the space before the last ``word.''
+%
+% |breakpreferspaces| (|\linepenalty|) determines whether line breaks are preferentially inserted at normal spaces (|breakcollapsespaces=true|, |showspaces=false|) rather than at other locations allowed by |breakbefore|, |breakafter|, or |breakanywhere|.
+% \begin{macrocode}
+\newbool{FV@breakpreferspaces}
+\booltrue{FV@breakpreferspaces}
+\define@booleankey{FV}{breakpreferspaces}%
+ {\booltrue{FV@breakpreferspaces}}%
+ {\boolfalse{FV@breakpreferspaces}}
+\def\FV@BreakHyphenation{%
+ \finalhyphendemerits=0\relax
+ \ifbool{FV@breakpreferspaces}{}{\linepenalty=\@M\relax}}
+\g@addto@macro\FV@FormattingPrep@PreHook{\FV@BreakHyphenation}
+% \end{macrocode}
+% \end{macro}
+%
+%
% \subsubsection{Line breaking implementation}
%
-% \paragraph{Helper macros}
+% \paragraph{Helper macros}\hfill\\
%
% \begin{macro}{\FV@LineBox}
% A box for saving a line of text, so that its dimensions may be determined and thus we may figure out if it needs line breaking.
@@ -5873,7 +6254,7 @@
% \begin{macro}{\FV@BreakBufferStart}
% Create a new buffer, either at the beginning of scanning or during recursion. The single mandatory argument is the macro for handling tokens, which is |\let| to |\FV@Break@Token|. An intermediate |\FV@BreakBufferStart@i| is used to optimize |\ifx| comparisons for |\FV@BreakBufferStart| during scanning.
%
-% For recursion, |\FV@BreakBuffer<n>| and |\FV@Break@Token<n>| store the state (buffer and token handling macro) immediately prior to recusion with depth |<n>|.
+% For recursion, |\FV@BreakBuffer<n>| and |\FV@Break@Token<n>| store the state (buffer and token handling macro) immediately prior to recursion with depth |<n>|.
% \begin{macrocode}
\def\FV@BreakBufferStart{%
\FV@BreakBufferStart@i}
@@ -6543,7 +6924,7 @@
%
%
%
-% \paragraph{Line processing before scanning}
+% \paragraph{Line processing before scanning}\hfill\\
%
% \begin{macro}{\FV@makeLineNumber}
% The \pkg{lineno} package is used for formatting wrapped lines and inserting break symbols. We need a version of \pkg{lineno}'s |\makeLineNumber| that is adapted for our purposes. This is adapted directly from the example |\makeLineNumber| that is given in the \pkg{lineno} documentation under the discussion of internal line numbers. The |\FV@SetLineBreakLast| is needed to determine the internal line number of the last segment of the broken line, so that we can disable the right-hand break symbol on this segment. When a right-hand break symbol is in use, a line of code will be processed twice: once to determine the last internal line number, and once to use this information only to insert right-hand break symbols on the appropriate lines. During the second run, |\FV@SetLineBreakLast| is disabled by |\let|ting it to |\relax|.
@@ -6670,8 +7051,9 @@
\FV@SaveLineBox{#1}}%
\FV@LeftListNumber
\FV@LeftListFrame
- \FancyVerbFormatLine{%
- \FancyVerbHighlightLine{\usebox{\FV@LineBox}}}%
+ \FV@BGColor@List{%
+ \FancyVerbFormatLine{%
+ \FancyVerbHighlightLine{\usebox{\FV@LineBox}}}}%
\FV@RightListFrame
\FV@RightListNumber
\ifx\FV@Tab\FV@TrueTab@UseWidth
@@ -6682,10 +7064,11 @@
\let\FancyVerbBreakStop\relax
\FV@LeftListNumber
\FV@LeftListFrame
- \FancyVerbFormatLine{%
- \FancyVerbHighlightLine{%
- \parbox[t]{\FV@LineWidth}{%
- \noindent\strut\FV@ObeyTabs{\FancyVerbFormatText{#1}}\strut}}}%
+ \FV@BGColor@List{%
+ \FancyVerbFormatLine{%
+ \FancyVerbHighlightLine{%
+ \parbox[t]{\FV@LineWidth}{%
+ \noindent\strut\FV@ObeyTabs{\FancyVerbFormatText{#1}}\strut}}}}%
\FV@RightListFrame
\FV@RightListNumber
\fi}%
@@ -6873,7 +7256,7 @@
%
% In the |breakbytoken| cases, an |\hbox| is used to prevent breaks within the macro (breaks could occur at spaces even without |\FancyVerbBreakStart|). The |breakbytokenanywhere| case is similar but a little tricky. |\FV@BreakByTokenAnywhereHook|, which is inside |\FV@SaveLineBox| where line breaking occurs, is used to define |\FV@BreakByTokenAnywhereBreak| so that it will ``do nothing'' the first time it is used and on subsequent invocations become |\FancyVerbBreakByTokenAnywhereBreak|. Because the hook is within the |internallinenumbers*| environment, the redefinition doesn't escape, and the default global definition of |\FV@BreakByTokenAnywhereBreak| as |\relax| is not affected. We don't want the actual break to appear before the first Pygments macro in case it might cause a spurious break after leading whitespace. But we must have breaks \emph{before} Pygments macros because otherwise lookahead would be necessary.
%
-% An intermediate variable |\FV@PYG| is defined to avoid problems in case |#1|$=$|#2|. There is also a check for a non-existant |#2| (|\PYG|\meta{style\_name} may not be created until a later compile in the \pkg{pythontex} case); if |#2| does not exist, fall back to |#1|. For the existance check, |\ifx...\relax| must be used instead of |\ifcsname|, because |#2| will be a macro, and will typically be created with |\csname...\endcsname| which will |\let| the macro to |\relax| if it doesn't already exist.
+% An intermediate variable |\FV@PYG| is defined to avoid problems in case |#1|$=$|#2|. There is also a check for a non-existent |#2| (|\PYG|\meta{style\_name} may not be created until a later compile in the \pkg{pythontex} case); if |#2| does not exist, fall back to |#1|. For the existence check, |\ifx...\relax| must be used instead of |\ifcsname|, because |#2| will be a macro, and will typically be created with |\csname...\endcsname| which will |\let| the macro to |\relax| if it doesn't already exist.
%
% |\FV@PYG@Redefed| is |\let| to the Pygments macro that appears literally (after redefinition), so that it can be detected elsewhere to allow for special processing, such as in |breakautoindent|.
% \begin{macrocode}