summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/doc/support/latexindent/sec-the-m-switch.tex
diff options
context:
space:
mode:
Diffstat (limited to 'Master/texmf-dist/doc/support/latexindent/sec-the-m-switch.tex')
-rw-r--r--Master/texmf-dist/doc/support/latexindent/sec-the-m-switch.tex555
1 files changed, 555 insertions, 0 deletions
diff --git a/Master/texmf-dist/doc/support/latexindent/sec-the-m-switch.tex b/Master/texmf-dist/doc/support/latexindent/sec-the-m-switch.tex
new file mode 100644
index 00000000000..541a66572d2
--- /dev/null
+++ b/Master/texmf-dist/doc/support/latexindent/sec-the-m-switch.tex
@@ -0,0 +1,555 @@
+% arara: pdflatex: {shell: yes, files: [latexindent]}
+% the -m switch
+% the -m switch
+% the -m switch
+
+\fancyhead[R]{\bfseries\thepage%
+ \tikz[remember picture,overlay] {
+ \node at (1,0){\includegraphics{logo}};
+ }}
+\section{The \texttt{-m} (\texttt{modifylinebreaks}) switch}\label{sec:modifylinebreaks}
+ All features described in this section will only be relevant if the \texttt{-m} switch
+ is used.
+
+\yamltitle{modifylinebreaks}*{fields}
+ \begin{wrapfigure}[7]{r}[0pt]{8cm}
+ \cmhlistingsfromfile[firstnumber=356,linerange={356-358},style=yaml-LST,numbers=left,]{../defaultSettings.yaml}[MLB-TCB,width=.85\linewidth,before=\centering]{\texttt{modifyLineBreaks}}{lst:modifylinebreaks}
+ \end{wrapfigure}
+ \makebox[0pt][r]{%
+ \raisebox{-\totalheight}[0pt][0pt]{%
+ \tikz\node[opacity=1] at (0,0) {\includegraphics[width=4cm]{logo}};}}%
+ One of the most exciting features of Version 3.0 is 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:
+
+ \begin{warning}
+ If you call \texttt{latexindent.pl} with the \texttt{-m} switch, then you
+ are giving it permission to modify line breaks. By default, the only
+ thing that will happen is that multiple blank lines will be condensed into
+ one blank line; many other settings are possible, discussed next.
+ \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.
+
+\yamltitle{condenseMultipleBlankLinesInto}*{integer $\geq 0$}
+ 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
+ \begin{commandshell}
+latexindent.pl myfile.tex -m
+\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{Poly-switches}
+ Every other field in the \texttt{modifyLineBreaks} field uses poly-switches, and can take
+ one of four integer values\footnote{You might like to associate one of the four circles in the logo with one of the four given values}:
+ \begin{itemize}[font=\bfseries]
+ \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>}.
+ \end{itemize}
+ 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. Note that all poly-switches are \emph{off} by default.
+
+ \cmhlistingsfromfile[firstnumber=359,linerange={359-368},style=yaml-LST,numbers=left,]{../defaultSettings.yaml}[width=.8\linewidth,before=\centering,MLB-TCB]{\texttt{environments}}{lst:environments-mlb}
+
+\subsubsection{Adding line breaks (poly-switches set to $1$ or $2$)}
+ 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}.
+
+ \begin{cmhlistings}[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}
+
+ 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$.
+
+ \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,
+ \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}{.57\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}{.42\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}).
+
+ \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}{.57\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}{.42\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 explore \texttt{EndStartsOnOwnLine} and \texttt{EndFinishesWithLineBreak} in \cref{lst:env-mlb5,lst:env-mlb6},
+ and in particular, let's allow each of them in turn to take a value of $1$.
+
+ \begin{minipage}{.49\textwidth}
+ \cmhlistingsfromfile[style=yaml-LST]{demonstrations/env-mlb5.yaml}[MLB-TCB]{\texttt{env-mlb5.yaml}}{lst:env-mlb5}
+ \end{minipage}
+ \hfill
+ \begin{minipage}{.49\textwidth}
+ \cmhlistingsfromfile[style=yaml-LST]{demonstrations/env-mlb6.yaml}[MLB-TCB]{\texttt{env-mlb6.yaml}}{lst:env-mlb6}
+ \end{minipage}
+
+ After running the following commands,
+ \begin{commandshell}
+latexindent.pl -m env-mlb.tex -l env-mlb5.yaml
+latexindent.pl -m env-mlb.tex -l env-mlb6.yaml
+\end{commandshell}
+ the output is as in \cref{lst:env-mlb-mod5,lst:env-mlb-mod6}.
+
+ \begin{widepage}
+ \begin{minipage}{.42\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}{.57\linewidth}
+ \cmhlistingsfromfile{demonstrations/env-mlb-mod6.tex}{\texttt{env-mlb.tex} using \cref{lst:env-mlb6}}{lst:env-mlb-mod6}
+ \end{minipage}
+ \end{widepage}
+
+ There are a couple of points to note:
+ \begin{itemize}
+ \item in \cref{lst:env-mlb-mod5} 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-mod6} 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-mlb5,lst:env-mlb6} so that they are $2$ and
+ save them into \texttt{env-mlb7.yaml} and \texttt{env-mlb8.yaml} respectively (see \cref{lst:env-mlb7,lst:env-mlb8}).
+
+ \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}
+
+ Upon running commands analogous to the above, we obtain \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}
+
+ Note that line breaks have been added as in \cref{lst:env-mlb-mod5,lst:env-mlb-mod6}, 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.
+
+ If you ask \texttt{latexindent.pl} to add a line break (possibly with a comment) using a poly-switch value of $1$ (or $2$),
+ it will only do so if necessary. For example, if you process the file in \vref{lst:mlb2} using any of the YAML
+ files presented so far in this section, 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}
+
+ 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{minipage}{.45\linewidth}
+ \cmhlistingsfromfile{demonstrations/env-mlb3-mod2.tex}{\texttt{env-mlb3.tex} using \vref{lst:env-mlb2}}{lst:env-mlb3-mod2}
+ \end{minipage}
+ \hfill
+ \begin{minipage}{.45\linewidth}
+ \cmhlistingsfromfile{demonstrations/env-mlb3-mod4.tex}{\texttt{env-mlb3.tex} using \vref{lst:env-mlb4}}{lst:env-mlb3-mod4}
+ \end{minipage}
+
+ 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-mlb9}{lst:env-mlb12}.
+
+ \begin{minipage}{.45\linewidth}
+ \begin{cmhlistings}[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-mlb9.yaml}[MLB-TCB]{\texttt{env-mlb9.yaml}}{lst:env-mlb9}
+
+ \cmhlistingsfromfile[style=yaml-LST]{demonstrations/env-mlb10.yaml}[MLB-TCB]{\texttt{env-mlb10.yaml}}{lst:env-mlb10}
+
+ \cmhlistingsfromfile[style=yaml-LST]{demonstrations/env-mlb11.yaml}[MLB-TCB]{\texttt{env-mlb11.yaml}}{lst:env-mlb11}
+
+ \cmhlistingsfromfile[style=yaml-LST]{demonstrations/env-mlb12.yaml}[MLB-TCB]{\texttt{env-mlb12.yaml}}{lst:env-mlb12}
+ \end{minipage}
+
+ After running the commands
+ \begin{commandshell}
+latexindent.pl -m env-mlb4.tex -l env-mlb9.yaml
+latexindent.pl -m env-mlb4.tex -l env-mlb10.yaml
+latexindent.pl -m env-mlb4.tex -l env-mlb11.yaml
+latexindent.pl -m env-mlb4.tex -l env-mlb12.yaml
+\end{commandshell}
+
+ we obtain the respective output in \crefrange{lst:env-mlb4-mod9}{lst:env-mlb4-mod12}.
+
+ \begin{minipage}{.45\linewidth}
+ \cmhlistingsfromfile{demonstrations/env-mlb4-mod9.tex}{\texttt{env-mlb4.tex} using \cref{lst:env-mlb9}}{lst:env-mlb4-mod9}
+ \end{minipage}
+ \hfill
+ \begin{minipage}{.45\linewidth}
+ \cmhlistingsfromfile{demonstrations/env-mlb4-mod10.tex}{\texttt{env-mlb4.tex} using \cref{lst:env-mlb10}}{lst:env-mlb4-mod10}
+ \end{minipage}
+
+ \begin{minipage}{.45\linewidth}
+ \cmhlistingsfromfile{demonstrations/env-mlb4-mod11.tex}{\texttt{env-mlb4.tex} using \cref{lst:env-mlb11}}{lst:env-mlb4-mod11}
+ \end{minipage}
+ \hfill
+ \begin{minipage}{.45\linewidth}
+ \cmhlistingsfromfile{demonstrations/env-mlb4-mod12.tex}{\texttt{env-mlb4.tex} using \cref{lst:env-mlb12}}{lst:env-mlb4-mod12}
+ \end{minipage}
+
+ Notice that in
+ \begin{itemize}
+ \item \cref{lst:env-mlb4-mod9} the line break denoted by $\BeginStartsOnOwnLine$ in \cref{lst:mlb4} has been removed;
+ \item \cref{lst:env-mlb4-mod10} the line break denoted by $\BodyStartsOnOwnLine$ in \cref{lst:mlb4} has been removed;
+ \item \cref{lst:env-mlb4-mod11} the line break denoted by $\EndStartsOnOwnLine$ in \cref{lst:mlb4} has been removed;
+ \item \cref{lst:env-mlb4-mod12} 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-mlb9}{lst:env-mlb12} into one file; alternatively, you could tell \texttt{latexindent.pl}
+ to load them all by using the following command, for example
+ \begin{widepage}
+ \begin{commandshell}
+latexindent.pl -m env-mlb4.tex -l env-mlb9.yaml,env-mlb10.yaml,env-mlb11.yaml,env-mlb12.yaml
+\end{commandshell}
+ \end{widepage}
+ which gives the output in \vref{lst:env-mlb1-tex}.
+
+ \paragraph{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{minipage}{.45\linewidth}
+ \begin{cmhlistings}[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}
+ \end{minipage}
+ \hfill
+ \begin{minipage}{.45\linewidth}
+ \cmhlistingsfromfile[style=yaml-LST]{demonstrations/removeTWS-before.yaml}[yaml-TCB]{\texttt{removeTWS-before.yaml}}{lst:removeTWS-before}
+ \end{minipage}
+
+ The output from the following commands
+ \begin{widepage}
+ \begin{commandshell}
+latexindent.pl -m env-mlb5.tex -l env-mlb9.yaml,env-mlb10.yaml,env-mlb11.yaml,env-mlb12.yaml
+latexindent.pl -m env-mlb5.tex -l env-mlb9.yaml,env-mlb10.yaml,env-mlb11.yaml,env-mlb12.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{demonstrations/env-mlb5-modAll.tex}{\texttt{env-mlb5.tex} using \crefrange{lst:env-mlb4-mod9}{lst:env-mlb4-mod12}}{lst:env-mlb5-modAll}
+
+ \cmhlistingsfromfile{demonstrations/env-mlb5-modAll-remove-WS.tex}{\texttt{env-mlb5.tex} using \crefrange{lst:env-mlb4-mod9}{lst:env-mlb4-mod12} \emph{and} \cref{lst:removeTWS-before}}{lst:env-mlb5-modAll-remove-WS}
+ \end{widepage}
+
+
+ \paragraph{Blank lines}
+ Now let's consider the file in \cref{lst:mlb6}, which contains blank lines.
+
+ \begin{minipage}{.45\linewidth}
+ \begin{cmhlistings}[escapeinside={(*@}{@*)}]{\texttt{env-mlb6.tex}}{lst:mlb6}
+before words(*@$\BeginStartsOnOwnLine$@*)
+
+
+\begin{myenv}(*@$\BodyStartsOnOwnLine$@*)
+
+
+body of myenv(*@$\EndStartsOnOwnLine$@*)
+
+
+\end{myenv}(*@$\EndFinishesWithLineBreak$@*)
+
+after words
+\end{cmhlistings}
+ \end{minipage}%
+ \hfill
+ \begin{minipage}{.45\linewidth}
+ \cmhlistingsfromfile[style=yaml-LST]{demonstrations/UnpreserveBlankLines.yaml}[MLB-TCB]{\texttt{UnpreserveBlankLines.yaml}}{lst:UnpreserveBlankLines}
+ \end{minipage}
+
+ Upon running the following commands
+ \begin{widepage}
+ \begin{commandshell}
+latexindent.pl -m env-mlb6.tex -l env-mlb9.yaml,env-mlb10.yaml,env-mlb11.yaml,env-mlb12.yaml
+latexindent.pl -m env-mlb6.tex -l env-mlb9.yaml,env-mlb10.yaml,env-mlb11.yaml,env-mlb12.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{widepage}
+ \begin{minipage}{.30\linewidth}
+ \cmhlistingsfromfile{demonstrations/env-mlb6-modAll.tex}{\texttt{env-mlb6.tex} using \crefrange{lst:env-mlb4-mod9}{lst:env-mlb4-mod12}}{lst:env-mlb6-modAll}
+ \end{minipage}
+ \hfill
+ \begin{minipage}{.65\linewidth}
+ \cmhlistingsfromfile{demonstrations/env-mlb6-modAll-un-Preserve-Blank-Lines.tex}{\texttt{env-mlb6.tex} using \crefrange{lst:env-mlb4-mod9}{lst:env-mlb4-mod12} \emph{and} \cref{lst:UnpreserveBlankLines}}{lst:env-mlb6-modAll-un-Preserve-Blank-Lines}
+ \end{minipage}
+ \end{widepage}
+
+\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{verbatim}, \texttt{filecontents} and `comment-marked' code blocks (\vref{lst:alignmentmarkup}) can \emph{not} be
+ modified using \texttt{latexindent.pl}.
+
+ \begin{longtable}{m{.2\textwidth}@{\hspace{.75cm}}m{.35\textwidth}@{}m{.4\textwidth}}
+ \caption{Poly-switch mappings for all code-block types}\label{tab:poly-switch-mapping}\\
+ \toprule
+ Code block & Sample & Poly-switch mapping \\
+ \midrule
+ environment &
+ \begin{lstlisting}[escapeinside={(*@}{@*)},nolol=true]
+before words(*@$\BeginStartsOnOwnLine$@*)
+\begin{myenv}(*@$\BodyStartsOnOwnLine$@*)
+body of myenv(*@$\EndStartsOnOwnLine$@*)
+\end{myenv}(*@$\EndFinishesWithLineBreak$@*)
+after words
+ \end{lstlisting}
+ &
+ \begin{tabular}[t]{c@{~}l@{}}
+ $\BeginStartsOnOwnLine$ & BeginStartsOnOwnLine \\
+ $\BodyStartsOnOwnLine$ & BodyStartsOnOwnLine \\
+ $\EndStartsOnOwnLine$ & EndStartsOnOwnLine \\
+ $\EndFinishesWithLineBreak$ & EndFinishesWithLineBreak \\
+ \end{tabular}
+ \\
+ \cmidrule{2-3}
+ ifelsefi &
+ \begin{lstlisting}[escapeinside={(*@}{@*)},nolol=true]
+before words(*@$\BeginStartsOnOwnLine$@*)
+\if...(*@$\BodyStartsOnOwnLine$@*)
+body of if statement(*@$\ElseStartsOnOwnLine$@*)
+\else(*@$\ElseFinishesWithLineBreak$@*)
+body of else statement(*@$\EndStartsOnOwnLine$@*)
+\fi(*@$\EndFinishesWithLineBreak$@*)
+after words
+ \end{lstlisting}
+ &
+ \begin{tabular}[t]{c@{~}l@{}}
+ $\BeginStartsOnOwnLine$ & IfStartsOnOwnLine \\
+ $\BodyStartsOnOwnLine$ & BodyStartsOnOwnLine \\
+ $\ElseStartsOnOwnLine$ & ElseStartsOnOwnLine \\
+ $\ElseFinishesWithLineBreak$ & ElseFinishesWithLineBreak \\
+ $\EndStartsOnOwnLine$ & FiStartsOnOwnLine \\
+ $\EndFinishesWithLineBreak$ & FiFinishesWithLineBreak \\
+ \end{tabular}
+ \\
+ \cmidrule{2-3}
+ optionalArguments &
+ \begin{lstlisting}[escapeinside={(*@}{@*)},nolol=true]
+...(*@$\BeginStartsOnOwnLine$@*)
+[(*@$\BodyStartsOnOwnLine$@*)
+body of opt arg(*@$\EndStartsOnOwnLine$@*)
+](*@$\EndFinishesWithLineBreak$@*)
+...
+ \end{lstlisting}
+ &
+ \begin{tabular}[t]{c@{~}l@{}}
+ $\BeginStartsOnOwnLine$ & LSqBStartsOnOwnLine\footnote{LSqB stands for Left Square Bracket} \\
+ $\BodyStartsOnOwnLine$ & OptArgBodyStartsOnOwnLine \\
+ $\EndStartsOnOwnLine$ & RSqBStartsOnOwnLine \\
+ $\EndFinishesWithLineBreak$ & RSqBFinishesWithLineBreak \\
+ \end{tabular}
+ \\
+ \cmidrule{2-3}
+ mandatoryArguments &
+ \begin{lstlisting}[escapeinside={(*@}{@*)},nolol=true]
+...(*@$\BeginStartsOnOwnLine$@*)
+{(*@$\BodyStartsOnOwnLine$@*)
+body of mand arg(*@$\EndStartsOnOwnLine$@*)
+}(*@$\EndFinishesWithLineBreak$@*)
+...
+ \end{lstlisting}
+ &
+ \begin{tabular}[t]{c@{~}l@{}}
+ $\BeginStartsOnOwnLine$ & LCuBStartsOnOwnLine\footnote{LCuB stands for Left Curly Brace} \\
+ $\BodyStartsOnOwnLine$ & MandArgBodyStartsOnOwnLine \\
+ $\EndStartsOnOwnLine$ & RCuBStartsOnOwnLine \\
+ $\EndFinishesWithLineBreak$ & RCuBFinishesWithLineBreak \\
+ \end{tabular}
+ \\
+ \cmidrule{2-3}
+ commands &
+ \begin{lstlisting}[escapeinside={(*@}{@*)},morekeywords={mycommand},nolol=true,]
+before words(*@$\BeginStartsOnOwnLine$@*)
+\mycommand(*@$\BodyStartsOnOwnLine$@*)
+(*@$\langle$\itshape{arguments}$\rangle$@*)
+ \end{lstlisting}
+ &
+ \begin{tabular}[t]{c@{~}l@{}}
+ $\BeginStartsOnOwnLine$ & CommandStartsOnOwnLine \\
+ $\BodyStartsOnOwnLine$ & CommandNameFinishesWithLineBreak \\
+ \end{tabular}
+ \\
+ \cmidrule{2-3}
+ namedGroupingBraces Brackets &
+ \begin{lstlisting}[escapeinside={(*@}{@*)},morekeywords={myname},nolol=true,]
+before words(*@$\BeginStartsOnOwnLine$@*)
+myname(*@$\BodyStartsOnOwnLine$@*)
+(*@$\langle$\itshape{braces/brackets}$\rangle$@*)
+ \end{lstlisting}
+ &
+ \begin{tabular}[t]{c@{~}l@{}}
+ $\BeginStartsOnOwnLine$ & NameStartsOnOwnLine \\
+ $\BodyStartsOnOwnLine$ & NameFinishesWithLineBreak \\
+ \end{tabular}
+ \\
+ \cmidrule{2-3}
+ keyEqualsValuesBraces\newline Brackets &
+ \begin{lstlisting}[escapeinside={(*@}{@*)},morekeywords={key},nolol=true,]
+before words(*@$\BeginStartsOnOwnLine$@*)
+key(*@$\EqualsStartsOnOwnLine$@*)=(*@$\BodyStartsOnOwnLine$@*)
+(*@$\langle$\itshape{braces/brackets}$\rangle$@*)
+ \end{lstlisting}
+ &
+ \begin{tabular}[t]{c@{~}l@{}}
+ $\BeginStartsOnOwnLine$ & KeyStartsOnOwnLine \\
+ $\EqualsStartsOnOwnLine$ & EqualsStartsOnOwnLine \\
+ $\BodyStartsOnOwnLine$ & EqualsFinishesWithLineBreak \\
+ \end{tabular}
+ \\
+ \cmidrule{2-3}
+ items &
+ \begin{lstlisting}[escapeinside={(*@}{@*)},nolol=true]
+before words(*@$\BeginStartsOnOwnLine$@*)
+\item(*@$\BodyStartsOnOwnLine$@*)
+...
+ \end{lstlisting}
+ &
+ \begin{tabular}[t]{c@{~}l@{}}
+ $\BeginStartsOnOwnLine$ & ItemStartsOnOwnLine \\
+ $\BodyStartsOnOwnLine$ & ItemFinishesWithLineBreak \\
+ \end{tabular}
+ \\
+ \cmidrule{2-3}
+ specialBeginEnd &
+ \begin{lstlisting}[escapeinside={(*@}{@*)},nolol=true]
+before words(*@$\BeginStartsOnOwnLine$@*)
+\[(*@$\BodyStartsOnOwnLine$@*)
+body of special(*@$\EndStartsOnOwnLine$@*)
+\](*@$\EndFinishesWithLineBreak$@*)
+after words
+ \end{lstlisting}
+ &
+ \begin{tabular}[t]{c@{~}l@{}}
+ $\BeginStartsOnOwnLine$ & SpecialBeginStartsOnOwnLine \\
+ $\BodyStartsOnOwnLine$ & SpecialBodyStartsOnOwnLine \\
+ $\EndStartsOnOwnLine$ & SpecialEndStartsOnOwnLine \\
+ $\EndFinishesWithLineBreak$ & SpecialEndFinishesWithLineBreak \\
+ \end{tabular}
+ \\
+ \bottomrule
+ \end{longtable}