% arara: pdflatex: {shell: yes, files: [latexindent]} \subsection{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 \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 \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} \subsection{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. \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 \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 \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.