diff options
Diffstat (limited to 'Master/texmf-dist/doc/support/latexindent/subsec-poly-switches.tex')
-rw-r--r-- | Master/texmf-dist/doc/support/latexindent/subsec-poly-switches.tex | 1101 |
1 files changed, 1101 insertions, 0 deletions
diff --git a/Master/texmf-dist/doc/support/latexindent/subsec-poly-switches.tex b/Master/texmf-dist/doc/support/latexindent/subsec-poly-switches.tex new file mode 100644 index 00000000000..609e5ca748a --- /dev/null +++ b/Master/texmf-dist/doc/support/latexindent/subsec-poly-switches.tex @@ -0,0 +1,1101 @@ +% arara: pdflatex: {shell: yes, files: [latexindent]} +\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. + +\subsubsection{Poly-switches 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} + + \paragraph{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} + + \paragraph{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} + + \paragraph{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. + + \paragraph{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}. + + \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{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} + + \paragraph{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} + +\subsubsection{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. + + \paragraph{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} + + \paragraph{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} + + \paragraph{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} + + \paragraph{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} + \end{cmhtcbraster} + + \paragraph{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}. + +\subsubsection{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} +\subsubsection{Partnering BodyStartsOnOwnLine with argument-based poly-switches} + Some poly-switches need to be partnered together; in particular, when line breaks + involving the \emph{first} argument of a code block need to be accounted for using both + \texttt{BodyStartsOnOwnLine} (or its equivalent, see \vref{tab:poly-switch-mapping}) and + \texttt{LCuBStartsOnOwnLine} for mandatory arguments, and \texttt{LSqBStartsOnOwnLine} + for optional arguments. + \index{poly-switches!conflicting partnering} + + Let's begin with the code in \cref{lst:mycommand1} and the YAML settings in + \cref{lst:mycom-mlb1}; with reference to \vref{tab:poly-switch-mapping}, the key + \texttt{CommandNameFinishesWithLineBreak} is an alias for \texttt{BodyStartsOnOwnLine}. + + \cmhlistingsfromfile{demonstrations/mycommand1.tex}{\texttt{mycommand1.tex}}{lst:mycommand1} + + Upon running the command + \index{switches!-l demonstration} + \index{switches!-m demonstration} + \begin{commandshell} +latexindent.pl -m -l=mycom-mlb1.yaml mycommand1.tex +\end{commandshell} + we obtain \cref{lst:mycommand1-mlb1}; note that the \emph{second} mandatory argument + beginning brace \lstinline!{! has had its leading line break removed, but that the + \emph{first} brace has not. + + \begin{cmhtcbraster}[ + raster force size=false, + raster column 1/.style={add to width=-1cm}, + ] + \cmhlistingsfromfile{demonstrations/mycommand1-mlb1.tex}{\texttt{mycommand1.tex} using \cref{lst:mycom-mlb1}}{lst:mycommand1-mlb1} + \cmhlistingsfromfile[style=yaml-LST]*{demonstrations/mycom-mlb1.yaml}[MLB-TCB,width=.6\textwidth]{\texttt{mycom-mlb1.yaml}}{lst:mycom-mlb1} + \end{cmhtcbraster} + + Now let's change the YAML file so that it is as in \cref{lst:mycom-mlb2}; upon running + the analogous command to that given above, we obtain \cref{lst:mycommand1-mlb2}; both + beginning braces \lstinline!{! have had their leading line breaks removed. + + \begin{cmhtcbraster}[ + raster force size=false, + raster column 1/.style={add to width=-1cm}, + ] + \cmhlistingsfromfile{demonstrations/mycommand1-mlb2.tex}{\texttt{mycommand1.tex} using \cref{lst:mycom-mlb2}}{lst:mycommand1-mlb2} + \cmhlistingsfromfile[style=yaml-LST]*{demonstrations/mycom-mlb2.yaml}[MLB-TCB,width=.6\textwidth]{\texttt{mycom-mlb2.yaml}}{lst:mycom-mlb2} + \end{cmhtcbraster} + + Now let's change the YAML file so that it is as in \cref{lst:mycom-mlb3}; upon running + the analogous command to that given above, we obtain \cref{lst:mycommand1-mlb3}. + + \begin{cmhtcbraster}[ + raster force size=false, + raster column 1/.style={add to width=-1cm}, + ] + \cmhlistingsfromfile{demonstrations/mycommand1-mlb3.tex}{\texttt{mycommand1.tex} using \cref{lst:mycom-mlb3}}{lst:mycommand1-mlb3} + \cmhlistingsfromfile[style=yaml-LST]*{demonstrations/mycom-mlb3.yaml}[MLB-TCB,width=.6\textwidth]{\texttt{mycom-mlb3.yaml}}{lst:mycom-mlb3} + \end{cmhtcbraster} + +\subsubsection{Conflicting poly-switches: sequential code blocks} + It is very easy to have conflicting poly-switches; if we use the example from + \vref{lst:mycommand1}, and consider the YAML settings given in \cref{lst:mycom-mlb4}. The + output from running + \index{poly-switches!conflicting switches} + \index{switches!-l demonstration} + \index{switches!-m demonstration} + \begin{commandshell} +latexindent.pl -m -l=mycom-mlb4.yaml mycommand1.tex +\end{commandshell} + is given in \cref{lst:mycom-mlb4}. + + \begin{cmhtcbraster} + \cmhlistingsfromfile{demonstrations/mycommand1-mlb4.tex}{\texttt{mycommand1.tex} using \cref{lst:mycom-mlb4}}{lst:mycommand1-mlb4} + \cmhlistingsfromfile[style=yaml-LST]*{demonstrations/mycom-mlb4.yaml}[MLB-TCB,width=\linewidth]{\texttt{mycom-mlb4.yaml}}{lst:mycom-mlb4} + \end{cmhtcbraster} + + Studying \cref{lst:mycom-mlb4}, we see that the two poly-switches are at opposition with + one another: + \begin{itemize} + \item on the one hand, \texttt{LCuBStartsOnOwnLine} should \emph{not} start on its own line (as + poly-switch is set to $-1$); + \item on the other hand, \texttt{RCuBFinishesWithLineBreak} \emph{should} finish with a line + break. + \end{itemize} + So, which should win the conflict? As demonstrated in \cref{lst:mycommand1-mlb4}, it is + clear that \texttt{LCuBStartsOnOwnLine} won this conflict, and the reason is that + \emph{the second argument was processed after the first} -- in general, the most + recently-processed code block and associated poly-switch takes priority. + + We can explore this further by considering the YAML settings in \cref{lst:mycom-mlb5}; + upon running the command + \index{switches!-l demonstration} + \index{switches!-m demonstration} + \begin{commandshell} +latexindent.pl -m -l=mycom-mlb5.yaml mycommand1.tex +\end{commandshell} + we obtain the output given in \cref{lst:mycommand1-mlb5}. + + \begin{cmhtcbraster}[raster column skip=.1\linewidth] + \cmhlistingsfromfile{demonstrations/mycommand1-mlb5.tex}{\texttt{mycommand1.tex} using \cref{lst:mycom-mlb5}}{lst:mycommand1-mlb5} + \cmhlistingsfromfile[style=yaml-LST]*{demonstrations/mycom-mlb5.yaml}[MLB-TCB,width=\linewidth]{\texttt{mycom-mlb5.yaml}}{lst:mycom-mlb5} + \end{cmhtcbraster} + + As previously, the most-recently-processed code block takes priority -- as before, the + second (i.e, \emph{last}) argument. Exploring this further, we consider the YAML settings + in \cref{lst:mycom-mlb6}, which give associated output in \cref{lst:mycommand1-mlb6}. + + \begin{cmhtcbraster}[raster column skip=.1\linewidth] + \cmhlistingsfromfile{demonstrations/mycommand1-mlb6.tex}{\texttt{mycommand1.tex} using \cref{lst:mycom-mlb6}}{lst:mycommand1-mlb6} + \cmhlistingsfromfile[style=yaml-LST]*{demonstrations/mycom-mlb6.yaml}[MLB-TCB,width=\linewidth]{\texttt{mycom-mlb6.yaml}}{lst:mycom-mlb6} + \end{cmhtcbraster} + + Note that a \lstinline!%! \emph{has} been added to the trailing first + \lstinline!}!; this is because: + \begin{itemize} + \item while processing the \emph{first} argument, the trailing line break has been removed + (\texttt{RCuBFinishesWithLineBreak} set to $-1$); + \item while processing the \emph{second} argument, \texttt{latexindent.pl} finds that it does + \emph{not} begin on its own line, and so because \texttt{LCuBStartsOnOwnLine} is set to + $2$, it adds a comment, followed by a line break. + \end{itemize} + +\subsubsection{Conflicting poly-switches: nested code blocks} + Now let's consider an example when nested code blocks have conflicting poly-switches; + we'll use the code in \cref{lst:nested-env}, noting that it contains nested environments. + \index{poly-switches!conflicting switches} + + \cmhlistingsfromfile{demonstrations/nested-env.tex}{\texttt{nested-env.tex}}{lst:nested-env} + + Let's use the YAML settings given in \cref{lst:nested-env-mlb1-yaml}, which upon running + the command + \index{switches!-l demonstration} + \index{switches!-m demonstration} + \begin{commandshell} +latexindent.pl -m -l=nested-env-mlb1.yaml nested-env.tex +\end{commandshell} + gives the output in \cref{lst:nested-env-mlb1}. + + \begin{cmhtcbraster}[raster column skip=.05\linewidth] + \cmhlistingsfromfile{demonstrations/nested-env-mlb1.tex}{\texttt{nested-env.tex} using \cref{lst:nested-env-mlb1-yaml}}{lst:nested-env-mlb1} + \cmhlistingsfromfile[style=yaml-LST]*{demonstrations/nested-env-mlb1.yaml}[MLB-TCB,width=\linewidth]{\texttt{nested-env-mlb1.yaml}}{lst:nested-env-mlb1-yaml} + \end{cmhtcbraster} + + In \cref{lst:nested-env-mlb1}, let's first of all note that both environments have + received the appropriate (default) indentation; secondly, note that the poly-switch + \texttt{EndStartsOnOwnLine} appears to have won the conflict, as \lstinline!\end{one}! + has had its leading line break removed. + + To understand it, let's talk about the three basic phases \label{page:phases}of + \texttt{latexindent.pl}: + \begin{enumerate} + \item Phase 1: packing, in which code blocks are replaced with unique ids, working from + \emph{the inside to the outside}, and then sequentially -- for example, in + \cref{lst:nested-env}, the \texttt{two} environment is found \emph{before} the + \texttt{one} environment; if the -m switch is active, then during this phase: + \begin{itemize} + \item line breaks at the beginning of the \texttt{body} can be added (if + \texttt{BodyStartsOnOwnLine} is $1$ or $2$) or removed (if \texttt{BodyStartsOnOwnLine} + is $-1$); + \item line breaks at the end of the body can be added (if \texttt{EndStartsOnOwnLine} is $1$ or + $2$) or removed (if \texttt{EndStartsOnOwnLine} is $-1$); + \item line breaks after the end statement can be added (if \texttt{EndFinishesWithLineBreak} is + $1$ or $2$). + \end{itemize} + \item Phase 2: indentation, in which white space is added to the begin, body, and end + statements; + \item Phase 3: unpacking, in which unique ids are replaced by their \emph{indented} code + blocks; if the -m switch is active, then during this phase, + \begin{itemize} + \item line breaks before \texttt{begin} statements can be added or removed (depending upon + \texttt{BeginStartsOnOwnLine}); + \item line breaks after \emph{end} statements can be removed but \emph{NOT} added (see + \texttt{EndFinishesWithLineBreak}). + \end{itemize} + \end{enumerate} + + With reference to \cref{lst:nested-env-mlb1}, this means that during Phase 1: + \begin{itemize} + \item the \texttt{two} environment is found first, and the line break ahead of the + \lstinline!\end{two}! statement is removed because \texttt{EndStartsOnOwnLine} is set to + $-1$. Importantly, because, \emph{at this stage}, + \lstinline!\end{two}! \emph{does} finish with a line break, + \texttt{EndFinishesWithLineBreak} causes no action. + \item next, the \texttt{one} environment is found; the line break ahead of + \lstinline!\end{one}! is removed because \texttt{EndStartsOnOwnLine} is set to + $-1$. + \end{itemize} + The indentation is done in Phase 2; in Phase 3 \emph{there is no option to add a line + break after the \lstinline!end! statements}. We can justify this by remembering that + during Phase 3, the \texttt{one} environment will be found and processed first, followed + by the \texttt{two} environment. If the \texttt{two} environment were to add a line break + after the + \lstinline!\end{two}! statement, then \texttt{latexindent.pl} would have no way of + knowing how much indentation to add to the subsequent text (in this case, + \lstinline!\end{one}!). + + We can explore this further using the poly-switches in \cref{lst:nested-env-mlb2}; upon + running the command + \index{switches!-l demonstration} + \index{switches!-m demonstration} + \begin{commandshell} +latexindent.pl -m -l=nested-env-mlb2.yaml nested-env.tex +\end{commandshell} + we obtain the output given in \cref{lst:nested-env-mlb2-output}. + + \begin{cmhtcbraster} + \cmhlistingsfromfile{demonstrations/nested-env-mlb2.tex}{\texttt{nested-env.tex} using \cref{lst:nested-env-mlb2}}{lst:nested-env-mlb2-output} + \cmhlistingsfromfile[style=yaml-LST]*{demonstrations/nested-env-mlb2.yaml}[MLB-TCB,width=\linewidth]{\texttt{nested-env-mlb2.yaml}}{lst:nested-env-mlb2} + \end{cmhtcbraster} + + During Phase 1: + \begin{itemize} + \item the \texttt{two} environment is found first, and the line break ahead of the + \lstinline!\end{two}! statement is not changed because \texttt{EndStartsOnOwnLine} is + set to $1$. Importantly, because, \emph{at this stage}, + \lstinline!\end{two}! \emph{does} finish with a line break, + \texttt{EndFinishesWithLineBreak} causes no action. + \item next, the \texttt{one} environment is found; the line break ahead of + \lstinline!\end{one}! is already present, and no action is needed. + \end{itemize} + The indentation is done in Phase 2, and then in Phase 3, the \texttt{one} environment is + found and processed first, followed by the \texttt{two} environment. \emph{At this + stage}, the \texttt{two} environment finds \texttt{EndFinishesWithLineBreak} is $-1$, so + it removes the trailing line break; remember, at this point, \texttt{latexindent.pl} has + completely finished with the \texttt{one} environment. |