summaryrefslogtreecommitdiff
path: root/support/latexindent/documentation/sec-the-m-switch.tex
diff options
context:
space:
mode:
Diffstat (limited to 'support/latexindent/documentation/sec-the-m-switch.tex')
-rw-r--r--support/latexindent/documentation/sec-the-m-switch.tex1947
1 files changed, 26 insertions, 1921 deletions
diff --git a/support/latexindent/documentation/sec-the-m-switch.tex b/support/latexindent/documentation/sec-the-m-switch.tex
index d8cdbe62c6..8a824987f6 100644
--- a/support/latexindent/documentation/sec-the-m-switch.tex
+++ b/support/latexindent/documentation/sec-the-m-switch.tex
@@ -5,8 +5,8 @@
\tikz[remember picture,overlay] {
\node at (1,0){\includegraphics{logo}};
}}
- All features described in this section will only be relevant if the
- \texttt{-m} switch is used.
+ All features described in this section will only be relevant if the \texttt{-m} switch is
+ used.
\startcontents[the-m-switch]
\printcontents[the-m-switch]{}{0}{}
@@ -17,16 +17,17 @@
\end{wrapfigure}
\makebox[0pt][r]{%
\raisebox{-\totalheight}[0pt][0pt]{%
- \tikz\node[opacity=1] at (0,0) {\includegraphics[width=4cm]{logo}};}}%
- As of Version 3.0, \texttt{latexindent.pl} has the \texttt{-m}
- switch, which permits \texttt{latexindent.pl} to modify line breaks, according to the
- specifications in the \texttt{modifyLineBreaks} field. \emph{The settings
- in this field will only be considered if the \texttt{-m} switch has been used}. A
- snippet of the default settings of this field is shown in \cref{lst:modifylinebreaks}.
+ \tikz\node[opacity=1] at (0,0)
+ {\includegraphics[width=4cm]{logo}};}}%
+ As of Version 3.0, \texttt{latexindent.pl} has the \texttt{-m} switch, which permits
+ \texttt{latexindent.pl} to modify line breaks, according to the specifications in the
+ \texttt{modifyLineBreaks} field. \emph{The settings in this field will only be considered
+ if the \texttt{-m} switch has been used}. A snippet of the default settings of this field
+ is shown in \cref{lst:modifylinebreaks}.
Having read the previous paragraph, it should sound reasonable that, if you call
- \texttt{latexindent.pl} using the \texttt{-m} switch, then you give
- it permission to modify line breaks in your file, but let's be clear:
+ \texttt{latexindent.pl} using the \texttt{-m} switch, then you give it permission to
+ modify line breaks in your file, but let's be clear:
\index{warning!the m switch}
\begin{warning}
@@ -37,1922 +38,26 @@
\end{warning}
\yamltitle{preserveBlankLines}{0|1}
- This field is directly related to \emph{poly-switches}, discussed below. By
- default, it is set to \texttt{1}, which means that blank lines will be
- protected from removal; however, regardless of this setting, multiple blank lines can be
- condensed if \texttt{condenseMultipleBlankLinesInto} is greater than \texttt{0},
- discussed next.
+ This field is directly related to \emph{poly-switches}, discussed in
+ \cref{sec:poly-switches}. By default, it is set to \texttt{1}, which means that blank
+ lines will be \emph{protected} from removal; however, regardless of this setting,
+ multiple blank lines can be condensed if \texttt{condenseMultipleBlankLinesInto} is
+ greater than \texttt{0}, discussed next.
\yamltitle{condenseMultipleBlankLinesInto}*{positive integer}
- Assuming that this switch takes an integer value greater than
- \texttt{0}, \texttt{latexindent.pl} will condense multiple blank
- lines into the number of blank lines illustrated by this switch. As an example,
- \cref{lst:mlb-bl} shows a sample file with blank lines; upon running
+ Assuming that this switch takes an integer value greater than \texttt{0},
+ \texttt{latexindent.pl} will condense multiple blank lines into the number of blank lines
+ illustrated by this switch. As an example, \cref{lst:mlb-bl} shows a sample file with
+ blank lines; upon running
\index{switches!-m demonstration}
\begin{commandshell}
-latexindent.pl myfile.tex -m
+latexindent.pl myfile.tex -m -o=+-mod1
\end{commandshell}
- the output is shown in \cref{lst:mlb-bl-out}; note that the multiple blank lines
- have been condensed into one blank line, and note also that we have used the
- \texttt{-m} switch!
-
- \begin{minipage}{.45\textwidth}
- \cmhlistingsfromfile{demonstrations/mlb1.tex}{\texttt{mlb1.tex}}{lst:mlb-bl}
- \end{minipage}%
- \hfill
- \begin{minipage}{.45\textwidth}
- \cmhlistingsfromfile{demonstrations/mlb1-out.tex}{\texttt{mlb1.tex} out output}{lst:mlb-bl-out}
- \end{minipage}
-
-\subsection{textWrapOptions: modifying line breaks by text wrapping}\label{subsec:textwrapping}
- When the \texttt{-m} switch is active \texttt{latexindent.pl} has the
- ability to wrap text using the options%
- \announce{2017-05-27}{textWrapOptions} specified in the \texttt{textWrapOptions} field, see
- \cref{lst:textWrapOptions}. The value of \texttt{columns} specifies the
- column at which the text should be wrapped. By default, the value of
- \texttt{columns} is \texttt{0}, so
- \texttt{latexindent.pl} will \emph{not} wrap text; if you change it
- to a value of \texttt{2} or more, then text will be wrapped after the
- character in the specified column.
- \index{modifying linebreaks! by text wrapping, globally}
-
- \cmhlistingsfromfile[style=textWrapOptions]*{../defaultSettings.yaml}[MLB-TCB,width=.85\linewidth,before=\centering]{\texttt{textWrapOptions}}{lst:textWrapOptions}
-
- For example, consider the file give in \cref{lst:textwrap1}.
-
- \begin{widepage}
- \cmhlistingsfromfile{demonstrations/textwrap1.tex}{\texttt{textwrap1.tex}}{lst:textwrap1}
- \end{widepage}
-
- Using the file \texttt{textwrap1.yaml} in \cref{lst:textwrap1-yaml}, and running
- the command
- \index{switches!-l demonstration}
- \index{switches!-m demonstration}
- \index{switches!-o demonstration}
- \begin{commandshell}
-latexindent.pl -m textwrap1.tex -o textwrap1-mod1.tex -l textwrap1.yaml
-\end{commandshell}
- we obtain the output in \cref{lst:textwrap1-mod1}.
-
- \begin{cmhtcbraster}[raster column skip=.1\linewidth]
- \cmhlistingsfromfile{demonstrations/textwrap1-mod1.tex}{\texttt{textwrap1-mod1.tex}}{lst:textwrap1-mod1}
- \cmhlistingsfromfile{demonstrations/textwrap1.yaml}[MLB-TCB]{\texttt{textwrap1.yaml}}{lst:textwrap1-yaml}
- \end{cmhtcbraster}
-
- The text wrapping routine is performed \emph{after} verbatim environments
- \index{verbatim!in relation to textWrapOptions} have been stored, so verbatim environments and verbatim
- commands are exempt from the routine. For example, using the file in
- \cref{lst:textwrap2},
- \begin{widepage}
- \cmhlistingsfromfile{demonstrations/textwrap2.tex}{\texttt{textwrap2.tex}}{lst:textwrap2}
- \end{widepage}
- and running the following command and continuing to use \texttt{textwrap1.yaml} from
- \cref{lst:textwrap1-yaml},
- \index{switches!-l demonstration}
- \index{switches!-m demonstration}
- \index{switches!-o demonstration}
- \begin{commandshell}
-latexindent.pl -m textwrap2.tex -o textwrap2-mod1.tex -l textwrap1.yaml
-\end{commandshell}
- then the output is as in \cref{lst:textwrap2-mod1}.
- \begin{widepage}
- \cmhlistingsfromfile{demonstrations/textwrap2-mod1.tex}{\texttt{textwrap2-mod1.tex}}{lst:textwrap2-mod1}
- \end{widepage}
- Furthermore, the text wrapping routine is performed after the trailing comments have been
- stored, and they are also exempt from text wrapping. For example, using the file in
- \cref{lst:textwrap3}
- \begin{widepage}
- \cmhlistingsfromfile{demonstrations/textwrap3.tex}{\texttt{textwrap3.tex}}{lst:textwrap3}
- \end{widepage}
- and running the following command and continuing to use \texttt{textwrap1.yaml} from
- \cref{lst:textwrap1-yaml},
- \index{switches!-l demonstration}
- \index{switches!-m demonstration}
- \index{switches!-o demonstration}
- \begin{commandshell}
-latexindent.pl -m textwrap3.tex -o textwrap3-mod1.tex -l textwrap1.yaml
-\end{commandshell}
- then the output is as in \cref{lst:textwrap3-mod1}.
-
- \cmhlistingsfromfile{demonstrations/textwrap3-mod1.tex}{\texttt{textwrap3-mod1.tex}}{lst:textwrap3-mod1}
-
- The%
- \announce*{2021-07-23}*{huge:overflow is now default} default value of
- \texttt{huge} is \texttt{overflow}, which means that words will
- \emph{not} be broken by the text wrapping routine, implemented by the
- \texttt{Text::Wrap} \cite{textwrap}. There are options to change the
- \texttt{huge} option for the \texttt{Text::Wrap} module to either
- \texttt{wrap} or \texttt{die}. Before modifying the value of
- \texttt{huge}, please bear in mind the following warning:
- \index{warning!changing huge (textwrap)}
- \begin{warning}
- \raggedright
- Changing the value of \texttt{huge} to anything other than \texttt{overflow} will slow down
- \texttt{latexindent.pl} significantly when the \texttt{-m} switch is active.
-
- Furthermore, changing \texttt{huge} means that you may have some words \emph{or commands}(!)
- split across lines in your .tex file, which may affect your output. I do not recommend
- changing this field.
- \end{warning}
-
- For example, using the settings in \cref{lst:textwrap2A-yaml,lst:textwrap2B-yaml} and running the commands
- \index{switches!-l demonstration}
- \index{switches!-m demonstration}
- \index{switches!-o demonstration}
- \begin{commandshell}
-latexindent.pl -m textwrap4.tex -o=+-mod2A -l textwrap2A.yaml
-latexindent.pl -m textwrap4.tex -o=+-mod2B -l textwrap2B.yaml
-\end{commandshell}
- gives the respective output in \cref{lst:textwrap4-mod2A,lst:textwrap4-mod2B}.
-
- \begin{cmhtcbraster}[raster column skip=.1\linewidth]
- \cmhlistingsfromfile{demonstrations/textwrap4-mod2A.tex}{\texttt{textwrap4-mod2A.tex}}{lst:textwrap4-mod2A}
- \cmhlistingsfromfile*{demonstrations/textwrap2A.yaml}[MLB-TCB]{\texttt{textwrap2A.yaml}}{lst:textwrap2A-yaml}
-
- \cmhlistingsfromfile{demonstrations/textwrap4-mod2B.tex}{\texttt{textwrap4-mod2B.tex}}{lst:textwrap4-mod2B}
- \cmhlistingsfromfile*{demonstrations/textwrap2B.yaml}[MLB-TCB]{\texttt{textwrap2B.yaml}}{lst:textwrap2B-yaml}
- \end{cmhtcbraster}
-
- You can also specify the \texttt{tabstop}
- field%
- \announce{2020-11-06}{tabstop option for text wrap module} as an integer
- value, which is passed to the text wrap module; see \cite{textwrap} for
- details. Starting with the code in \cref{lst:textwrap-ts} with settings in
- \cref{lst:tabstop}, and running the command
- \index{switches!-l demonstration}
- \index{switches!-m demonstration}
- \index{switches!-o demonstration}
- \begin{commandshell}
-latexindent.pl -m textwrap-ts.tex -o=+-mod1 -l tabstop.yaml
-\end{commandshell}
- gives the code given in \cref{lst:textwrap-ts-mod1}.
- \begin{cmhtcbraster}[raster columns=3,
- raster left skip=-3.5cm,
- raster right skip=-2cm,
- raster column skip=.03\linewidth]
- \cmhlistingsfromfile[showtabs=true]*{demonstrations/textwrap-ts.tex}{\texttt{textwrap-ts.tex}}{lst:textwrap-ts}
- \cmhlistingsfromfile{demonstrations/tabstop.yaml}[MLB-TCB]{\texttt{tabstop.yaml}}{lst:tabstop}
- \cmhlistingsfromfile[showtabs=true]*{demonstrations/textwrap-ts-mod1.tex}{\texttt{textwrap-ts-mod1.tex}}{lst:textwrap-ts-mod1}
- \end{cmhtcbraster}
-
- You can specify \texttt{separator}, \texttt{break} and
- \texttt{unexpand} options in your settings in analogous ways to those
- demonstrated in \cref{lst:textwrap2B-yaml,lst:tabstop}, and they will be passed to the
- \texttt{Text::Wrap} module. I have not found a useful reason to do this; see
- \cite{textwrap} for more details.
-
-\subsubsection{text wrapping on a per-code-block basis}
- By default, if the value of \texttt{columns} is greater than 0 and the
- \texttt{-m} switch is active, then%
- \announce{2018-08-13}*{updates to textWrapOptions} the text wrapping routine will operate before the code blocks
- have been searched for. This behaviour is customisable; in particular, you can instead
- instruct \texttt{latexindent.pl} to apply \texttt{textWrap} on a
- per-code-block basis. Thanks to \cite{zoehneto} for their help in testing and
- shaping this feature.
- \index{modifying linebreaks! by text wrapping, per-code-block}
-
- The full details of \texttt{textWrapOptions} are shown in \cref{lst:textWrapOptionsAll}.
- In particular, note the field \texttt{perCodeBlockBasis: 0}.
- \index{specialBeginEnd!textWrapOptions}
-
- \cmhlistingsfromfile*[style=textWrapOptionsAll]*{../defaultSettings.yaml}[MLB-TCB,width=.85\linewidth,before=\centering]{\texttt{textWrapOptions}}{lst:textWrapOptionsAll}
-
- The code blocks detailed in \cref{lst:textWrapOptionsAll} are with direct reference to
- those detailed in \vref{tab:code-blocks}. The only special case is the
- \texttt{masterDocument} field; this is designed for `chapter'-type files that may
- contain paragraphs that are not within any other code-blocks. The same notation is used
- between this feature and the \texttt{removeParagraphLineBreaks} described in
- \vref{lst:removeParagraphLineBreaks}; in fact, the two features can even be combined (this is
- detailed in \vref{subsec:removeparagraphlinebreaks:and:textwrap}).
-
- Let's explore these switches with reference to the code given in
- \cref{lst:textwrap5}; the text outside of the environment is considered part of
- the \texttt{masterDocument}.
-
- \begin{widepage}
- \cmhlistingsfromfile{demonstrations/textwrap5.tex}{\texttt{textwrap5.tex}}{lst:textwrap5}
- \end{widepage}
-
- With reference to this code block, the settings given in \cref{lst:textwrap3-yaml,lst:textwrap4-yaml,lst:textwrap5-yaml} each
- give the same output.
-
- \begin{cmhtcbraster}[raster columns=3,
- raster left skip=-3.5cm,
- raster right skip=-2cm,
- raster column skip=.03\linewidth]
- \cmhlistingsfromfile{demonstrations/textwrap3.yaml}[MLB-TCB]{\texttt{textwrap3.yaml}}{lst:textwrap3-yaml}
- \cmhlistingsfromfile{demonstrations/textwrap4.yaml}[MLB-TCB]{\texttt{textwrap4.yaml}}{lst:textwrap4-yaml}
- \cmhlistingsfromfile{demonstrations/textwrap5.yaml}[MLB-TCB]{\texttt{textwrap5.yaml}}{lst:textwrap5-yaml}
- \end{cmhtcbraster}
-
- Let's explore the similarities and differences in the equivalent (with respect to
- \cref{lst:textwrap5}) syntax specified in \cref{lst:textwrap3-yaml,lst:textwrap4-yaml,lst:textwrap5-yaml}:
- \begin{itemize}
- \item in each of \cref{lst:textwrap3-yaml,lst:textwrap4-yaml,lst:textwrap5-yaml} notice that \texttt{columns: 30};
- \item in each of \cref{lst:textwrap3-yaml,lst:textwrap4-yaml,lst:textwrap5-yaml} notice that \texttt{perCodeBlockBasis: 1};
- \item in \cref{lst:textwrap3-yaml} we have specified \texttt{all: 1} so that the
- text wrapping will operate upon \emph{all} code blocks;
- \item in \cref{lst:textwrap4-yaml} we have \emph{not} specified
- \texttt{all}, and instead, have specified that text wrapping should be
- applied to each of \texttt{environments} and \texttt{masterDocument};
- \item in \cref{lst:textwrap5-yaml} we have specified text wrapping for
- \texttt{masterDocument} and on a \emph{per-name} basis for
- \texttt{environments} code blocks.
- \end{itemize}
-
- Upon running the following commands
- \index{switches!-l demonstration}
- \index{switches!-m demonstration}
- \begin{commandshell}
-latexindent.pl -s textwrap5.tex -l=textwrap3.yaml -m
-latexindent.pl -s textwrap5.tex -l=textwrap4.yaml -m
-latexindent.pl -s textwrap5.tex -l=textwrap5.yaml -m
-\end{commandshell}
- we obtain the output shown in \cref{lst:textwrap5-mod3}.
-
- \cmhlistingsfromfile{demonstrations/textwrap5-mod3.tex}{\texttt{textwrap5-mod3.tex}}{lst:textwrap5-mod3}
-
- We can explore the idea of per-name text wrapping given in \cref{lst:textwrap5-yaml} by
- using \cref{lst:textwrap6}.
-
- \begin{widepage}
- \cmhlistingsfromfile{demonstrations/textwrap6.tex}{\texttt{textwrap6.tex}}{lst:textwrap6}
- \end{widepage}
-
- In particular, upon running
- \index{switches!-l demonstration}
- \index{switches!-m demonstration}
- \begin{commandshell}
-latexindent.pl -s textwrap6.tex -l=textwrap5.yaml -m
-\end{commandshell}
- we obtain the output given in \cref{lst:textwrap6-mod5}.
-
- \begin{widepage}
- \cmhlistingsfromfile{demonstrations/textwrap6-mod5.tex}{\texttt{textwrap6.tex} using \cref{lst:textwrap5-yaml}}{lst:textwrap6-mod5}
- \end{widepage}
-
- Notice that, because \texttt{environments} has been specified only for
- \texttt{myenv} (in \cref{lst:textwrap5-yaml}) that the environment named \texttt{another} has
- \emph{not} had text wrapping applied to it.
-
- The {all} field can be specified with exceptions which can either
- be done on a per-code-block or per-name basis; we explore this in relation to
- \cref{lst:textwrap6} in the settings given in \crefrange{lst:textwrap6-yaml}{lst:textwrap8-yaml}.
-
- \begin{adjustwidth}{-3.5cm}{-2.5cm}
- \begin{minipage}{.33\linewidth}
- \cmhlistingsfromfile{demonstrations/textwrap6.yaml}[MLB-TCB]{\texttt{textwrap6.yaml}}{lst:textwrap6-yaml}
- \end{minipage}%
- \begin{minipage}{.33\linewidth}
- \cmhlistingsfromfile{demonstrations/textwrap7.yaml}[MLB-TCB]{\texttt{textwrap7.yaml}}{lst:textwrap7-yaml}
- \end{minipage}%
- \begin{minipage}{.33\linewidth}
- \cmhlistingsfromfile{demonstrations/textwrap8.yaml}[MLB-TCB]{\texttt{textwrap8.yaml}}{lst:textwrap8-yaml}
- \end{minipage}
- \end{adjustwidth}
-
- Upon running the commands
- \index{switches!-l demonstration}
- \index{switches!-m demonstration}
- \begin{commandshell}
-latexindent.pl -s textwrap6.tex -l=textwrap6.yaml -m
-latexindent.pl -s textwrap6.tex -l=textwrap7.yaml -m
-latexindent.pl -s textwrap6.tex -l=textwrap8.yaml -m
-\end{commandshell}
- we receive the respective output given in \crefrange{lst:textwrap6-mod6}{lst:textwrap6-mod8}.
- \begin{widepage}
- \cmhlistingsfromfile{demonstrations/textwrap6-mod6.tex}{\texttt{textwrap6.tex} using \cref{lst:textwrap6-yaml}}{lst:textwrap6-mod6}
-
- \cmhlistingsfromfile{demonstrations/textwrap6-mod7.tex}{\texttt{textwrap6.tex} using \cref{lst:textwrap7-yaml}}{lst:textwrap6-mod7}
-
- \cmhlistingsfromfile{demonstrations/textwrap6-mod8.tex}{\texttt{textwrap6.tex} using \cref{lst:textwrap8-yaml}}{lst:textwrap6-mod8}
- \end{widepage}
-
- Notice that:
- \begin{itemize}
- \item in \cref{lst:textwrap6-mod6} the text wrapping routine has not been applied to any
- \texttt{environments} because it has been switched off (per-code-block) in
- \cref{lst:textwrap6-yaml};
- \item in \cref{lst:textwrap6-mod7} the text wrapping routine has not been applied to
- \texttt{myenv} because it has been switched off (per-name) in
- \cref{lst:textwrap7-yaml};
- \item in \cref{lst:textwrap6-mod8} the text wrapping routine has not been applied to
- \texttt{masterDocument} because of the settings in \cref{lst:textwrap8-yaml}.
- \end{itemize}
-
- The \texttt{columns} field has a variety of different ways that it can be
- specified; we've seen two basic ways already: the default (set to
- \texttt{0}) and a positive integer (see \vref{lst:textwrap6}, for
- example). We explore further options in \crefrange{lst:textwrap9-yaml}{lst:textwrap11-yaml}.
-
- \begin{cmhtcbraster}[raster columns=3,
- raster left skip=-3.5cm,
- raster right skip=-2cm,
- raster column skip=.03\linewidth]
- \cmhlistingsfromfile{demonstrations/textwrap9.yaml}[MLB-TCB]{\texttt{textwrap9.yaml}}{lst:textwrap9-yaml}
- \cmhlistingsfromfile{demonstrations/textwrap10.yaml}[MLB-TCB]{\texttt{textwrap10.yaml}}{lst:textwrap10-yaml}
- \cmhlistingsfromfile{demonstrations/textwrap11.yaml}[MLB-TCB]{\texttt{textwrap11.yaml}}{lst:textwrap11-yaml}
- \end{cmhtcbraster}
-
- \Cref{lst:textwrap9-yaml} and \cref{lst:textwrap10-yaml} are equivalent. Upon running
- the commands
- \index{switches!-l demonstration}
- \index{switches!-m demonstration}
- \begin{commandshell}
-latexindent.pl -s textwrap6.tex -l=textwrap9.yaml -m
-latexindent.pl -s textwrap6.tex -l=textwrap11.yaml -m
-\end{commandshell}
- we receive the respective output given in \cref{lst:textwrap6-mod9,lst:textwrap6-mod11}.
-
- \begin{widepage}
- \cmhlistingsfromfile{demonstrations/textwrap6-mod9.tex}{\texttt{textwrap6.tex} using \cref{lst:textwrap9-yaml}}{lst:textwrap6-mod9}
-
- \cmhlistingsfromfile*{demonstrations/textwrap6-mod11.tex}{\texttt{textwrap6.tex} using \cref{lst:textwrap11-yaml}}{lst:textwrap6-mod11}
- \end{widepage}
-
- Notice that:
- \begin{itemize}
- \item in \cref{lst:textwrap6-mod9} the text for the \texttt{masterDocument} has been
- wrapped using \texttt{30} columns, while \texttt{environments} has
- been wrapped using \texttt{50} columns;
- \item in \cref{lst:textwrap6-mod11} the text for \texttt{myenv} has been wrapped
- using \texttt{50} columns, the text for \texttt{another} has
- been wrapped using \texttt{15} columns, and \texttt{masterDocument}
- has been wrapped using \texttt{30} columns.
- \end{itemize}
- If you don't specify a \texttt{default} value on per-code-block basis, then
- the \texttt{default} value from \texttt{columns} will be inherited;
- if you don't specify a default value for \texttt{columns} then
- \texttt{80} will be used.
-
- \texttt{alignAtAmpersandTakesPriority} is set to \texttt{1} by default; assuming
- that text wrapping is occurring on a per-code-block basis, and the current
- environment/code block is specified within \vref{lst:aligndelims:basic} then text wrapping
- will be disabled for this code block.
-
- If you wish to specify \texttt{afterHeading} commands (see
- \vref{lst:indentAfterHeadings}) on a per-name basis, then you need to append the name with
- \texttt{:heading}, for example, you might use \texttt{section:heading}.
-
-\subsubsection{Summary of text wrapping}
- It is important to note the following:
- \index{verbatim!within summary of text wrapping}
- \begin{itemize}
- \item Verbatim environments (\vref{lst:verbatimEnvironments}) and verbatim commands
- (\vref{lst:verbatimCommands}) will \emph{not} be affected by the text
- wrapping routine (see \vref{lst:textwrap2-mod1});
- \item comments will \emph{not} be affected by the text wrapping routine (see
- \vref{lst:textwrap3-mod1});
- \item it is possible to wrap text on a per-code-block and a per-name basis;
- \announce{2018-08-13}*{updates to textWrapOptions}
- \item the text wrapping routine sets \texttt{preserveBlankLines} as
- \texttt{1};
- \item indentation is performed \emph{after} the text wrapping routine; as such,
- indented code will likely exceed any maximum value set in the \texttt{columns}
- field.
- \end{itemize}
-
-\subsection{oneSentencePerLine: modifying line breaks for sentences}\label{sec:onesentenceperline}
- You can instruct \texttt{latexindent.pl} to
- format%
- \announce{2018-01-13}{one sentence per line} your file so that
- it puts one sentence per line. Thank you to \cite{mlep} for helping to
- shape and test this feature. The behaviour of this part of the script is controlled by
- the switches detailed in \cref{lst:oneSentencePerLine}, all of which we discuss next.
- \index{modifying linebreaks! by using one sentence per line}
- \index{sentences!oneSentencePerLine}
- \index{sentences!one sentence per line}
- \index{regular expressions!lowercase alph a-z}
- \index{regular expressions!uppercase alph A-Z}
-
- \cmhlistingsfromfile[style=oneSentencePerLine]*{../defaultSettings.yaml}[MLB-TCB,width=.85\linewidth,before=\centering]{\texttt{oneSentencePerLine}}{lst:oneSentencePerLine}
-
-\yamltitle{manipulateSentences}{0|1}
- This is a binary switch that details if \texttt{latexindent.pl} should perform the
- sentence manipulation routine; it is \emph{off} (set to \texttt{0}) by default, and you will
- need to turn it on (by setting it to \texttt{1}) if you want the script
- to modify line breaks surrounding and within sentences.
-
-\yamltitle{removeSentenceLineBreaks}{0|1}
- When operating upon sentences \texttt{latexindent.pl} will, by default, remove
- internal line breaks as \texttt{removeSentenceLineBreaks} is set to
- \texttt{1}. Setting this switch to \texttt{0} instructs
- \texttt{latexindent.pl} not to do so.
- \index{sentences!removing sentence line breaks}
-
- For example, consider \texttt{multiple-sentences.tex} shown in \cref{lst:multiple-sentences}.
-
- \cmhlistingsfromfile{demonstrations/multiple-sentences.tex}{\texttt{multiple-sentences.tex}}{lst:multiple-sentences}
-
- If we use the YAML files in \cref{lst:manipulate-sentences-yaml,lst:keep-sen-line-breaks-yaml}, and run the commands
- \index{switches!-l demonstration}
- \index{switches!-m demonstration}
- \begin{widepage}
- \begin{commandshell}
-latexindent.pl multiple-sentences -m -l=manipulate-sentences.yaml
-latexindent.pl multiple-sentences -m -l=keep-sen-line-breaks.yaml
-\end{commandshell}
- \end{widepage}
- then we obtain the respective output given in \cref{lst:multiple-sentences-mod1,lst:multiple-sentences-mod2}.
-
- \begin{cmhtcbraster}
- \cmhlistingsfromfile{demonstrations/multiple-sentences-mod1.tex}{\texttt{multiple-sentences.tex} using \cref{lst:manipulate-sentences-yaml}}{lst:multiple-sentences-mod1}
- \cmhlistingsfromfile[style=yaml-LST]*{demonstrations/manipulate-sentences.yaml}[MLB-TCB]{\texttt{manipulate-sentences.yaml}}{lst:manipulate-sentences-yaml}
- \end{cmhtcbraster}
-
- \begin{cmhtcbraster}
- \cmhlistingsfromfile{demonstrations/multiple-sentences-mod2.tex}{\texttt{multiple-sentences.tex} using \cref{lst:keep-sen-line-breaks-yaml}}{lst:multiple-sentences-mod2}
- \cmhlistingsfromfile[style=yaml-LST]*{demonstrations/keep-sen-line-breaks.yaml}[MLB-TCB]{\texttt{keep-sen-line-breaks.yaml}}{lst:keep-sen-line-breaks-yaml}
- \end{cmhtcbraster}
-
- Notice, in particular, that the `internal' sentence line breaks in
- \cref{lst:multiple-sentences} have been removed in \cref{lst:multiple-sentences-mod1}, but have
- not been removed in \cref{lst:multiple-sentences-mod2}.
-
- The remainder of the settings displayed in \vref{lst:oneSentencePerLine} instruct
- \texttt{latexindent.pl} on how to define a sentence. From the perspective of
- \texttt{latexindent.pl} a sentence must:
- \index{sentences!follow}
- \index{sentences!begin with}
- \index{sentences!end with}
- \begin{itemize}
- \item \emph{follow} a certain character or set of characters (see
- \cref{lst:sentencesFollow}); by default, this is either \lstinline!\par!, a
- blank line, a full stop/period (.), exclamation mark (!), question mark (?) right brace
- (\}) or a comment on the previous line;
- \item \emph{begin} with a character type (see \cref{lst:sentencesBeginWith}); by
- default, this is only capital letters;
- \item \emph{end} with a character (see \cref{lst:sentencesEndWith}); by
- default, these are full stop/period (.), exclamation mark (!) and question mark (?).
- \end{itemize}
- In each case, you can specify the \texttt{other} field to include any
- pattern that you would like; you can specify anything in this field using the language of
- regular expressions.
- \index{regular expressions!lowercase alph a-z}
- \index{regular expressions!uppercase alph A-Z}
-
- \begin{cmhtcbraster}[raster columns=3,
- raster left skip=-3.5cm,
- raster right skip=-2cm,
- raster column skip=.06\linewidth]
- \cmhlistingsfromfile[style=sentencesFollow]*{../defaultSettings.yaml}[MLB-TCB,width=.9\linewidth,before=\centering]{\texttt{sentencesFollow}}{lst:sentencesFollow}
- \cmhlistingsfromfile[style=sentencesBeginWith]*{../defaultSettings.yaml}[MLB-TCB,width=.9\linewidth,before=\centering]{\texttt{sentencesBeginWith}}{lst:sentencesBeginWith}
- \cmhlistingsfromfile[style=sentencesEndWith]*{../defaultSettings.yaml}[MLB-TCB,width=.9\linewidth,before=\centering]{\texttt{sentencesEndWith}}{lst:sentencesEndWith}
- \end{cmhtcbraster}
-
-\subsubsection{sentencesFollow}
- Let's explore a few of the switches in \texttt{sentencesFollow}; let's start with
- \vref{lst:multiple-sentences}, and use the YAML settings given in
- \cref{lst:sentences-follow1-yaml}. Using the command
- \index{sentences!follow}
- \index{switches!-l demonstration}
- \index{switches!-m demonstration}
- \begin{commandshell}
-latexindent.pl multiple-sentences -m -l=sentences-follow1.yaml
-\end{commandshell}
- we obtain the output given in \cref{lst:multiple-sentences-mod3}.
-
- \begin{cmhtcbraster}
- \cmhlistingsfromfile{demonstrations/multiple-sentences-mod3.tex}{\texttt{multiple-sentences.tex} using \cref{lst:sentences-follow1-yaml}}{lst:multiple-sentences-mod3}
- \cmhlistingsfromfile[style=yaml-LST]*{demonstrations/sentences-follow1.yaml}[MLB-TCB]{\texttt{sentences-follow1.yaml}}{lst:sentences-follow1-yaml}
- \end{cmhtcbraster}
-
- Notice that, because \texttt{blankLine} is set to \texttt{0},
- \texttt{latexindent.pl} will not seek sentences following a blank line, and so the
- fourth sentence has not been accounted for.
-
- We can explore the \texttt{other} field in \cref{lst:sentencesFollow} with
- the \texttt{.tex} file detailed in \cref{lst:multiple-sentences1}.
-
- \cmhlistingsfromfile{demonstrations/multiple-sentences1.tex}{\texttt{multiple-sentences1.tex}}{lst:multiple-sentences1}
-
- Upon running the following commands
- \index{switches!-l demonstration}
- \index{switches!-m demonstration}
- \begin{widepage}
- \begin{commandshell}
-latexindent.pl multiple-sentences1 -m -l=manipulate-sentences.yaml
-latexindent.pl multiple-sentences1 -m -l=manipulate-sentences.yaml,sentences-follow2.yaml
-\end{commandshell}
- \end{widepage}
- then we obtain the respective output given in \cref{lst:multiple-sentences1-mod1,lst:multiple-sentences1-mod2}.
- \cmhlistingsfromfile{demonstrations/multiple-sentences1-mod1.tex}{\texttt{multiple-sentences1.tex} using \vref{lst:manipulate-sentences-yaml}}{lst:multiple-sentences1-mod1}
-
- \begin{cmhtcbraster}[
- raster force size=false,
- raster column 1/.style={add to width=1cm},
- ]
- \cmhlistingsfromfile{demonstrations/multiple-sentences1-mod2.tex}{\texttt{multiple-sentences1.tex} using \cref{lst:sentences-follow2-yaml}}{lst:multiple-sentences1-mod2}
- \cmhlistingsfromfile[style=yaml-LST]*{demonstrations/sentences-follow2.yaml}[MLB-TCB,width=.45\textwidth]{\texttt{sentences-follow2.yaml}}{lst:sentences-follow2-yaml}
- \end{cmhtcbraster}
-
- Notice that in \cref{lst:multiple-sentences1-mod1} the first sentence after the
- \texttt{)} has not been accounted for, but that following the inclusion
- of \cref{lst:sentences-follow2-yaml}, the output given in \cref{lst:multiple-sentences1-mod2}
- demonstrates that the sentence \emph{has} been accounted for correctly.
-
-\subsubsection{sentencesBeginWith}
- By default, \texttt{latexindent.pl} will only assume that sentences begin with the
- upper case letters \texttt{A-Z}; you can instruct the script to define
- sentences to begin with lower case letters (see \cref{lst:sentencesBeginWith}), and we can
- use the \texttt{other} field to define sentences to begin with other
- characters.
- \index{sentences!begin with}
-
- \cmhlistingsfromfile{demonstrations/multiple-sentences2.tex}{\texttt{multiple-sentences2.tex}}{lst:multiple-sentences2}
-
- Upon running the following commands
- \index{switches!-l demonstration}
- \index{switches!-m demonstration}
- \begin{widepage}
- \begin{commandshell}
-latexindent.pl multiple-sentences2 -m -l=manipulate-sentences.yaml
-latexindent.pl multiple-sentences2 -m -l=manipulate-sentences.yaml,sentences-begin1.yaml
-\end{commandshell}
- \end{widepage}
- then we obtain the respective output given in \cref{lst:multiple-sentences2-mod1,lst:multiple-sentences2-mod2}.
- \cmhlistingsfromfile{demonstrations/multiple-sentences2-mod1.tex}{\texttt{multiple-sentences2.tex} using \vref{lst:manipulate-sentences-yaml}}{lst:multiple-sentences2-mod1}
- \index{regular expressions!numeric 0-9}
-
- \begin{cmhtcbraster}[
- raster force size=false,
- raster column 1/.style={add to width=1cm},
- ]
- \cmhlistingsfromfile{demonstrations/multiple-sentences2-mod2.tex}{\texttt{multiple-sentences2.tex} using \cref{lst:sentences-begin1-yaml}}{lst:multiple-sentences2-mod2}
- \cmhlistingsfromfile[style=yaml-LST]*{demonstrations/sentences-begin1.yaml}[MLB-TCB,width=.45\textwidth]{\texttt{sentences-begin1.yaml}}{lst:sentences-begin1-yaml}
- \end{cmhtcbraster}
- Notice that in \cref{lst:multiple-sentences2-mod1}, the first sentence has been accounted for but
- that the subsequent sentences have not. In \cref{lst:multiple-sentences2-mod2}, all of the
- sentences have been accounted for, because the \texttt{other} field in
- \cref{lst:sentences-begin1-yaml} has defined sentences to begin with either
- \lstinline!$! or any numeric digit, \texttt{0} to
- \texttt{9}.
-
-\subsubsection{sentencesEndWith}
- Let's return to \vref{lst:multiple-sentences}; we have already seen the default way in
- which \texttt{latexindent.pl} will operate on the sentences in this file in
- \vref{lst:multiple-sentences-mod1}. We can populate the \texttt{other} field with
- any character that we wish; for example, using the YAML specified in
- \cref{lst:sentences-end1-yaml} and the command
- \index{sentences!end with}
- \index{switches!-l demonstration}
- \index{switches!-m demonstration}
- \begin{commandshell}
-latexindent.pl multiple-sentences -m -l=sentences-end1.yaml
-latexindent.pl multiple-sentences -m -l=sentences-end2.yaml
-\end{commandshell}
- then we obtain the output in \cref{lst:multiple-sentences-mod4}.
- \index{regular expressions!lowercase alph a-z}
-
- \begin{cmhtcbraster}
- \cmhlistingsfromfile{demonstrations/multiple-sentences-mod4.tex}{\texttt{multiple-sentences.tex} using \cref{lst:sentences-end1-yaml}}{lst:multiple-sentences-mod4}
- \cmhlistingsfromfile[style=yaml-LST]*{demonstrations/sentences-end1.yaml}[MLB-TCB]{\texttt{sentences-end1.yaml}}{lst:sentences-end1-yaml}
- \end{cmhtcbraster}
-
- \begin{cmhtcbraster}
- \cmhlistingsfromfile{demonstrations/multiple-sentences-mod5.tex}{\texttt{multiple-sentences.tex} using \cref{lst:sentences-end2-yaml}}{lst:multiple-sentences-mod5}
- \cmhlistingsfromfile[style=yaml-LST]*{demonstrations/sentences-end2.yaml}[MLB-TCB]{\texttt{sentences-end2.yaml}}{lst:sentences-end2-yaml}
- \end{cmhtcbraster}
-
- There is a subtle difference between the output in \cref{lst:multiple-sentences-mod4,lst:multiple-sentences-mod5}; in
- particular, in \cref{lst:multiple-sentences-mod4} the word \texttt{sentence} has not
- been defined as a sentence, because we have not instructed \texttt{latexindent.pl} to
- begin sentences with lower case letters. We have changed this by using the settings in
- \cref{lst:sentences-end2-yaml}, and the associated output in \cref{lst:multiple-sentences-mod5}
- reflects this.
-
- Referencing \vref{lst:sentencesEndWith}, you'll notice that there is a field called
- \texttt{basicFullStop}, which is set to \texttt{0}, and that the
- \texttt{betterFullStop} is set to \texttt{1} by default.
-
- Let's consider the file shown in \cref{lst:url}.
-
- \cmhlistingsfromfile{demonstrations/url.tex}{\texttt{url.tex}}{lst:url}
-
- Upon running the following commands
- \index{switches!-l demonstration}
- \index{switches!-m demonstration}
- \begin{commandshell}
-latexindent.pl url -m -l=manipulate-sentences.yaml
-\end{commandshell}
- we obtain the output given in \cref{lst:url-mod1}.
-
- \cmhlistingsfromfile{demonstrations/url-mod1.tex}{\texttt{url.tex} using \vref{lst:manipulate-sentences-yaml}}{lst:url-mod1}
-
- Notice that the full stop within the url has been interpreted correctly. This is because,
- within the \texttt{betterFullStop}, full stops at the end of sentences have the
- following properties:
- \begin{itemize}
- \item they are ignored within \texttt{e.g.} and \texttt{i.e.};
- \item they can not be immediately followed by a lower case or upper case letter;
- \item they can not be immediately followed by a hyphen, comma, or number.
- \end{itemize}
- If you find that the \texttt{betterFullStop} does not work for your purposes, then
- you can switch it off by setting it to \texttt{0}, and you can
- experiment with the \texttt{other}
- field.%
- \announce{2019-07-13}{fine tuning the betterFullStop} You can also seek
- to customise the \texttt{betterFullStop} routine by using the
- \emph{fine tuning}, detailed in \vref{lst:fineTuning}.
-
- The \texttt{basicFullStop} routine should probably be avoided in most situations, as
- it does not accommodate the specifications above. For example, using the following
- command
- \index{switches!-l demonstration}
- \index{switches!-m demonstration}
- \begin{commandshell}
-latexindent.pl url -m -l=alt-full-stop1.yaml
-\end{commandshell}
- and the YAML in \cref{lst:alt-full-stop1-yaml} gives the output in
- \cref{lst:url-mod2}.
-
- \begin{cmhtcbraster}[ raster left skip=-3.5cm,
- raster right skip=-2cm,
- raster force size=false,
- raster column 1/.style={add to width=.1\textwidth},
- raster column skip=.06\linewidth]
- \cmhlistingsfromfile{demonstrations/url-mod2.tex}{\texttt{url.tex} using \cref{lst:alt-full-stop1-yaml}}{lst:url-mod2}
- \cmhlistingsfromfile[style=yaml-LST]*{demonstrations/alt-full-stop1.yaml}[MLB-TCB,width=.5\textwidth]{\texttt{alt-full-stop1.yaml}}{lst:alt-full-stop1-yaml}
- \end{cmhtcbraster}
-
- Notice that the full stop within the URL has not been accommodated correctly because of
- the non-default settings in \cref{lst:alt-full-stop1-yaml}.
-
-\subsubsection{Features of the oneSentencePerLine routine}
- The sentence manipulation routine takes place \emph{after} verbatim
- \index{verbatim!in relation to oneSentencePerLine} environments, preamble and trailing comments have been
- accounted for; this means that any characters within these types of code blocks will not
- be part of the sentence manipulation routine.
-
- For example, if we begin with the \texttt{.tex} file in
- \cref{lst:multiple-sentences3}, and run the command
- \index{switches!-l demonstration}
- \index{switches!-m demonstration}
- \begin{commandshell}
-latexindent.pl multiple-sentences3 -m -l=manipulate-sentences.yaml
-\end{commandshell}
- then we obtain the output in \cref{lst:multiple-sentences3-mod1}. \cmhlistingsfromfile{demonstrations/multiple-sentences3.tex}{\texttt{multiple-sentences3.tex}}{lst:multiple-sentences3}
- \cmhlistingsfromfile{demonstrations/multiple-sentences3-mod1.tex}{\texttt{multiple-sentences3.tex} using \vref{lst:manipulate-sentences-yaml}}{lst:multiple-sentences3-mod1}
-
- Furthermore, if sentences run across environments then, by default, the line breaks
- internal to the sentence will be removed. For example, if we use the
- \texttt{.tex} file in \cref{lst:multiple-sentences4} and run the commands
- \index{switches!-l demonstration}
- \index{switches!-m demonstration}
- \begin{commandshell}
-latexindent.pl multiple-sentences4 -m -l=manipulate-sentences.yaml
-latexindent.pl multiple-sentences4 -m -l=keep-sen-line-breaks.yaml
-\end{commandshell}
- then we obtain the output in \cref{lst:multiple-sentences4-mod1,lst:multiple-sentences4-mod2}. \cmhlistingsfromfile{demonstrations/multiple-sentences4.tex}{\texttt{multiple-sentences4.tex}}{lst:multiple-sentences4}
- \begin{widepage}
- \cmhlistingsfromfile{demonstrations/multiple-sentences4-mod1.tex}{\texttt{multiple-sentences4.tex} using \vref{lst:manipulate-sentences-yaml}}{lst:multiple-sentences4-mod1}
- \end{widepage}
- \cmhlistingsfromfile{demonstrations/multiple-sentences4-mod2.tex}{\texttt{multiple-sentences4.tex} using \vref{lst:keep-sen-line-breaks-yaml}}{lst:multiple-sentences4-mod2}
- Once you've read \cref{sec:poly-switches}, you will know that you can accommodate the
- removal of internal sentence line breaks by using the YAML in \cref{lst:item-rules2-yaml}
- and the command
- \index{switches!-l demonstration}
- \index{switches!-m demonstration}
- \begin{commandshell}
-latexindent.pl multiple-sentences4 -m -l=item-rules2.yaml
-\end{commandshell}
- the output of which is shown in \cref{lst:multiple-sentences4-mod3}.
-
- \begin{cmhtcbraster}
- \cmhlistingsfromfile{demonstrations/multiple-sentences4-mod3.tex}{\texttt{multiple-sentences4.tex} using \cref{lst:item-rules2-yaml}}{lst:multiple-sentences4-mod3}
- \cmhlistingsfromfile[style=yaml-LST]*{demonstrations/item-rules2.yaml}[MLB-TCB]{\texttt{item-rules2.yaml}}{lst:item-rules2-yaml}
- \end{cmhtcbraster}
-
-\subsubsection{text wrapping and indenting sentences}
- The \texttt{oneSentencePerLine}%
- \announce{2018-08-13}{oneSentencePerline text wrap and indent} can be instructed to perform
- text wrapping and indentation upon sentences.
- \index{sentences!text wrapping}
- \index{sentences!indenting}
-
- Let's use the code in \cref{lst:multiple-sentences5}.
-
- \cmhlistingsfromfile{demonstrations/multiple-sentences5.tex}{\texttt{multiple-sentences5.tex}}{lst:multiple-sentences5}
-
- Referencing \cref{lst:sentence-wrap1-yaml}, and running the following command
- \index{switches!-l demonstration}
- \index{switches!-m demonstration}
- \begin{commandshell}
-latexindent.pl multiple-sentences5 -m -l=sentence-wrap1.yaml
-\end{commandshell}
- we receive the output given in \cref{lst:multiple-sentences5-mod1}.
-
- \begin{cmhtcbraster}[ raster left skip=-3.5cm,
- raster right skip=-2cm,
- raster force size=false,
- raster column 1/.style={add to width=.1\textwidth},
- raster column skip=.06\linewidth]
- \cmhlistingsfromfile{demonstrations/multiple-sentences5-mod1.tex}{\texttt{multiple-sentences5.tex} using \cref{lst:sentence-wrap1-yaml}}{lst:multiple-sentences5-mod1}
- \cmhlistingsfromfile[style=yaml-LST]*{demonstrations/sentence-wrap1.yaml}[MLB-TCB,width=0.5\textwidth]{\texttt{sentence-wrap1.yaml}}{lst:sentence-wrap1-yaml}
- \end{cmhtcbraster}
-
- If you wish to specify the \texttt{columns} field on a per-code-block basis
- for sentences, then you would use \texttt{sentence}; explicitly, starting with
- \vref{lst:textwrap9-yaml}, for example, you would replace/append
- \texttt{environments} with, for example, \texttt{sentence: 50}.
-
- If you specify \texttt{textWrapSentences} as 1, but do \emph{not}
- specify a value for \texttt{columns} then the text wrapping will
- \emph{not} operate on sentences, and you will see a warning in
- \texttt{indent.log}.
-
- The indentation of sentences requires that sentences are stored as code blocks. This
- means that you may need to tweak \vref{lst:sentencesEndWith}. Let's explore this in
- relation to \cref{lst:multiple-sentences6}.
-
- \cmhlistingsfromfile{demonstrations/multiple-sentences6.tex}{\texttt{multiple-sentences6.tex}}{lst:multiple-sentences6}
-
- By default, \texttt{latexindent.pl} will find the full-stop within the first
- \texttt{item}, which means that, upon running the following commands
- \index{switches!-l demonstration}
- \index{switches!-m demonstration}
- \index{switches!-y demonstration}
- \begin{commandshell}
-latexindent.pl multiple-sentences6 -m -l=sentence-wrap1.yaml
-latexindent.pl multiple-sentences6 -m -l=sentence-wrap1.yaml -y="modifyLineBreaks:oneSentencePerLine:sentenceIndent:''"
-\end{commandshell}
- we receive the respective output in \cref{lst:multiple-sentences6-mod1} and
- \cref{lst:multiple-sentences6-mod2}.
-
- \cmhlistingsfromfile{demonstrations/multiple-sentences6-mod1.tex}{\texttt{multiple-sentences6-mod1.tex} using \cref{lst:sentence-wrap1-yaml}}{lst:multiple-sentences6-mod1}
-
- \cmhlistingsfromfile{demonstrations/multiple-sentences6-mod2.tex}{\texttt{multiple-sentences6-mod2.tex} using \cref{lst:sentence-wrap1-yaml} and no sentence indentation}{lst:multiple-sentences6-mod2}
-
- We note that \cref{lst:multiple-sentences6-mod1} the \texttt{itemize} code block has
- \emph{not} been indented appropriately. This is because the
- oneSentencePerLine has been instructed to store sentences (because
- \cref{lst:sentence-wrap1-yaml}); each sentence is then searched for code blocks.
-
- We can tweak the settings in \vref{lst:sentencesEndWith} to ensure that full stops are
- not followed by \texttt{item} commands, and that the end of sentences
- contains \lstinline!\end{itemize}! as in \cref{lst:itemize-yaml} (if you intend to use this, ensure that you
- remove the line breaks from the \texttt{other} field).
- \index{regular expressions!lowercase alph a-z}
- \index{regular expressions!uppercase alph A-Z}
- \index{regular expressions!numeric 0-9}
- \index{regular expressions!horizontal space \textbackslash{h}}
-
- \cmhlistingsfromfile[style=yaml-LST]*{demonstrations/itemized.yaml}[MLB-TCB]{\texttt{itemize.yaml}}{lst:itemize-yaml}
-
- Upon running
- \index{switches!-l demonstration}
- \index{switches!-m demonstration}
- \begin{commandshell}
-latexindent.pl multiple-sentences6 -m -l=sentence-wrap1.yaml,itemize.yaml
-\end{commandshell}
- we receive the output in \cref{lst:multiple-sentences6-mod3}.
-
- \cmhlistingsfromfile{demonstrations/multiple-sentences6-mod3.tex}{\texttt{multiple-sentences6-mod3.tex} using \cref{lst:sentence-wrap1-yaml} and \cref{lst:itemize-yaml}}{lst:multiple-sentences6-mod3}
-
- Notice that the sentence has received indentation, and that the
- \texttt{itemize} code block has been found and indented correctly.
-
-\subsection{removeParagraphLineBreaks: modifying line breaks for paragraphs}\label{subsec:removeparagraphlinebreaks}
- When the \texttt{-m} switch is active \texttt{latexindent.pl} has the
- ability to remove line breaks%
- \announce{2017-05-27}{removeParagraphLineBreaks} from within paragraphs; the behaviour is controlled by the
- \texttt{removeParagraphLineBreaks} field, detailed in \cref{lst:removeParagraphLineBreaks}. Thank you to
- \cite{jowens} for shaping and assisting with the testing of this feature.
-\yamltitle{removeParagraphLineBreaks}*{fields}
- This feature is considered complimentary to the \texttt{oneSentencePerLine} feature
- described in \vref{sec:onesentenceperline}.
- \index{specialBeginEnd!removeParagraphLineBreaks}
-
- \cmhlistingsfromfile[style=removeParagraphLineBreaks]*{../defaultSettings.yaml}[MLB-TCB,width=.85\linewidth,before=\centering]{\texttt{removeParagraphLineBreaks}}{lst:removeParagraphLineBreaks}
-
- This routine can be turned on \emph{globally} for \emph{every}
- code block type known to \texttt{latexindent.pl}
- (see \vref{tab:code-blocks}) by using the
- \texttt{all} switch; by default, this switch is
- \emph{off}. Assuming that the \texttt{all} switch is off,
- then the routine can be controlled on a per-code-block-type basis, and within that, on a
- per-name basis. We will consider examples of each of these in turn, but before we do,
- let's specify what \texttt{latexindent.pl} considers as a paragraph:
- \begin{itemize}
- \item it must begin on its own line with either an alphabetic or numeric character, and not
- with any of the code-block types detailed in \vref{tab:code-blocks};
- \item it can include line breaks, but finishes when it meets either a blank line, a
- \lstinline!\par! command, or any of the user-specified settings in the
- \texttt{paragraphsStopAt} field, detailed in \vref{lst:paragraphsStopAt}.
- \end{itemize}
-
- Let's start with the \texttt{.tex} file in \cref{lst:shortlines},
- together with the YAML settings in \cref{lst:remove-para1-yaml}.
-
- \begin{cmhtcbraster}
- \cmhlistingsfromfile[showspaces=true]{demonstrations/shortlines.tex}{\texttt{shortlines.tex}}{lst:shortlines}
- \cmhlistingsfromfile{demonstrations/remove-para1.yaml}[MLB-TCB]{\texttt{remove-para1.yaml}}{lst:remove-para1-yaml}
- \end{cmhtcbraster}
-
- Upon running the command
- \index{switches!-l demonstration}
- \index{switches!-m demonstration}
- \index{switches!-o demonstration}
- \begin{commandshell}
-latexindent.pl -m shortlines.tex -o shortlines1.tex -l remove-para1.yaml
-\end{commandshell}
- then we obtain the output given in \cref{lst:shortlines1}.
-
- \cmhlistingsfromfile[showspaces=true]{demonstrations/shortlines1.tex}{\texttt{shortlines1.tex}}{lst:shortlines1}
-
- Keen readers may notice that some trailing white space must be present in the file in
- \cref{lst:shortlines} which has crept in to the output in
- \cref{lst:shortlines1}. This can be fixed using the YAML file in
- \vref{lst:removeTWS-before} and running, for example,
- \index{switches!-l demonstration}
- \index{switches!-m demonstration}
- \index{switches!-o demonstration}
- \begin{commandshell}
-latexindent.pl -m shortlines.tex -o shortlines1-tws.tex -l remove-para1.yaml,removeTWS-before.yaml
-\end{commandshell}
- in which case the output is as in \cref{lst:shortlines1-tws}; notice that the double
- spaces present in \cref{lst:shortlines1} have been addressed.
-
- \cmhlistingsfromfile[showspaces=true]{demonstrations/shortlines1-tws.tex}{\texttt{shortlines1-tws.tex}}{lst:shortlines1-tws}
-
- Keeping with the settings in \cref{lst:remove-para1-yaml}, we note that the
- \texttt{all} switch applies to \emph{all} code block
- types. So, for example, let's consider the files in \cref{lst:shortlines-mand,lst:shortlines-opt}
-
- \begin{cmhtcbraster}
- \cmhlistingsfromfile{demonstrations/shortlines-mand.tex}{\texttt{shortlines-mand.tex}}{lst:shortlines-mand}
- \cmhlistingsfromfile{demonstrations/shortlines-opt.tex}{\texttt{shortlines-opt.tex}}{lst:shortlines-opt}
- \end{cmhtcbraster}
-
- Upon running the commands
- \index{switches!-l demonstration}
- \index{switches!-m demonstration}
- \index{switches!-o demonstration}
- \begin{widepage}
- \begin{commandshell}
-latexindent.pl -m shortlines-mand.tex -o shortlines-mand1.tex -l remove-para1.yaml
-latexindent.pl -m shortlines-opt.tex -o shortlines-opt1.tex -l remove-para1.yaml
-\end{commandshell}
- \end{widepage}
-
- then we obtain the respective output given in \cref{lst:shortlines-mand1,lst:shortlines-opt1}.
-
- \cmhlistingsfromfile{demonstrations/shortlines-mand1.tex}{\texttt{shortlines-mand1.tex}}{lst:shortlines-mand1}
- \cmhlistingsfromfile{demonstrations/shortlines-opt1.tex}{\texttt{shortlines-opt1.tex}}{lst:shortlines-opt1}
-
- Assuming that we turn \emph{off} the \texttt{all} switch
- (by setting it to \texttt{0}), then we can control the behaviour of
- \texttt{removeParagraphLineBreaks} either on a per-code-block-type basis, or on a per-name
- basis.
-
- For example, let's use the code in \cref{lst:shortlines-envs}, and consider the settings
- in \cref{lst:remove-para2-yaml,lst:remove-para3-yaml}; note that in \cref{lst:remove-para2-yaml} we specify that
- \emph{every} environment should receive treatment from the routine, while
- in \cref{lst:remove-para3-yaml} we specify that \emph{only} the
- \texttt{one} environment should receive the treatment.
-
- \begin{minipage}{.45\linewidth}
- \cmhlistingsfromfile{demonstrations/shortlines-envs.tex}{\texttt{shortlines-envs.tex}}{lst:shortlines-envs}
- \end{minipage}
- \hfill
- \begin{minipage}{.49\linewidth}
- \cmhlistingsfromfile{demonstrations/remove-para2.yaml}[MLB-TCB]{\texttt{remove-para2.yaml}}{lst:remove-para2-yaml}
- \cmhlistingsfromfile{demonstrations/remove-para3.yaml}[MLB-TCB]{\texttt{remove-para3.yaml}}{lst:remove-para3-yaml}
- \end{minipage}
-
- Upon running the commands
- \index{switches!-l demonstration}
- \index{switches!-m demonstration}
- \index{switches!-o demonstration}
- \begin{widepage}
- \begin{commandshell}
-latexindent.pl -m shortlines-envs.tex -o shortlines-envs2.tex -l remove-para2.yaml
-latexindent.pl -m shortlines-envs.tex -o shortlines-envs3.tex -l remove-para3.yaml
-\end{commandshell}
- \end{widepage}
- then we obtain the respective output given in \cref{lst:shortlines-envs2,lst:shortlines-envs3}.
-
- \cmhlistingsfromfile{demonstrations/shortlines-envs2.tex}{\texttt{shortlines-envs2.tex}}{lst:shortlines-envs2}
- \cmhlistingsfromfile{demonstrations/shortlines-envs3.tex}{\texttt{shortlines-envs3.tex}}{lst:shortlines-envs3}
-
- The remaining code-block types can be customised in analogous ways, although note that
- \texttt{commands}, \texttt{keyEqualsValuesBracesBrackets}, \texttt{namedGroupingBracesBrackets},
- \texttt{UnNamedGroupingBracesBrackets} are controlled by the \texttt{optionalArguments} and the
- \texttt{mandatoryArguments}.
-
- The only special case is the \texttt{masterDocument} field; this is designed for
- `chapter'-type files that may contain paragraphs that are not within any other
- code-blocks. For example, consider the file in \cref{lst:shortlines-md}, with the YAML
- settings in \cref{lst:remove-para4-yaml}.
-
- \begin{cmhtcbraster}
- \cmhlistingsfromfile{demonstrations/shortlines-md.tex}{\texttt{shortlines-md.tex}}{lst:shortlines-md}
- \cmhlistingsfromfile{demonstrations/remove-para4.yaml}[MLB-TCB]{\texttt{remove-para4.yaml}}{lst:remove-para4-yaml}
- \end{cmhtcbraster}
-
- Upon running the following command
- \index{switches!-l demonstration}
- \index{switches!-m demonstration}
- \index{switches!-o demonstration}
- \begin{widepage}
- \begin{commandshell}
-latexindent.pl -m shortlines-md.tex -o shortlines-md4.tex -l remove-para4.yaml
-\end{commandshell}
- \end{widepage}
- then we obtain the output in \cref{lst:shortlines-md4}. \cmhlistingsfromfile{demonstrations/shortlines-md4.tex}{\texttt{shortlines-md4.tex}}{lst:shortlines-md4}
-
- Note%
- \announce{2018-08-13}*{updates to all in removeParagraphLineBreaks} that the
- \texttt{all} field can take the same exceptions detailed in
- \cref{lst:textwrap6-yaml}{lst:textwrap8-yaml}.
-
-\yamltitle{paragraphsStopAt}*{fields}
- The paragraph line break routine considers blank lines and the
- \lstinline|\par| command to be the end of a paragraph;
- \announce{2017-05-27}{paragraphsStopAt} you can fine tune the behaviour of the routine further by
- using the \texttt{paragraphsStopAt} fields, shown in \cref{lst:paragraphsStopAt}.
- \index{specialBeginEnd!paragraphsStopAt}
- \index{verbatim!in relation to paragraphsStopAt}
-
- \cmhlistingsfromfile[style=paragraphsStopAt]*{../defaultSettings.yaml}[MLB-TCB,width=.85\linewidth,before=\centering]{\texttt{paragraphsStopAt}}{lst:paragraphsStopAt}
-
- The fields specified in \texttt{paragraphsStopAt} tell \texttt{latexindent.pl} to
- stop the current paragraph when it reaches a line that \emph{begins} with
- any of the code-block types specified as \texttt{1} in
- \cref{lst:paragraphsStopAt}. By default, you'll see that the paragraph line break
- routine will stop when it reaches an environment or verbatim code block at the beginning
- of a line. It is \emph{not} possible to specify these fields on a
- per-name basis.
-
- Let's use the \texttt{.tex} file in \cref{lst:sl-stop}; we will,
- in turn, consider the settings in \cref{lst:stop-command-yaml,lst:stop-comment-yaml}.
-
- \begin{minipage}{.45\linewidth}
- \cmhlistingsfromfile{demonstrations/sl-stop.tex}{\texttt{sl-stop.tex}}{lst:sl-stop}
- \end{minipage}
- \hfill
- \begin{minipage}{.49\linewidth}
- \cmhlistingsfromfile{demonstrations/stop-command.yaml}[MLB-TCB]{\texttt{stop-command.yaml}}{lst:stop-command-yaml}
-
- \cmhlistingsfromfile{demonstrations/stop-comment.yaml}[MLB-TCB]{\texttt{stop-comment.yaml}}{lst:stop-comment-yaml}
- \end{minipage}
-
- Upon using the settings from \vref{lst:remove-para4-yaml} and running the commands
- \index{switches!-l demonstration}
- \index{switches!-m demonstration}
- \index{switches!-o demonstration}
- \begin{widepage}
- \begin{commandshell}
-latexindent.pl -m sl-stop.tex -o sl-stop4.tex -l remove-para4.yaml
-latexindent.pl -m sl-stop.tex -o sl-stop4-command.tex -l=remove-para4.yaml,stop-command.yaml
-latexindent.pl -m sl-stop.tex -o sl-stop4-comment.tex -l=remove-para4.yaml,stop-comment.yaml
-\end{commandshell}
- \end{widepage}
- we obtain the respective outputs in \crefrange{lst:sl-stop4}{lst:sl-stop4-comment}; notice in particular
- that:
- \begin{itemize}
- \item in \cref{lst:sl-stop4} the paragraph line break routine has included commands and
- comments;
- \item in \cref{lst:sl-stop4-command} the paragraph line break routine has
- \emph{stopped} at the \texttt{emph} command, because in
- \cref{lst:stop-command-yaml} we have specified \texttt{commands} to be
- \texttt{1}, and \texttt{emph} is at the beginning of a
- line;
- \item in \cref{lst:sl-stop4-comment} the paragraph line break routine has
- \emph{stopped} at the comments, because in \cref{lst:stop-comment-yaml} we
- have specified \texttt{comments} to be \texttt{1}, and the
- comment is at the beginning of a line.
- \end{itemize}
- In all outputs in \crefrange{lst:sl-stop4}{lst:sl-stop4-comment} we notice that the paragraph line break
- routine has stopped at \lstinline!\begin{myenv}! because, by default,
- \texttt{environments} is set to \texttt{1} in
- \vref{lst:paragraphsStopAt}.
-
- \cmhlistingsfromfile{demonstrations/sl-stop4.tex}{\texttt{sl-stop4.tex}}{lst:sl-stop4}
- \cmhlistingsfromfile{demonstrations/sl-stop4-command.tex}{\texttt{sl-stop4-command.tex}}{lst:sl-stop4-command}
- \cmhlistingsfromfile{demonstrations/sl-stop4-comment.tex}{\texttt{sl-stop4-comment.tex}}{lst:sl-stop4-comment}
-
-\subsection{Combining removeParagraphLineBreaks and textWrapOptions}\label{subsec:removeparagraphlinebreaks:and:textwrap}
-
- The%
- \announce{2018-08-13}{combine text wrap and remove paragraph line breaks} text wrapping
- routine (\vref{subsec:textwrapping}) and remove paragraph line breaks routine
- (\vref{subsec:removeparagraphlinebreaks}) can be combined.
-
- We motivate this feature with the code given in \cref{lst:textwrap7}.
-
- \cmhlistingsfromfile{demonstrations/textwrap7.tex}{\texttt{textwrap7.tex}}{lst:textwrap7}
-
- Applying the text wrap routine from \vref{subsec:textwrapping} with, for example,
- \vref{lst:textwrap3-yaml} gives the output in \cref{lst:textwrap7-mod3}.
-
- \cmhlistingsfromfile{demonstrations/textwrap7-mod3.tex}{\texttt{textwrap7.tex} using \cref{lst:textwrap3-yaml}}{lst:textwrap7-mod3}
-
- The text wrapping routine has behaved as expected, but it may be desired to remove
- paragraph line breaks \emph{before} performing the text wrapping routine.
- The desired behaviour can be achieved by employing the \texttt{beforeTextWrap}
- switch.
-
- Explicitly, using the settings in \cref{lst:textwrap12-yaml} and running the command
- \index{switches!-l demonstration}
- \index{switches!-m demonstration}
- \index{switches!-o demonstration}
- \begin{commandshell}
-latexindent.pl -m textwrap7.tex -l=textwrap12.yaml -o=+-mod12
-\end{commandshell}
- we obtain the output in \cref{lst:textwrap7-mod12}.
+ the output is shown in \cref{lst:mlb-bl-out}; note that the multiple blank lines have
+ been condensed into one blank line, and note also that we have used the \texttt{-m}
+ switch!
\begin{cmhtcbraster}
- \cmhlistingsfromfile{demonstrations/textwrap7-mod12.tex}{\texttt{textwrap7-mod12.tex}}{lst:textwrap7-mod12}
- \cmhlistingsfromfile{demonstrations/textwrap12.yaml}[MLB-TCB]{\texttt{textwrap12.yaml}}{lst:textwrap12-yaml}
- \end{cmhtcbraster}
-
- In \cref{lst:textwrap7-mod12} the paragraph line breaks have first been removed from
- \cref{lst:textwrap7}, and then the text wrapping routine has been applied. It is
- envisaged that variants of \cref{lst:textwrap12-yaml} will be among the most useful
- settings for these two features.
-
-\subsection{Poly-switches}\label{sec:poly-switches}
- Every other field in the \texttt{modifyLineBreaks} field uses poly-switches, and can
- take one of the following%
- \announce{2017-08-21}*{blank line poly-switch} integer values:
- \index{modifying linebreaks! using poly-switches}
- \index{poly-switches!definition}
- \index{poly-switches!values}
- \index{poly-switches!off by default: set to 0}
- \begin{description}
- \item[$-1$] \emph{remove mode}: line breaks before or after the
- \emph{<part of thing>} can be removed (assuming that \texttt{preserveBlankLines} is
- set to \texttt{0});
- \item[0] \emph{off mode}: line breaks will not be modified for the
- \emph{<part of thing>} under consideration;
- \item[1] \emph{add mode}: a line break will be added before or after the
- \emph{<part of thing>} under consideration, assuming that
- there is not already a line break before or after the \emph{<part of thing>};
- \item[2] \emph{comment then add mode}: a comment symbol will be added, followed by a line break
- before or after the \emph{<part of thing>} under consideration, assuming that there
- is not already a comment and line break before or after the \emph{<part of thing>};
- \item[3] \emph{add then blank line mode}%
- \announce{2017-08-21}{blank line poly-switch}: a line break will be added before or after the
- \emph{<part of thing>} under consideration, assuming that
- there is not already a line break before or after the \emph{<part of thing>},
- followed by a blank line;
- \item[4] \emph{add blank line mode}%
- \announce{2019-07-13}{blank line poly-switch}; a blank line will
- be added before or after the \emph{<part of thing>} under consideration, even if the
- \emph{<part of thing>} is already on its own line.
- \end{description}
- In the above, \emph{<part of thing>} refers to either the
- \emph{begin statement}, \emph{body} or
- \emph{end statement} of the code blocks detailed in \vref{tab:code-blocks}.
- All poly-switches are \emph{off} by default;
- \texttt{latexindent.pl} searches first of all for per-name settings, and then
- followed by global per-thing settings.
-
-\subsection{modifyLineBreaks for environments}\label{sec:modifylinebreaks-environments}
- We start by viewing a snippet of \texttt{defaultSettings.yaml} in
- \cref{lst:environments-mlb}; note that it contains \emph{global} settings
- (immediately after the \texttt{environments} field) and that
- \emph{per-name} settings are also allowed -- in the case of
- \cref{lst:environments-mlb}, settings for \texttt{equation*} have been
- specified for demonstration. Note that all poly-switches are \emph{off} (set to 0)
- by default.
- \index{poly-switches!default values}
- \index{poly-switches!environment global example}
- \index{poly-switches!environment per-code block example}
-
- \cmhlistingsfromfile[style=modifylinebreaksEnv]*{../defaultSettings.yaml}[width=.8\linewidth,before=\centering,MLB-TCB]{\texttt{environments}}{lst:environments-mlb}
-
- Let's begin with the simple example given in \cref{lst:env-mlb1-tex}; note that we
- have annotated key parts of the file using $\BeginStartsOnOwnLine$,
- $\BodyStartsOnOwnLine$, $\EndStartsOnOwnLine$ and $\EndFinishesWithLineBreak$,
- these will be related to fields specified in \cref{lst:environments-mlb}.
- \index{poly-switches!visualisation: $\BeginStartsOnOwnLine$, $\BodyStartsOnOwnLine$, $\EndStartsOnOwnLine$, $\EndFinishesWithLineBreak$}
-
- \begin{cmhlistings}[style=tcblatex,escapeinside={(*@}{@*)}]{\texttt{env-mlb1.tex}}{lst:env-mlb1-tex}
-before words(*@$\BeginStartsOnOwnLine$@*) \begin{myenv}(*@$\BodyStartsOnOwnLine$@*)body of myenv(*@$\EndStartsOnOwnLine$@*)\end{myenv}(*@$\EndFinishesWithLineBreak$@*) after words
-\end{cmhlistings}
-
-\subsubsection{Adding line breaks: BeginStartsOnOwnLine and BodyStartsOnOwnLine}
- Let's explore \texttt{BeginStartsOnOwnLine} and \texttt{BodyStartsOnOwnLine} in
- \cref{lst:env-mlb1,lst:env-mlb2}, and in particular, let's allow each of them in turn to take
- a value of $1$.
- \index{modifying linebreaks! at the \emph{beginning} of a code block}
- \index{poly-switches!adding line breaks: set to 1}
-
- \begin{minipage}{.45\textwidth}
- \cmhlistingsfromfile[style=yaml-LST]*{demonstrations/env-mlb1.yaml}[MLB-TCB]{\texttt{env-mlb1.yaml}}{lst:env-mlb1}
- \end{minipage}
- \hfill
- \begin{minipage}{.45\textwidth}
- \cmhlistingsfromfile[style=yaml-LST]*{demonstrations/env-mlb2.yaml}[MLB-TCB]{\texttt{env-mlb2.yaml}}{lst:env-mlb2}
- \end{minipage}
-
- After running the following commands,
- \index{switches!-l demonstration}
- \index{switches!-m demonstration}
- \begin{commandshell}
-latexindent.pl -m env-mlb.tex -l env-mlb1.yaml
-latexindent.pl -m env-mlb.tex -l env-mlb2.yaml
-\end{commandshell}
- the output is as in \cref{lst:env-mlb-mod1,lst:env-mlb-mod2} respectively.
-
- \begin{widepage}
- \begin{minipage}{.56\linewidth}
- \cmhlistingsfromfile{demonstrations/env-mlb-mod1.tex}{\texttt{env-mlb.tex} using \cref{lst:env-mlb1}}{lst:env-mlb-mod1}
- \end{minipage}
- \hfill
- \begin{minipage}{.43\linewidth}
- \cmhlistingsfromfile{demonstrations/env-mlb-mod2.tex}{\texttt{env-mlb.tex} using \cref{lst:env-mlb2}}{lst:env-mlb-mod2}
- \end{minipage}
- \end{widepage}
-
- There are a couple of points to note:
- \begin{itemize}
- \item in \cref{lst:env-mlb-mod1} a line break has been added at the point denoted by
- $\BeginStartsOnOwnLine$ in \cref{lst:env-mlb1-tex}; no other line breaks have been
- changed;
- \item in \cref{lst:env-mlb-mod2} a line break has been added at the point denoted by
- $\BodyStartsOnOwnLine$ in \cref{lst:env-mlb1-tex}; furthermore, note that the
- \emph{body} of \texttt{myenv} has received the appropriate
- (default) indentation.
- \end{itemize}
-
- Let's now change each of the \texttt{1} values in
- \cref{lst:env-mlb1,lst:env-mlb2} so that they are $2$ and save them
- into \texttt{env-mlb3.yaml} and \texttt{env-mlb4.yaml} respectively (see
- \cref{lst:env-mlb3,lst:env-mlb4}).
- \index{poly-switches!adding comments and then line breaks: set to 2}
-
- \begin{minipage}{.45\textwidth}
- \cmhlistingsfromfile[style=yaml-LST]*{demonstrations/env-mlb3.yaml}[MLB-TCB]{\texttt{env-mlb3.yaml}}{lst:env-mlb3}
- \end{minipage}
- \hfill
- \begin{minipage}{.45\textwidth}
- \cmhlistingsfromfile[style=yaml-LST]*{demonstrations/env-mlb4.yaml}[MLB-TCB]{\texttt{env-mlb4.yaml}}{lst:env-mlb4}
- \end{minipage}
-
- Upon running commands analogous to the above, we obtain \cref{lst:env-mlb-mod3,lst:env-mlb-mod4}.
-
- \begin{widepage}
- \begin{minipage}{.56\linewidth}
- \cmhlistingsfromfile{demonstrations/env-mlb-mod3.tex}{\texttt{env-mlb.tex} using \cref{lst:env-mlb3}}{lst:env-mlb-mod3}
- \end{minipage}
- \hfill
- \begin{minipage}{.43\linewidth}
- \cmhlistingsfromfile{demonstrations/env-mlb-mod4.tex}{\texttt{env-mlb.tex} using \cref{lst:env-mlb4}}{lst:env-mlb-mod4}
- \end{minipage}
- \end{widepage}
-
- Note that line breaks have been added as in \cref{lst:env-mlb-mod1,lst:env-mlb-mod2}, but this time a
- comment symbol has been added before adding the line break; in both cases, trailing
- horizontal space has been stripped before doing so.
-
- Let's%
- \announce{2017-08-21}{demonstration of blank line poly-switch (3)} now change each
- of the \texttt{1} values in \cref{lst:env-mlb1,lst:env-mlb2} so that they
- are $3$ and save them into \texttt{env-mlb5.yaml} and
- \texttt{env-mlb6.yaml} respectively (see \cref{lst:env-mlb5,lst:env-mlb6}).
- \index{poly-switches!adding blank lines: set to 3}
-
- \begin{minipage}{.45\textwidth}
- \cmhlistingsfromfile[style=yaml-LST]*{demonstrations/env-mlb5.yaml}[MLB-TCB]{\texttt{env-mlb5.yaml}}{lst:env-mlb5}
- \end{minipage}
- \hfill
- \begin{minipage}{.45\textwidth}
- \cmhlistingsfromfile[style=yaml-LST]*{demonstrations/env-mlb6.yaml}[MLB-TCB]{\texttt{env-mlb6.yaml}}{lst:env-mlb6}
- \end{minipage}
-
- Upon running commands analogous to the above, we obtain \cref{lst:env-mlb-mod5,lst:env-mlb-mod6}.
-
- \begin{widepage}
- \begin{minipage}{.56\linewidth}
- \cmhlistingsfromfile{demonstrations/env-mlb-mod5.tex}{\texttt{env-mlb.tex} using \cref{lst:env-mlb5}}{lst:env-mlb-mod5}
- \end{minipage}
- \hfill
- \begin{minipage}{.43\linewidth}
- \cmhlistingsfromfile{demonstrations/env-mlb-mod6.tex}{\texttt{env-mlb.tex} using \cref{lst:env-mlb6}}{lst:env-mlb-mod6}
- \end{minipage}
- \end{widepage}
-
- Note that line breaks have been added as in \cref{lst:env-mlb-mod1,lst:env-mlb-mod2}, but this time a
- \emph{blank line} has been added after adding the line break.
-
- Let's now change%
- \announce{2019-07-13}{demonstration of new blank line poly-switch} each
- of the \texttt{1} values in \cref{lst:env-mlb5,lst:env-mlb6} so that they
- are $4$ and save them into \texttt{env-beg4.yaml} and
- \texttt{env-body4.yaml} respectively (see \cref{lst:env-beg4,lst:env-body4}).
- \index{poly-switches!adding blank lines (again"!): set to 4}
-
- \begin{minipage}{.45\textwidth}
- \cmhlistingsfromfile[style=yaml-LST]*{demonstrations/env-beg4.yaml}[MLB-TCB]{\texttt{env-beg4.yaml}}{lst:env-beg4}
- \end{minipage}
- \hfill
- \begin{minipage}{.45\textwidth}
- \cmhlistingsfromfile[style=yaml-LST]*{demonstrations/env-body4.yaml}[MLB-TCB]{\texttt{env-body4.yaml}}{lst:env-body4}
- \end{minipage}
-
- We will demonstrate this poly-switch value using the code in
- \cref{lst:env-mlb1-text}.
-
- \cmhlistingsfromfile{demonstrations/env-mlb1.tex}{\texttt{env-mlb1.tex}}{lst:env-mlb1-text}
-
- Upon running the commands
- \index{switches!-l demonstration}
- \index{switches!-m demonstration}
- \begin{commandshell}
-latexindent.pl -m env-mlb1.tex -l env-beg4.yaml
-latexindent.pl -m env-mlb.1tex -l env-body4.yaml
-\end{commandshell}
-
- then we receive the respective outputs in \cref{lst:env-mlb1-beg4,lst:env-mlb1-body4}.
-
- \begin{cmhtcbraster}[raster column skip=.1\linewidth]
- \cmhlistingsfromfile{demonstrations/env-mlb1-beg4.tex}{\texttt{env-mlb1.tex} using \cref{lst:env-beg4}}{lst:env-mlb1-beg4}
- \cmhlistingsfromfile{demonstrations/env-mlb1-body4.tex}{\texttt{env-mlb1.tex} using \cref{lst:env-body4}}{lst:env-mlb1-body4}
- \end{cmhtcbraster}
-
- We note in particular that, by design, for this value of the poly-switches:
- \begin{enumerate}
- \item in \cref{lst:env-mlb1-beg4} a blank line has been inserted before the
- \lstinline!\begin! statement, even though the \lstinline!\begin!
- statement was already on its own line;
- \item in \cref{lst:env-mlb1-body4} a blank line has been inserted before the beginning of the
- \emph{body}, even though it already began on its own line.
- \end{enumerate}
-
-\subsubsection{Adding line breaks using EndStartsOnOwnLine and EndFinishesWithLineBreak}
- Let's explore \texttt{EndStartsOnOwnLine} and \texttt{EndFinishesWithLineBreak} in
- \cref{lst:env-mlb7,lst:env-mlb8}, and in particular, let's allow each of them in turn to take
- a value of $1$.
- \index{modifying linebreaks! at the \emph{end} of a code block}
- \index{poly-switches!adding line breaks: set to 1}
-
- \begin{minipage}{.49\textwidth}
- \cmhlistingsfromfile[style=yaml-LST]*{demonstrations/env-mlb7.yaml}[MLB-TCB]{\texttt{env-mlb7.yaml}}{lst:env-mlb7}
- \end{minipage}
- \hfill
- \begin{minipage}{.49\textwidth}
- \cmhlistingsfromfile[style=yaml-LST]*{demonstrations/env-mlb8.yaml}[MLB-TCB]{\texttt{env-mlb8.yaml}}{lst:env-mlb8}
- \end{minipage}
-
- After running the following commands,
- \index{switches!-l demonstration}
- \index{switches!-m demonstration}
- \begin{commandshell}
-latexindent.pl -m env-mlb.tex -l env-mlb7.yaml
-latexindent.pl -m env-mlb.tex -l env-mlb8.yaml
-\end{commandshell}
- the output is as in \cref{lst:env-mlb-mod7,lst:env-mlb-mod8}.
-
- \begin{widepage}
- \begin{minipage}{.42\linewidth}
- \cmhlistingsfromfile{demonstrations/env-mlb-mod7.tex}{\texttt{env-mlb.tex} using \cref{lst:env-mlb7}}{lst:env-mlb-mod7}
- \end{minipage}
- \hfill
- \begin{minipage}{.57\linewidth}
- \cmhlistingsfromfile{demonstrations/env-mlb-mod8.tex}{\texttt{env-mlb.tex} using \cref{lst:env-mlb8}}{lst:env-mlb-mod8}
- \end{minipage}
- \end{widepage}
-
- There are a couple of points to note:
- \begin{itemize}
- \item in \cref{lst:env-mlb-mod7} a line break has been added at the point denoted by
- $\EndStartsOnOwnLine$ in \vref{lst:env-mlb1-tex}; no other line breaks have been
- changed and the \lstinline!\end{myenv}! statement has \emph{not}
- received indentation (as intended);
- \item in \cref{lst:env-mlb-mod8} a line break has been added at the point denoted by
- $\EndFinishesWithLineBreak$ in \vref{lst:env-mlb1-tex}.
- \end{itemize}
-
- Let's now change each of the \texttt{1} values in
- \cref{lst:env-mlb7,lst:env-mlb8} so that they are $2$ and save them
- into \texttt{env-mlb9.yaml} and \texttt{env-mlb10.yaml} respectively (see
- \cref{lst:env-mlb9,lst:env-mlb10}).
- \index{poly-switches!adding comments and then line breaks: set to 2}
-
- \begin{minipage}{.49\textwidth}
- \cmhlistingsfromfile[style=yaml-LST]*{demonstrations/env-mlb9.yaml}[MLB-TCB]{\texttt{env-mlb9.yaml}}{lst:env-mlb9}
- \end{minipage}
- \hfill
- \begin{minipage}{.49\textwidth}
- \cmhlistingsfromfile[style=yaml-LST]*{demonstrations/env-mlb10.yaml}[MLB-TCB]{\texttt{env-mlb10.yaml}}{lst:env-mlb10}
- \end{minipage}
-
- Upon running commands analogous to the above, we obtain \cref{lst:env-mlb-mod9,lst:env-mlb-mod10}.
-
- \begin{widepage}
- \begin{minipage}{.43\linewidth}
- \cmhlistingsfromfile{demonstrations/env-mlb-mod9.tex}{\texttt{env-mlb.tex} using \cref{lst:env-mlb9}}{lst:env-mlb-mod9}
- \end{minipage}
- \hfill
- \begin{minipage}{.56\linewidth}
- \cmhlistingsfromfile{demonstrations/env-mlb-mod10.tex}{\texttt{env-mlb.tex} using \cref{lst:env-mlb10}}{lst:env-mlb-mod10}
- \end{minipage}
- \end{widepage}
-
- Note that line breaks have been added as in \cref{lst:env-mlb-mod7,lst:env-mlb-mod8}, but this time a
- comment symbol has been added before adding the line break; in both cases, trailing
- horizontal space has been stripped before doing so.
-
- Let's%
- \announce{2017-08-21}{demonstration of blank line poly-switch (3)} now change each
- of the \texttt{1} values in \cref{lst:env-mlb7,lst:env-mlb8} so that they
- are $3$ and save them into \texttt{env-mlb11.yaml} and
- \texttt{env-mlb12.yaml} respectively (see \cref{lst:env-mlb11,lst:env-mlb12}).
- \index{poly-switches!adding blank lines: set to 3}
-
- \begin{minipage}{.49\textwidth}
- \cmhlistingsfromfile[style=yaml-LST]*{demonstrations/env-mlb11.yaml}[MLB-TCB]{\texttt{env-mlb11.yaml}}{lst:env-mlb11}
- \end{minipage}
- \hfill
- \begin{minipage}{.49\textwidth}
- \cmhlistingsfromfile[style=yaml-LST]*{demonstrations/env-mlb12.yaml}[MLB-TCB]{\texttt{env-mlb12.yaml}}{lst:env-mlb12}
- \end{minipage}
-
- Upon running commands analogous to the above, we obtain \cref{lst:env-mlb-mod11,lst:env-mlb-mod12}.
-
- \begin{widepage}
- \begin{minipage}{.42\linewidth}
- \cmhlistingsfromfile{demonstrations/env-mlb-mod11.tex}{\texttt{env-mlb.tex} using \cref{lst:env-mlb11}}{lst:env-mlb-mod11}
- \end{minipage}
- \hfill
- \begin{minipage}{.57\linewidth}
- \cmhlistingsfromfile{demonstrations/env-mlb-mod12.tex}{\texttt{env-mlb.tex} using \cref{lst:env-mlb12}}{lst:env-mlb-mod12}
- \end{minipage}
- \end{widepage}
-
- Note that line breaks have been added as in \cref{lst:env-mlb-mod7,lst:env-mlb-mod8}, and that a
- \emph{blank line} has been added after the line break.
-
- Let's now change%
- \announce{2019-07-13}{demonstration of new blank line poly-switch} each
- of the \texttt{1} values in \cref{lst:env-mlb11,lst:env-mlb12} so that they
- are $4$ and save them into \texttt{env-end4.yaml} and
- \texttt{env-end-f4.yaml} respectively (see \cref{lst:env-end4,lst:env-end-f4}).
- \index{poly-switches!adding blank lines (again"!): set to 4}
-
- \begin{minipage}{.45\textwidth}
- \cmhlistingsfromfile[style=yaml-LST]*{demonstrations/env-end4.yaml}[MLB-TCB]{\texttt{env-end4.yaml}}{lst:env-end4}
- \end{minipage}
- \hfill
- \begin{minipage}{.5\textwidth}
- \cmhlistingsfromfile[style=yaml-LST]*{demonstrations/env-end-f4.yaml}[MLB-TCB]{\texttt{env-end-f4.yaml}}{lst:env-end-f4}
- \end{minipage}
-
- We will demonstrate this poly-switch value using the code from
- \vref{lst:env-mlb1-text}.
-
- Upon running the commands
- \index{switches!-l demonstration}
- \index{switches!-m demonstration}
- \begin{commandshell}
-latexindent.pl -m env-mlb1.tex -l env-end4.yaml
-latexindent.pl -m env-mlb.1tex -l env-end-f4.yaml
-\end{commandshell}
-
- then we receive the respective outputs in \cref{lst:env-mlb1-end4,lst:env-mlb1-end-f4}.
-
- \begin{cmhtcbraster}[raster column skip=.1\linewidth]
- \cmhlistingsfromfile{demonstrations/env-mlb1-end4.tex}{\texttt{env-mlb1.tex} using \cref{lst:env-end4}}{lst:env-mlb1-end4}
- \cmhlistingsfromfile{demonstrations/env-mlb1-end-f4.tex}{\texttt{env-mlb1.tex} using \cref{lst:env-end-f4}}{lst:env-mlb1-end-f4}
- \end{cmhtcbraster}
-
- We note in particular that, by design, for this value of the poly-switches:
- \begin{enumerate}
- \item in \cref{lst:env-mlb1-end4} a blank line has been inserted before the
- \lstinline!\end! statement, even though the \lstinline!\end!
- statement was already on its own line;
- \item in \cref{lst:env-mlb1-end-f4} a blank line has been inserted after the
- \lstinline!\end! statement, even though it already began on its own line.
- \end{enumerate}
-
-\subsubsection{poly-switches 1, 2, and 3 only add line breaks when necessary}
- If you ask \texttt{latexindent.pl} to add a line break (possibly with a comment)
- using a poly-switch value of $1$ (or $2$
- or $3$), it will only do so if necessary. For example, if you
- process the file in \vref{lst:mlb2} using poly-switch values of 1, 2, or 3,
- it will be left unchanged.
-
- \begin{minipage}{.45\linewidth}
- \cmhlistingsfromfile{demonstrations/env-mlb2.tex}{\texttt{env-mlb2.tex}}{lst:mlb2}
- \end{minipage}
- \hfill
- \begin{minipage}{.45\linewidth}
- \cmhlistingsfromfile{demonstrations/env-mlb3.tex}{\texttt{env-mlb3.tex}}{lst:mlb3}
- \end{minipage}
-
- Setting the poly-switches to a value of $4$ instructs
- \texttt{latexindent.pl} to add a line break even if the \emph{<part of thing>}
- is already on its own line; see \cref{lst:env-mlb1-beg4,lst:env-mlb1-body4} and
- \cref{lst:env-mlb1-end4,lst:env-mlb1-end-f4}.
-
- In contrast, the output from processing the file in \cref{lst:mlb3} will
- vary depending on the poly-switches used; in \cref{lst:env-mlb3-mod2} you'll see that
- the comment symbol after the \lstinline!\begin{myenv}! has been moved to the next line,
- as \texttt{BodyStartsOnOwnLine} is set to \texttt{1}. In
- \cref{lst:env-mlb3-mod4} you'll see that the comment has been accounted for correctly
- because \texttt{BodyStartsOnOwnLine} has been set to \texttt{2}, and
- the comment symbol has \emph{not} been moved to its own line. You're
- encouraged to experiment with \cref{lst:mlb3} and by setting the other
- poly-switches considered so far to \texttt{2} in turn.
-
- \begin{cmhtcbraster}[raster column skip=.1\linewidth]
- \cmhlistingsfromfile{demonstrations/env-mlb3-mod2.tex}{\texttt{env-mlb3.tex} using \vref{lst:env-mlb2}}{lst:env-mlb3-mod2}
- \cmhlistingsfromfile{demonstrations/env-mlb3-mod4.tex}{\texttt{env-mlb3.tex} using \vref{lst:env-mlb4}}{lst:env-mlb3-mod4}
- \end{cmhtcbraster}
-
- The details of the discussion in this section have concerned \emph{global}
- poly-switches in the \texttt{environments} field; each switch can also be
- specified on a \emph{per-name} basis, which would take priority over the
- global values; with reference to \vref{lst:environments-mlb}, an example is shown for
- the \texttt{equation*} environment.
-
-\subsubsection{Removing line breaks (poly-switches set to $-1$)}
- Setting poly-switches to $-1$ tells \texttt{latexindent.pl}
- to remove line breaks of the \emph{<part of the thing>}, if necessary. We will consider
- the example code given in \cref{lst:mlb4}, noting in particular the
- positions of the line break highlighters, $\BeginStartsOnOwnLine$,
- $\BodyStartsOnOwnLine$, $\EndStartsOnOwnLine$ and $\EndFinishesWithLineBreak$,
- together with the associated YAML files in \crefrange{lst:env-mlb13}{lst:env-mlb16}.
- \index{poly-switches!removing line breaks: set to -1}
-
- \begin{minipage}{.45\linewidth}
- \begin{cmhlistings}[style=tcblatex,escapeinside={(*@}{@*)}]{\texttt{env-mlb4.tex}}{lst:mlb4}
-before words(*@$\BeginStartsOnOwnLine$@*)
-\begin{myenv}(*@$\BodyStartsOnOwnLine$@*)
-body of myenv(*@$\EndStartsOnOwnLine$@*)
-\end{myenv}(*@$\EndFinishesWithLineBreak$@*)
-after words
-\end{cmhlistings}
- \end{minipage}%
- \hfill
- \begin{minipage}{.51\textwidth}
- \cmhlistingsfromfile[style=yaml-LST]*{demonstrations/env-mlb13.yaml}[MLB-TCB]{\texttt{env-mlb13.yaml}}{lst:env-mlb13}
-
- \cmhlistingsfromfile[style=yaml-LST]*{demonstrations/env-mlb14.yaml}[MLB-TCB]{\texttt{env-mlb14.yaml}}{lst:env-mlb14}
-
- \cmhlistingsfromfile[style=yaml-LST]*{demonstrations/env-mlb15.yaml}[MLB-TCB]{\texttt{env-mlb15.yaml}}{lst:env-mlb15}
-
- \cmhlistingsfromfile[style=yaml-LST]*{demonstrations/env-mlb16.yaml}[MLB-TCB]{\texttt{env-mlb16.yaml}}{lst:env-mlb16}
- \end{minipage}
-
- After running the commands
- \index{switches!-l demonstration}
- \index{switches!-m demonstration}
- \begin{commandshell}
-latexindent.pl -m env-mlb4.tex -l env-mlb13.yaml
-latexindent.pl -m env-mlb4.tex -l env-mlb14.yaml
-latexindent.pl -m env-mlb4.tex -l env-mlb15.yaml
-latexindent.pl -m env-mlb4.tex -l env-mlb16.yaml
-\end{commandshell}
-
- we obtain the respective output in \crefrange{lst:env-mlb4-mod13}{lst:env-mlb4-mod16}.
-
- \begin{minipage}{.45\linewidth}
- \cmhlistingsfromfile{demonstrations/env-mlb4-mod13.tex}{\texttt{env-mlb4.tex} using \cref{lst:env-mlb13}}{lst:env-mlb4-mod13}
- \end{minipage}
- \hfill
- \begin{minipage}{.45\linewidth}
- \cmhlistingsfromfile{demonstrations/env-mlb4-mod14.tex}{\texttt{env-mlb4.tex} using \cref{lst:env-mlb14}}{lst:env-mlb4-mod14}
- \end{minipage}
-
- \begin{minipage}{.45\linewidth}
- \cmhlistingsfromfile{demonstrations/env-mlb4-mod15.tex}{\texttt{env-mlb4.tex} using \cref{lst:env-mlb15}}{lst:env-mlb4-mod15}
- \end{minipage}
- \hfill
- \begin{minipage}{.45\linewidth}
- \cmhlistingsfromfile{demonstrations/env-mlb4-mod16.tex}{\texttt{env-mlb4.tex} using \cref{lst:env-mlb16}}{lst:env-mlb4-mod16}
- \end{minipage}
-
- Notice that in:
- \begin{itemize}
- \item \cref{lst:env-mlb4-mod13} the line break denoted by $\BeginStartsOnOwnLine$ in
- \cref{lst:mlb4} has been removed;
- \item \cref{lst:env-mlb4-mod14} the line break denoted by $\BodyStartsOnOwnLine$ in
- \cref{lst:mlb4} has been removed;
- \item \cref{lst:env-mlb4-mod15} the line break denoted by $\EndStartsOnOwnLine$ in
- \cref{lst:mlb4} has been removed;
- \item \cref{lst:env-mlb4-mod16} the line break denoted by $\EndFinishesWithLineBreak$ in
- \cref{lst:mlb4} has been removed.
- \end{itemize}
- We examined each of these cases separately for clarity of explanation, but you can
- combine all of the YAML settings in \crefrange{lst:env-mlb13}{lst:env-mlb16} into one file;
- alternatively, you could tell \texttt{latexindent.pl} to load them all by using the
- following command, for example
- \index{switches!-l demonstration}
- \index{switches!-m demonstration}
- \begin{widepage}
- \begin{commandshell}
-latexindent.pl -m env-mlb4.tex -l env-mlb13.yaml,env-mlb14.yaml,env-mlb15.yaml,env-mlb16.yaml
-\end{commandshell}
- \end{widepage}
- which gives the output in \vref{lst:env-mlb1-tex}.
-
-\subsubsection{About trailing horizontal space}
- Recall that on \cpageref{yaml:removeTrailingWhitespace} we discussed the YAML field
- \texttt{removeTrailingWhitespace}, and that it has two (binary) switches to determine if
- horizontal space should be removed \texttt{beforeProcessing} and
- \texttt{afterProcessing}. The \texttt{beforeProcessing} is particularly relevant
- when considering the \texttt{-m} switch; let's consider the file shown
- in \cref{lst:mlb5}, which highlights trailing spaces.
-
- \begin{cmhtcbraster}
- \begin{cmhlistings}[style=tcblatex,showspaces=true,escapeinside={(*@}{@*)}]{\texttt{env-mlb5.tex}}{lst:mlb5}
-before words (*@$\BeginStartsOnOwnLine$@*)
-\begin{myenv} (*@$\BodyStartsOnOwnLine$@*)
-body of myenv (*@$\EndStartsOnOwnLine$@*)
-\end{myenv} (*@$\EndFinishesWithLineBreak$@*)
-after words
-\end{cmhlistings}
- \cmhlistingsfromfile[style=yaml-LST]*{demonstrations/removeTWS-before.yaml}[yaml-TCB]{\texttt{removeTWS-before.yaml}}{lst:removeTWS-before}
- \end{cmhtcbraster}
-
- The output from the following commands
- \index{switches!-l demonstration}
- \index{switches!-m demonstration}
- \begin{widepage}
- \begin{commandshell}
-latexindent.pl -m env-mlb5.tex -l env-mlb13.yaml,env-mlb14.yaml,env-mlb15.yaml,env-mlb16.yaml
-latexindent.pl -m env-mlb5.tex -l env-mlb13.yaml,env-mlb14.yaml,env-mlb15.yaml,env-mlb16.yaml,removeTWS-before.yaml
-\end{commandshell}
- \end{widepage}
- is shown, respectively, in \cref{lst:env-mlb5-modAll,lst:env-mlb5-modAll-remove-WS}; note that the trailing
- horizontal white space has been preserved (by default) in \cref{lst:env-mlb5-modAll},
- while in \cref{lst:env-mlb5-modAll-remove-WS}, it has been removed using the switch specified in
- \cref{lst:removeTWS-before}.
-
- \begin{widepage}
- \cmhlistingsfromfile[showspaces=true]{demonstrations/env-mlb5-modAll.tex}{\texttt{env-mlb5.tex} using \crefrange{lst:env-mlb4-mod13}{lst:env-mlb4-mod16}}{lst:env-mlb5-modAll}
-
- \cmhlistingsfromfile[showspaces=true]{demonstrations/env-mlb5-modAll-remove-WS.tex}{\texttt{env-mlb5.tex} using \crefrange{lst:env-mlb4-mod13}{lst:env-mlb4-mod16} \emph{and} \cref{lst:removeTWS-before}}{lst:env-mlb5-modAll-remove-WS}
- \end{widepage}
-
-\subsubsection{poly-switch line break removal and blank lines}
- Now let's consider the file in \cref{lst:mlb6}, which contains blank lines.
- \index{poly-switches!blank lines}
-
- \begin{cmhtcbraster}
- \begin{cmhlistings}[style=tcblatex,escapeinside={(*@}{@*)}]{\texttt{env-mlb6.tex}}{lst:mlb6}
-before words(*@$\BeginStartsOnOwnLine$@*)
-
-
-\begin{myenv}(*@$\BodyStartsOnOwnLine$@*)
-
-
-body of myenv(*@$\EndStartsOnOwnLine$@*)
-
-
-\end{myenv}(*@$\EndFinishesWithLineBreak$@*)
-
-after words
-\end{cmhlistings}
- \cmhlistingsfromfile[style=yaml-LST]*{demonstrations/UnpreserveBlankLines.yaml}[MLB-TCB]{\texttt{UnpreserveBlankLines.yaml}}{lst:UnpreserveBlankLines}
- \end{cmhtcbraster}
-
- Upon running the following commands
- \index{switches!-l demonstration}
- \index{switches!-m demonstration}
- \begin{widepage}
- \begin{commandshell}
-latexindent.pl -m env-mlb6.tex -l env-mlb13.yaml,env-mlb14.yaml,env-mlb15.yaml,env-mlb16.yaml
-latexindent.pl -m env-mlb6.tex -l env-mlb13.yaml,env-mlb14.yaml,env-mlb15.yaml,env-mlb16.yaml,UnpreserveBlankLines.yaml
-\end{commandshell}
- \end{widepage}
- we receive the respective outputs in \cref{lst:env-mlb6-modAll,lst:env-mlb6-modAll-un-Preserve-Blank-Lines}. In
- \cref{lst:env-mlb6-modAll} we see that the multiple blank lines have each been
- condensed into one blank line, but that blank lines have \emph{not}
- been removed by the poly-switches -- this is because, by default,
- \texttt{preserveBlankLines} is set to \texttt{1}. By contrast, in
- \cref{lst:env-mlb6-modAll-un-Preserve-Blank-Lines}, we have allowed the poly-switches to remove blank lines
- because, in \cref{lst:UnpreserveBlankLines}, we have set \texttt{preserveBlankLines} to
- \texttt{0}.
-
- \begin{cmhtcbraster}[ raster left skip=-3.5cm,
- raster right skip=-2cm,
- raster force size=false,
- raster column 1/.style={add to width=-.2\textwidth},
- raster column 2/.style={add to width=.2\textwidth},
- raster column skip=.06\linewidth]
- \cmhlistingsfromfile{demonstrations/env-mlb6-modAll.tex}{\texttt{env-mlb6.tex} using \crefrange{lst:env-mlb4-mod13}{lst:env-mlb4-mod16}}{lst:env-mlb6-modAll}
- \cmhlistingsfromfile{demonstrations/env-mlb6-modAll-un-Preserve-Blank-Lines.tex}{\texttt{env-mlb6.tex} using \crefrange{lst:env-mlb4-mod13}{lst:env-mlb4-mod16} \emph{and} \cref{lst:UnpreserveBlankLines}}{lst:env-mlb6-modAll-un-Preserve-Blank-Lines}
- \end{cmhtcbraster}
-
- We can explore this further using the blank-line poly-switch value of
- $3$; let's use the file given in \cref{lst:env-mlb7-tex}.
-
- \cmhlistingsfromfile{demonstrations/env-mlb7.tex}{\texttt{env-mlb7.tex}}{lst:env-mlb7-tex}
-
- Upon running the following commands
- \index{switches!-l demonstration}
- \index{switches!-m demonstration}
- \begin{commandshell}
-latexindent.pl -m env-mlb7.tex -l env-mlb12.yaml,env-mlb13.yaml
-latexindent.pl -m env-mlb7.tex -l env-mlb13.yaml,env-mlb14.yaml,UnpreserveBlankLines.yaml
-\end{commandshell}
- we receive the outputs given in \cref{lst:env-mlb7-preserve,lst:env-mlb7-no-preserve}.
-
- \cmhlistingsfromfile{demonstrations/env-mlb7-preserve.tex}{\texttt{env-mlb7-preserve.tex}}{lst:env-mlb7-preserve}
- \cmhlistingsfromfile{demonstrations/env-mlb7-no-preserve.tex}{\texttt{env-mlb7-no-preserve.tex}}{lst:env-mlb7-no-preserve}
-
- Notice that in:
- \begin{itemize}
- \item \cref{lst:env-mlb7-preserve} that \lstinline!\end{one}! has added a blank line,
- because of the value of \texttt{EndFinishesWithLineBreak} in \vref{lst:env-mlb12}, and
- even though the line break ahead of \lstinline!\begin{two}! should have been removed
- (because of \texttt{BeginStartsOnOwnLine} in \vref{lst:env-mlb13}), the blank line
- has been preserved by default;
- \item \cref{lst:env-mlb7-no-preserve}, by contrast, has had the additional line-break removed,
- because of the settings in \cref{lst:UnpreserveBlankLines}.
- \end{itemize}
-
-\subsection{Poly-switches for double back slash}\label{subsec:dbs}
- With reference to \texttt{lookForAlignDelims} (see \vref{lst:aligndelims:basic})%
- \announce{2019-07-13}{poly-switch for double back slash} you can
- specify poly-switches to dictate the line-break behaviour of double back slashes in
- environments (\vref{lst:tabularafter:basic}), commands (\vref{lst:matrixafter}), or
- special code blocks (\vref{lst:specialafter}). Note that for these poly-switches to
- take effect, the name of the code block must necessarily be specified within
- \texttt{lookForAlignDelims} (\vref{lst:aligndelims:basic}); we will demonstrate this in what follows.
- \index{delimiters!poly-switches for double back slash}
- \index{modifying linebreaks! surrounding double back slash}
- \index{poly-switches!for double back slash (delimiters)}
-
- Consider the code given in \cref{lst:dbs-demo}.
- \begin{cmhlistings}[style=tcblatex,escapeinside={(*@}{@*)}]{\texttt{tabular3.tex}}{lst:dbs-demo}
-\begin{tabular}{cc}
- 1 & 2 (*@$\ElseStartsOnOwnLine$@*)\\(*@$\ElseFinishesWithLineBreak$@*) 3 & 4 (*@$\ElseStartsOnOwnLine$@*)\\(*@$\ElseFinishesWithLineBreak$@*)
-\end{tabular}
-\end{cmhlistings}
- Referencing \cref{lst:dbs-demo}:
- \begin{itemize}
- \item \texttt{DBS} stands for \emph{double back slash};
- \item line breaks ahead of the double back slash are annotated by $\ElseStartsOnOwnLine$,
- and are controlled by \texttt{DBSStartsOnOwnLine};
- \item line breaks after the double back slash are annotated by $\ElseFinishesWithLineBreak$, and
- are controlled by \texttt{DBSFinishesWithLineBreak}.
- \end{itemize}
-
- Let's explore each of these in turn.
-
-\subsubsection{Double back slash starts on own line}
- We explore \texttt{DBSStartsOnOwnLine} ($\ElseStartsOnOwnLine$ in \cref{lst:dbs-demo}); starting with the code in
- \cref{lst:dbs-demo}, together with the YAML files given in
- \cref{lst:DBS1} and \cref{lst:DBS2} and running the following
- commands
- \index{switches!-l demonstration}
- \index{switches!-m demonstration}
- \begin{commandshell}
-latexindent.pl -m tabular3.tex -l DBS1.yaml
-latexindent.pl -m tabular3.tex -l DBS2.yaml
-\end{commandshell}
- then we receive the respective output given in \cref{lst:tabular3-DBS1} and
- \cref{lst:tabular3-DBS2}.
-
- \begin{cmhtcbraster}[raster column skip=.01\linewidth]
- \cmhlistingsfromfile{demonstrations/tabular3-mod1.tex}{\texttt{tabular3.tex} using \cref{lst:DBS1}}{lst:tabular3-DBS1}
- \cmhlistingsfromfile[style=yaml-LST]*{demonstrations/DBS1.yaml}[MLB-TCB]{\texttt{DBS1.yaml}}{lst:DBS1}
- \end{cmhtcbraster}
-
- \begin{cmhtcbraster}[raster column skip=.01\linewidth]
- \cmhlistingsfromfile{demonstrations/tabular3-mod2.tex}{\texttt{tabular3.tex} using \cref{lst:DBS2}}{lst:tabular3-DBS2}
- \cmhlistingsfromfile[style=yaml-LST]*{demonstrations/DBS2.yaml}[MLB-TCB]{\texttt{DBS2.yaml}}{lst:DBS2}
- \end{cmhtcbraster}
-
- We note that
- \begin{itemize}
- \item \cref{lst:DBS1} specifies \texttt{DBSStartsOnOwnLine} for
- \emph{every} environment (that is within \texttt{lookForAlignDelims},
- \vref{lst:aligndelims:advanced});
- the double back slashes from \cref{lst:dbs-demo} have been moved to their own
- line in \cref{lst:tabular3-DBS1};
- \item \cref{lst:DBS2} specifies \texttt{DBSStartsOnOwnLine} on a
- \emph{per-name} basis for \texttt{tabular} (that is within \texttt{lookForAlignDelims}, \vref{lst:aligndelims:advanced});
- the double back slashes from \cref{lst:dbs-demo} have been moved to their own
- line in \cref{lst:tabular3-DBS2}, having added comment symbols before moving them.
- \end{itemize}
-
-\subsubsection{Double back slash finishes with line break}
- Let's now explore \texttt{DBSFinishesWithLineBreak} ($\ElseFinishesWithLineBreak$ in \cref{lst:dbs-demo}); starting with the code in
- \cref{lst:dbs-demo}, together with the YAML files given in
- \cref{lst:DBS3} and \cref{lst:DBS4} and running the following
- commands
- \index{poly-switches!for double back slash (delimiters)}
- \index{switches!-l demonstration}
- \index{switches!-m demonstration}
- \begin{commandshell}
-latexindent.pl -m tabular3.tex -l DBS3.yaml
-latexindent.pl -m tabular3.tex -l DBS4.yaml
-\end{commandshell}
- then we receive the respective output given in \cref{lst:tabular3-DBS3} and
- \cref{lst:tabular3-DBS4}.
-
- \begin{cmhtcbraster}[raster column skip=.01\linewidth]
- \cmhlistingsfromfile{demonstrations/tabular3-mod3.tex}{\texttt{tabular3.tex} using \cref{lst:DBS3}}{lst:tabular3-DBS3}
- \cmhlistingsfromfile[style=yaml-LST]*{demonstrations/DBS3.yaml}[MLB-TCB]{\texttt{DBS3.yaml}}{lst:DBS3}
- \end{cmhtcbraster}
-
- \begin{cmhtcbraster}[raster column skip=.01\linewidth]
- \cmhlistingsfromfile{demonstrations/tabular3-mod4.tex}{\texttt{tabular3.tex} using \cref{lst:DBS4}}{lst:tabular3-DBS4}
- \cmhlistingsfromfile[style=yaml-LST]*{demonstrations/DBS4.yaml}[MLB-TCB]{\texttt{DBS4.yaml}}{lst:DBS4}
- \end{cmhtcbraster}
-
- We note that
- \begin{itemize}
- \item \cref{lst:DBS3} specifies \texttt{DBSFinishesWithLineBreak} for
- \emph{every} environment (that is within \texttt{lookForAlignDelims},
- \vref{lst:aligndelims:advanced});
- the code following the double back slashes from \cref{lst:dbs-demo} has been
- moved to their own line in \cref{lst:tabular3-DBS3};
- \item \cref{lst:DBS4} specifies \texttt{DBSFinishesWithLineBreak} on a
- \emph{per-name} basis for \texttt{tabular} (that is within \texttt{lookForAlignDelims}, \vref{lst:aligndelims:advanced});
- the first double back slashes from \cref{lst:dbs-demo} have moved code following
- them to their own line in \cref{lst:tabular3-DBS4}, having added comment symbols
- before moving them; the final double back slashes have \emph{not} added
- a line break as they are at the end of the body within the code block.
- \end{itemize}
-
-\subsubsection{Double back slash poly-switches for specialBeginEnd}
- Let's explore the double back slash poly-switches for code blocks within
- \texttt{specialBeginEnd} code blocks (\vref{lst:specialBeginEnd}); we begin with
- the code within \cref{lst:special4}.
- \index{specialBeginEnd!double backslash poly-switch demonstration}
- \index{poly-switches!double backslash}
- \index{poly-switches!for double back slash (delimiters)}
- \index{specialBeginEnd!lookForAlignDelims}
- \index{delimiters}
- \index{linebreaks!summary of poly-switches}
-
- \cmhlistingsfromfile{demonstrations/special4.tex}{\texttt{special4.tex}}{lst:special4}
-
- Upon using the YAML settings in \cref{lst:DBS5}, and running the command
- \index{switches!-l demonstration}
- \index{switches!-m demonstration}
- \begin{commandshell}
-latexindent.pl -m special4.tex -l DBS5.yaml
-\end{commandshell}
- then we receive the output given in \cref{lst:special4-DBS5}.
- \index{delimiters!with specialBeginEnd and the -m switch}
-
- \begin{cmhtcbraster}[
- raster force size=false,
- raster column 1/.style={add to width=-.1\textwidth},
- raster column skip=.06\linewidth]
- \cmhlistingsfromfile{demonstrations/special4-mod5.tex}{\texttt{special4.tex} using \cref{lst:DBS5}}{lst:special4-DBS5}
- \cmhlistingsfromfile[style=yaml-LST]*{demonstrations/DBS5.yaml}[MLB-TCB,width=0.6\textwidth]{\texttt{DBS5.yaml}}{lst:DBS5}
- \end{cmhtcbraster}
-
- There are a few things to note:
- \begin{itemize}
- \item in \cref{lst:DBS5} we have specified \texttt{cmhMath} within
- \texttt{lookForAlignDelims}; without this, the double back slash poly-switches would be
- ignored for this code block;
- \item the \texttt{DBSFinishesWithLineBreak} poly-switch has controlled the line breaks following the
- double back slashes;
- \item the \texttt{SpecialEndStartsOnOwnLine} poly-switch has controlled the addition of a comment
- symbol, followed by a line break, as it is set to a value of 2.
- \end{itemize}
-
-\subsubsection{Double back slash poly-switches for optional and mandatory arguments}
- For clarity, we provide a demonstration of controlling the double back slash
- poly-switches for optional and mandatory arguments. We begin with the code in
- \cref{lst:mycommand2}.
- \index{poly-switches!for double back slash (delimiters)}
-
- \cmhlistingsfromfile{demonstrations/mycommand2.tex}{\texttt{mycommand2.tex}}{lst:mycommand2}
-
- Upon using the YAML settings in \cref{lst:DBS6,lst:DBS7}, and running the command
- \index{switches!-l demonstration}
- \index{switches!-m demonstration}
- \begin{commandshell}
-latexindent.pl -m mycommand2.tex -l DBS6.yaml
-latexindent.pl -m mycommand2.tex -l DBS7.yaml
-\end{commandshell}
- then we receive the output given in \cref{lst:mycommand2-DBS6,lst:mycommand2-DBS7}.
-
- \begin{cmhtcbraster}[
- raster force size=false,
- raster column 1/.style={add to width=-.1\textwidth},
- raster column skip=.03\linewidth]
- \cmhlistingsfromfile{demonstrations/mycommand2-mod6.tex}{\texttt{mycommand2.tex} using \cref{lst:DBS6}}{lst:mycommand2-DBS6}
- \cmhlistingsfromfile[style=yaml-LST]*{demonstrations/DBS6.yaml}[MLB-TCB,width=0.6\textwidth]{\texttt{DBS6.yaml}}{lst:DBS6}
- \end{cmhtcbraster}
-
- \begin{cmhtcbraster}[
- raster force size=false,
- raster column 1/.style={add to width=-.1\textwidth},
- raster column skip=.03\linewidth]
- \cmhlistingsfromfile{demonstrations/mycommand2-mod7.tex}{\texttt{mycommand2.tex} using \cref{lst:DBS7}}{lst:mycommand2-DBS7}
- \cmhlistingsfromfile[style=yaml-LST]*{demonstrations/DBS7.yaml}[MLB-TCB,width=0.6\textwidth]{\texttt{DBS7.yaml}}{lst:DBS7}
+ \cmhlistingsfromfile{demonstrations/mlb1.tex}{\texttt{mlb1.tex}}{lst:mlb-bl}
+ \cmhlistingsfromfile{demonstrations/mlb1-out.tex}{\texttt{mlb1-mod1.tex}}{lst:mlb-bl-out}
\end{cmhtcbraster}
-
-\subsubsection{Double back slash optional square brackets}
- The pattern matching for the double back slash will also, optionally, allow trailing
- square brackets that contain a measurement of vertical spacing, for example
- \lstinline!\\[3pt]!.
- \index{poly-switches!for double back slash (delimiters)}
-
- For example, beginning with the code in \cref{lst:pmatrix3}
-
- \cmhlistingsfromfile{demonstrations/pmatrix3.tex}{\texttt{pmatrix3.tex}}{lst:pmatrix3}
-
- and running the following command, using \cref{lst:DBS3},
- \index{switches!-l demonstration}
- \index{switches!-m demonstration}
- \begin{commandshell}
-latexindent.pl -m pmatrix3.tex -l DBS3.yaml
-\end{commandshell}
- then we receive the output given in \cref{lst:pmatrix3-DBS3}.
-
- \cmhlistingsfromfile{demonstrations/pmatrix3-mod3.tex}{\texttt{pmatrix3.tex} using \cref{lst:DBS3}}{lst:pmatrix3-DBS3}
-
- You can customise the pattern for the double back slash by exploring the
- \emph{fine tuning} field detailed in \vref{lst:fineTuning}.
-
-\subsection{Poly-switches for other code blocks}
- Rather than repeat the examples shown for the environment code blocks (in
- \vref{sec:modifylinebreaks-environments}), we choose to detail the poly-switches for all other code
- blocks in \cref{tab:poly-switch-mapping}; note that each and every one of these
- poly-switches is \emph{off by default}, i.e, set to \texttt{0}.
-
- Note also that, by design, line breaks involving, \texttt{filecontents} and
- `comment-marked' code blocks (\vref{lst:alignmentmarkup}) can
- \emph{not} be modified using
- \texttt{latexindent.pl}.%
- \announce{2019-05-05}*{verbatim poly-switch} However, there are two poly-switches available for
- \texttt{verbatim} code blocks: environments (\vref{lst:verbatimEnvironments}),
- commands (\vref{lst:verbatimCommands}) and \texttt{specialBeginEnd} (\vref{lst:special-verb1-yaml}).
- \index{specialBeginEnd!poly-switch summary}
- \index{verbatim!poly-switch summary}
- \index{poly-switches!summary of all poly-switches}
-
- \clearpage
- \begin{longtable}{llll}
- \caption{Poly-switch mappings for all code-block types}\label{tab:poly-switch-mapping} \\
- \toprule
- Code block & Sample & \multicolumn{2}{c}{Poly-switch mapping} \\
- \midrule
- environment & \verb!before words!$\BeginStartsOnOwnLine$ & $\BeginStartsOnOwnLine$ & BeginStartsOnOwnLine \\
- & \verb!\begin{myenv}!$\BodyStartsOnOwnLine$ & $\BodyStartsOnOwnLine$ & BodyStartsOnOwnLine \\
- & \verb!body of myenv!$\EndStartsOnOwnLine$ & $\EndStartsOnOwnLine$ & EndStartsOnOwnLine \\
- & \verb!\end{myenv}!$\EndFinishesWithLineBreak$ & $\EndFinishesWithLineBreak$ & EndFinishesWithLineBreak \\
- & \verb!after words! & & \\
- \cmidrule{2-4}
- ifelsefi & \verb!before words!$\BeginStartsOnOwnLine$ & $\BeginStartsOnOwnLine$ & IfStartsOnOwnLine \\
- & \verb!\if...!$\BodyStartsOnOwnLine$ & $\BodyStartsOnOwnLine$ & BodyStartsOnOwnLine \\
- & \verb!body of if/or statement!$\OrStartsOnOwnLine$ & $\OrStartsOnOwnLine$ & OrStartsOnOwnLine %
- \announce{2018-04-27}{new ifElseFi code block poly-switches} \\
- & \verb!\or!$\OrFinishesWithLineBreak$ & $\OrFinishesWithLineBreak$ & OrFinishesWithLineBreak \\
- & \verb!body of if/or statement!$\ElseStartsOnOwnLine$ & $\ElseStartsOnOwnLine$ & ElseStartsOnOwnLine \\
- & \verb!\else!$\ElseFinishesWithLineBreak$ & $\ElseFinishesWithLineBreak$ & ElseFinishesWithLineBreak \\
- & \verb!body of else statement!$\EndStartsOnOwnLine$ & $\EndStartsOnOwnLine$ & FiStartsOnOwnLine \\
- & \verb!\fi!$\EndFinishesWithLineBreak$ & $\EndFinishesWithLineBreak$ & FiFinishesWithLineBreak \\
- & \verb!after words! & & \\
- \cmidrule{2-4}
- optionalArguments & \verb!...!$\BeginStartsOnOwnLine$ & $\BeginStartsOnOwnLine$ & LSqBStartsOnOwnLine\footnote{LSqB stands for Left Square Bracket} \\
- & \verb![!$\BodyStartsOnOwnLine$ & $\BodyStartsOnOwnLine$ & OptArgBodyStartsOnOwnLine \\
- \announce{2019-07-13}{new comma-related poly-switches} & \verb!value before comma!$\ElseStartsOnOwnLine$, & $\ElseStartsOnOwnLine$ & CommaStartsOnOwnLine \\
- & $\ElseFinishesWithLineBreak$ & $\ElseFinishesWithLineBreak$ & CommaFinishesWithLineBreak \\
- & \verb!end of body of opt arg!$\EndStartsOnOwnLine$ & $\EndStartsOnOwnLine$ & RSqBStartsOnOwnLine \\
- & \verb!]!$\EndFinishesWithLineBreak$ & $\EndFinishesWithLineBreak$ & RSqBFinishesWithLineBreak \\
- & \verb!...! & & \\
- \cmidrule{2-4}
- mandatoryArguments & \verb!...!$\BeginStartsOnOwnLine$ & $\BeginStartsOnOwnLine$ & LCuBStartsOnOwnLine\footnote{LCuB stands for Left Curly Brace} \\
- & \verb!{!$\BodyStartsOnOwnLine$ & $\BodyStartsOnOwnLine$ & MandArgBodyStartsOnOwnLine \\
- \announce{2019-07-13}{new comma-related poly-switches} & \verb!value before comma!$\ElseStartsOnOwnLine$, & $\ElseStartsOnOwnLine$ & CommaStartsOnOwnLine \\
- & $\ElseFinishesWithLineBreak$ & $\ElseFinishesWithLineBreak$ & CommaFinishesWithLineBreak \\
- & \verb!end of body of mand arg!$\EndStartsOnOwnLine$ & $\EndStartsOnOwnLine$ & RCuBStartsOnOwnLine \\
- & \verb!}!$\EndFinishesWithLineBreak$ & $\EndFinishesWithLineBreak$ & RCuBFinishesWithLineBreak \\
- & \verb!...! & & \\
- \cmidrule{2-4}
- commands & \verb!before words!$\BeginStartsOnOwnLine$ & $\BeginStartsOnOwnLine$ & CommandStartsOnOwnLine \\
- & \verb!\mycommand!$\BodyStartsOnOwnLine$ & $\BodyStartsOnOwnLine$ & CommandNameFinishesWithLineBreak \\
- & $\langle$\itshape{arguments}$\rangle$ & & \\
- \cmidrule{2-4}
- namedGroupingBraces Brackets & before words$\BeginStartsOnOwnLine$ & $\BeginStartsOnOwnLine$ & NameStartsOnOwnLine \\
- & myname$\BodyStartsOnOwnLine$ & $\BodyStartsOnOwnLine$ & NameFinishesWithLineBreak \\
- & $\langle$\itshape{braces/brackets}$\rangle$ & & \\
- \cmidrule{2-4}
- keyEqualsValuesBraces\newline Brackets & before words$\BeginStartsOnOwnLine$ & $\BeginStartsOnOwnLine$ & KeyStartsOnOwnLine \\
- & key$\EqualsStartsOnOwnLine$=$\BodyStartsOnOwnLine$ & $\EqualsStartsOnOwnLine$ & EqualsStartsOnOwnLine \\
- & $\langle$\itshape{braces/brackets}$\rangle$ & $\BodyStartsOnOwnLine$ & EqualsFinishesWithLineBreak \\
- \cmidrule{2-4}
- items & before words$\BeginStartsOnOwnLine$ & $\BeginStartsOnOwnLine$ & ItemStartsOnOwnLine \\
- & \verb!\item!$\BodyStartsOnOwnLine$ & $\BodyStartsOnOwnLine$ & ItemFinishesWithLineBreak \\
- & \verb!...! & & \\
- \cmidrule{2-4}
- specialBeginEnd & before words$\BeginStartsOnOwnLine$ & $\BeginStartsOnOwnLine$ & SpecialBeginStartsOnOwnLine \\
- & \verb!\[!$\BodyStartsOnOwnLine$ & $\BodyStartsOnOwnLine$ & SpecialBodyStartsOnOwnLine \\
- & \verb!body of special/middle!$\ElseStartsOnOwnLine$ & $\ElseStartsOnOwnLine$ & SpecialMiddleStartsOnOwnLine %
- \announce{2018-04-27}{new special code block poly-switches} \\
- & \verb!\middle!$\ElseFinishesWithLineBreak$ & $\ElseFinishesWithLineBreak$ & SpecialMiddleFinishesWithLineBreak \\
- & body of special/middle $\EndStartsOnOwnLine$ & $\EndStartsOnOwnLine$ & SpecialEndStartsOnOwnLine \\
- & \verb!\]!$\EndFinishesWithLineBreak$ & $\EndFinishesWithLineBreak$ & SpecialEndFinishesWithLineBreak \\
- & after words & & \\
- \cmidrule{2-4}
- verbatim & before words$\BeginStartsOnOwnLine$\verb!\begin{verbatim}! & $\BeginStartsOnOwnLine$ & VerbatimBeginStartsOnOwnLine \\
- \announce{2019-05-05}{verbatim poly-switches} & body of verbatim \verb!\end{verbatim}!$\EndFinishesWithLineBreak$ & $\EndFinishesWithLineBreak$ & VerbatimEndFinishesWithLineBreak \\
- & after words & & \\
- \bottomrule
- \end{longtable}