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.dtx785
1 files changed, 623 insertions, 162 deletions
diff --git a/macros/latex/contrib/fvextra/fvextra.dtx b/macros/latex/contrib/fvextra/fvextra.dtx
index e4182b6f88..f5b8aca429 100644
--- a/macros/latex/contrib/fvextra/fvextra.dtx
+++ b/macros/latex/contrib/fvextra/fvextra.dtx
@@ -26,7 +26,7 @@
%<package>\NeedsTeXFormat{LaTeX2e}[1999/12/01]
%<package>\ProvidesPackage{fvextra}
%<*package>
- [2024/05/16 v1.7.0 fvextra - extensions and patches for fancyvrb]
+ [2024/10/16 v1.9.0 fvextra - extensions and patches for fancyvrb]
%</package>
%
%<*driver>
@@ -111,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}}}
@@ -134,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
@@ -147,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}
@@ -290,7 +339,7 @@
%\hrule
%\vspace{2ex}
%\noindent\begin{minipage}{\linewidth}
-%\begin{Verbatim}[gobble=1]
+%\begin{verbatim}
%---
%header-includes:
% - |
@@ -301,7 +350,7 @@
% breaklines, breaknonspaceingroup, breakanywhere}
% ```
%---
-%\end{Verbatim}
+%\end{verbatim}
%\end{minipage}
%\vspace{2ex}
%\hrule
@@ -317,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.
%
@@ -522,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}
%
%
@@ -585,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.
@@ -611,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}}
%
@@ -718,7 +819,7 @@
%
% Below is an extended example that demonstrates what is possible with |VerbatimBuffer| combined with |\VerbatimInsertBuffer|. This uses |\ifdefstring| from the \pkg{etoolbox} package.
% \begin{itemize}
-% \item |\setformatter| defines an empty |\formatter| macro. Then it loops over the lines in a buffer looking for a line containing only the text ``red''. If this is found, it redefines |\formatter| to |\color{red}|. |FancyVerbBufferIndex| is a counter that is always available for buffer looping. |FancyVerbBufferLength| is the default counter containing the buffer length (number of lines). |\FancyVerbBufferLineName| contains the base name for buffer line macros (default |FancyVerbBufferLine|).
+% \item |\setformatter| defines an empty |\formatter| macro. Then it loops over the lines in a buffer looking for a line containing only the text ``red''. If this is found, it redefines |\formatter| to |\color{red}|. |FancyVerbBufferIndex| is a counter that is always available for buffer looping. |\FancyVerbBufferLength| is the default macro containing the buffer length (number of lines). |\FancyVerbBufferLineName| contains the base name for buffer line macros (default |FancyVerbBufferLine|).
% \item |afterbuffer| involves two steps: (1) |\setformatter| loops through the buffer and defines |\formatter| based on the buffer contents, and (2) |\VerbatimInsertBuffer| typesets the buffer, using |formatcom=\formatter| to format the text based on whether any line contains only the text ``red''.
% \end{itemize}
%
@@ -726,7 +827,7 @@
%\def\setformatter{%
% \def\formatter{}%
% \setcounter{FancyVerbBufferIndex}{1}%
-% \loop\unless\ifnum\value{FancyVerbBufferIndex}>\value{FancyVerbBufferLength}\relax
+% \loop\unless\ifnum\value{FancyVerbBufferIndex}>\FancyVerbBufferLength\relax
% \expandafter\let\expandafter\bufferline
% \csname\FancyVerbBufferLineName\arabic{FancyVerbBufferIndex}\endcsname
% \ifdefstring{\bufferline}{red}{\def\formatter{\color{red}}}{}%
@@ -745,7 +846,7 @@
% Here is the same example, but rewritten to use a global buffer with custom buffer names instead.
%
%\begin{tcblisting}{oversize=5em}
-%\begin{VerbatimBuffer}[globalbuffer, bufferlinename=exbuff, bufferlengthname=exbuff]
+%\begin{VerbatimBuffer}[globalbuffer, bufferlinename=exbuff, bufferlengthname=exbufflen]
%first
%second
%red
@@ -753,7 +854,7 @@
%
%\def\formatter{}
%\setcounter{FancyVerbBufferIndex}{1}
-%\loop\unless\ifnum\value{FancyVerbBufferIndex}>\value{exbuff}\relax
+%\loop\unless\ifnum\value{FancyVerbBufferIndex}>\exbufflen\relax
% \expandafter\let\expandafter\bufferline
% \csname exbuff\arabic{FancyVerbBufferIndex}\endcsname
% \ifdefstring{\bufferline}{red}{\def\formatter{\color{red}}}{}
@@ -763,7 +864,7 @@
%\VerbatimInsertBuffer[
% formatcom=\formatter,
% bufferlinename=exbuff,
-% bufferlengthname=exbuff
+% bufferlengthname=exbufflen
%]
%\end{tcblisting}
%
@@ -773,7 +874,7 @@
%
% \begin{optionlist}
% \item[afterbuffer (macro) (\meta{none})]
-% Macro or macros invoked at the end of the environment, after all lines of the environment have been buffered. This is outside the |\begingroup...\endgroup| that wraps verbatim processing, so \fancyvrb\ settings are no longer active. However, the buffer line macros and the buffer length counter are still accessible.
+% Macro or macros invoked at the end of the environment, after all lines of the environment have been buffered. This is outside the |\begingroup...\endgroup| that wraps verbatim processing, so \fancyvrb\ settings are no longer active. However, the buffer line macros and the buffer length macro are still accessible.
%
% \item[bufferer (macro) (\Verb{\FancyVerbDefaultBufferer})]
% This is the macro that adds lines to the buffer. The default is designed to create a truly verbatim buffer via |\detokenize|. This can be customized if you wish to use \fancyvrb\ options related to catcodes to create a buffer that is only partially verbatim (that contains macros).
@@ -789,7 +890,7 @@
% This macro must be defined globally, so |\xdef| or |\gdef| is necessary (this does not interfere with scoping from |globalbuffer|). Otherwise, there are no restrictions. The |\xdef| and |\detokenize| in the default definition guarantee that the buffer consists only of the literal text from the environment, but this is not required for a custom |bufferer|.
%
% \item[bufferlengthname (string) (FancyVerbBufferLength)]
-% Name of the counter (|\newcounter|) storing the length of the buffer. This is the number of lines stored.
+% Name of the macro storing the length of the buffer. This is the number of lines stored.
%
% \item[bufferlinename (string) (FancyVerbBufferLine)]
% The base name of the buffer line macros. The default is |FancyVerbBufferLine|, which will result in buffer macros |\FancyVerbBufferLine<n>| with integer |n| greater than or equal to one and less than or equal to the number of lines (one-based indexing). Since buffer macro names contain a number, they must be accessed differently than typical macros:
@@ -803,28 +904,36 @@
% 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. 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.
+% 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 macro 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=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.
+% 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 macro (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.
+% Clear an existing buffer created with \cmd{VerbatimBuffer}. |\global\let| all buffer line macros to an undefined macro and set the buffer length macro to zero.
%
%
%
@@ -885,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|.
%
@@ -931,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.
%
@@ -980,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|.
%
@@ -1369,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}
%
%
@@ -1506,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.
@@ -1820,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
@@ -1840,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
@@ -1852,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}
%
@@ -1874,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
@@ -1884,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}
%
@@ -1902,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
@@ -1912,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}
%
@@ -1939,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}
@@ -2926,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.
@@ -2962,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
@@ -3058,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
@@ -3250,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
@@ -3260,7 +3434,6 @@
\expandafter\FV@FormattingPrep@PreHook\FV@FormattingPrep\FV@FormattingPrep@PostHook}
% \end{macrocode}
% \end{macro}
-% \end{macro}
%
%
% \begin{macro}{\FV@PygmentsHook}
@@ -3326,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}
%
@@ -3432,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}}}}
@@ -3440,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}
@@ -3488,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}
@@ -3591,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}
%
@@ -3654,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}
%
@@ -3805,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}{%
@@ -3820,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{%
@@ -3858,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}{%
@@ -3868,13 +4043,13 @@
% \end{macro}
%
% \begin{macro}{FancyVerbBufferIndex}
-% Current index in buffer during buffering. This is given a |\FancyVerb*| macro name since it may be accessed by the user in defining custom |bufferer|.
+% Current index in buffer during buffering. This is given a |FancyVerb*| macro name since it may be accessed by the user in defining custom |bufferer|.
% \begin{macrocode}
\newcounter{FancyVerbBufferIndex}
% \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}{%
@@ -3887,14 +4062,16 @@
% \end{macro}
%
% \begin{macro}{bufferlengthname, \FV@bufferlengthname}
-% Name of counter storing the length of the buffer.
+% Name of macro storing the length of the buffer.
% \begin{macrocode}
\define@key{FV}{bufferlengthname}{%
- \ifcsname c@#1\endcsname
+ \ifcsname#1\endcsname
\else
- \newcounter{#1}%
+ \expandafter\xdef\csname#1\endcsname{0}%
\fi
- \def\FV@bufferlengthname{#1}}
+ \def\FV@bufferlengthname{#1}%
+ \expandafter\def\expandafter\FV@bufferlengthmacro\expandafter{%
+ \csname#1\endcsname}}
\fvset{bufferlengthname=FancyVerbBufferLength}
% \end{macrocode}
% \end{macro}
@@ -3917,7 +4094,7 @@
% \end{macro}
%
% \begin{macro}{globalbuffer, FV@globalbuffer}
-% Whether buffer macros and the buffer length counter are defined globally.
+% Whether buffer line macros and the buffer length macro are defined globally.
% \begin{macrocode}
\newbool{FV@globalbuffer}
\define@booleankey{FV}{globalbuffer}%
@@ -3931,12 +4108,12 @@
% \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 exact location of the |\setcounter| commands 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}
\newbool{FV@globalbuffer@tmp}
-\let\FV@bufferlengthname@tmp\relax
+\let\FV@oldbufferlength\relax
+\let\FV@bufferlengthmacro@tmp\relax
\let\FancyVerbBufferLineName@tmp\relax
\let\FV@afterbuffer@tmp\relax
\def\VerbatimBuffer{%
@@ -3948,17 +4125,14 @@
\@bsphack
\begingroup
\FV@UseKeyValues
- \setcounter{FancyVerbBufferLine}%
- {\expandafter\value\expandafter{\FV@bufferlengthname}}%
+ \setcounter{FancyVerbBufferLine}{\FV@bufferlengthmacro}%
\let\c@FancyVerbLine\c@FancyVerbBufferLine
- \setcounter{FancyVerbBufferIndex}%
- {\expandafter\value\expandafter{\FV@bufferlengthname}}%
+ \setcounter{FancyVerbBufferIndex}{\FV@bufferlengthmacro}%
\ifbool{FV@globalbuffer}%
{\global\booltrue{FV@globalbuffer@tmp}}%
{\global\boolfalse{FV@globalbuffer@tmp}%
- \setcounter{FV@oldbufferlength}%
- {\expandafter\value\expandafter{\FV@bufferlengthname}}%
- \global\let\FV@bufferlengthname@tmp\FV@bufferlengthname
+ \expandafter\global\expandafter\let\expandafter\FV@oldbufferlength\FV@bufferlengthmacro
+ \global\let\FV@bufferlengthmacro@tmp\FV@bufferlengthmacro
\global\let\FancyVerbBufferLineName@tmp\FancyVerbBufferLineName}%
\global\let\FV@afterbuffer@tmp\FV@afterbuffer
\FV@DefineWhiteSpace
@@ -3969,8 +4143,7 @@
\FancyVerbFormatCom
\FV@Scan}
\def\FVE@VerbatimBuffer{%
- \expandafter\setcounter\expandafter{\FV@bufferlengthname}%
- {\value{FancyVerbBufferIndex}}%
+ \expandafter\xdef\FV@bufferlengthmacro{\theFancyVerbBufferIndex}%
\setcounter{FancyVerbBufferIndex}{0}%
\endgroup
\@esphack
@@ -3980,16 +4153,16 @@
\endgroup
\ifbool{FV@globalbuffer@tmp}%
{}%
- {\loop\unless\ifnum\expandafter\value\expandafter{\FV@bufferlengthname@tmp}=
- \value{FV@oldbufferlength}\relax
+ {\loop\unless\ifnum\FV@bufferlengthmacro@tmp=\FV@oldbufferlength\relax
\expandafter\global\expandafter\let\csname
- \FancyVerbBufferLineName@tmp
- \expandafter\arabic\expandafter{\FV@bufferlengthname@tmp}%
+ \FancyVerbBufferLineName@tmp\FV@bufferlengthmacro@tmp
\endcsname\FV@Undefined
- \expandafter\addtocounter\expandafter{\FV@bufferlengthname@tmp}{-1}%
+ \expandafter\xdef\FV@bufferlengthmacro@tmp{%
+ \the\numexpr\FV@bufferlengthmacro@tmp-1\relax}%
\repeat
- \global\let\FV@bufferlengthname@tmp\relax
- \global\let\FancyVerbBufferLineName@tmp\relax}}
+ \global\let\FV@bufferlengthmacro@tmp\relax
+ \global\let\FancyVerbBufferLineName@tmp\relax}%
+ \global\let\FV@oldbufferlength\relax}
\def\endVerbatimBuffer{\FVE@VerbatimBuffer}
% \end{macrocode}
% \end{macro}
@@ -3997,53 +4170,76 @@
%
%
% \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\FV@bufferlengthmacro=\z@\relax
+ \PackageError{fvextra}%
+ {Buffer length macro \expandafter\string\FV@bufferlengthmacro\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}>\FV@bufferlengthmacro\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}
%
@@ -4056,9 +4252,8 @@
\begingroup
\def\FV@KeyValues{#1}%
\FV@UseKeyValues
- \setcounter{FancyVerbBufferIndex}%
- {\expandafter\value\expandafter{\FV@bufferlengthname}}%
- \expandafter\setcounter\expandafter{\FV@bufferlengthname}{0}%
+ \setcounter{FancyVerbBufferIndex}{\FV@bufferlengthmacro}%
+ \expandafter\xdef\FV@bufferlengthmacro{0}%
\loop\unless\ifnum\value{FancyVerbBufferIndex}<1\relax
\expandafter\global\expandafter\let
\csname\FancyVerbBufferLineName\arabic{FancyVerbBufferIndex}\endcsname
@@ -4714,7 +4909,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{%
@@ -4722,9 +4917,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}}
@@ -4737,6 +4933,10 @@
% \begin{macrocode}
\def\FV@BProcessLine#1{%
\hbox{\FancyVerbFormatLine{%
+ \ifx\FancyVerbBackgroundColor\relax
+ \else
+ \expandafter\FancyVerbBackgroundColorVPhantom
+ \fi
\FancyVerbHighlightLine{%
\FV@ObeyTabs{\FancyVerbFormatText{#1}}}}}}
% \end{macrocode}
@@ -4964,6 +5164,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}
%
@@ -5139,6 +5527,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}
@@ -5350,6 +5764,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}
@@ -5421,6 +5836,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.
@@ -5452,7 +5891,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|.
%
@@ -5683,9 +6122,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.
@@ -5791,7 +6250,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}
@@ -6461,7 +6920,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|.
@@ -6588,8 +7047,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
@@ -6600,10 +7060,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}%
@@ -6791,7 +7252,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}
generated by cgit v1.2.3 (git 2.39.1) at 2024-11-10 01:29:16 +0000