1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
|
% 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{minipage}{.4\linewidth}
\cmhlistingsfromfile{demonstrations/mycommand1-mlb4.tex}{\texttt{mycommand1.tex} using \cref{lst:mycom-mlb4}}{lst:mycommand1-mlb4}
\end{minipage}
\hfill
\begin{minipage}{.55\linewidth}
\cmhlistingsfromfile[style=yaml-LST]*{demonstrations/mycom-mlb4.yaml}[MLB-TCB,width=\linewidth]{\texttt{mycom-mlb4.yaml}}{lst:mycom-mlb4}
\end{minipage}
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{minipage}{.4\linewidth}
\cmhlistingsfromfile{demonstrations/mycommand1-mlb5.tex}{\texttt{mycommand1.tex} using \cref{lst:mycom-mlb5}}{lst:mycommand1-mlb5}
\end{minipage}
\hfill
\begin{minipage}{.55\linewidth}
\cmhlistingsfromfile[style=yaml-LST]*{demonstrations/mycom-mlb5.yaml}[MLB-TCB,width=\linewidth]{\texttt{mycom-mlb5.yaml}}{lst:mycom-mlb5}
\end{minipage}
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{minipage}{.4\linewidth}
\cmhlistingsfromfile{demonstrations/mycommand1-mlb6.tex}{\texttt{mycommand1.tex} using \cref{lst:mycom-mlb6}}{lst:mycommand1-mlb6}
\end{minipage}
\hfill
\begin{minipage}{.55\linewidth}
\cmhlistingsfromfile[style=yaml-LST]*{demonstrations/mycom-mlb6.yaml}[MLB-TCB,width=\linewidth]{\texttt{mycom-mlb6.yaml}}{lst:mycom-mlb6}
\end{minipage}
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{minipage}{.45\linewidth}
\cmhlistingsfromfile{demonstrations/nested-env-mlb1.tex}{\texttt{nested-env.tex} using \cref{lst:nested-env-mlb1-yaml}}{lst:nested-env-mlb1}
\end{minipage}
\hfill
\begin{minipage}{.55\linewidth}
\cmhlistingsfromfile[style=yaml-LST]*{demonstrations/nested-env-mlb1.yaml}[MLB-TCB,width=\linewidth]{\texttt{nested-env-mlb1.yaml}}{lst:nested-env-mlb1-yaml}
\end{minipage}
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{minipage}{.45\linewidth}
\cmhlistingsfromfile{demonstrations/nested-env-mlb2.tex}{\texttt{nested-env.tex} using \cref{lst:nested-env-mlb2}}{lst:nested-env-mlb2-output}
\end{minipage}
\hfill
\begin{minipage}{.55\linewidth}
\cmhlistingsfromfile[style=yaml-LST]*{demonstrations/nested-env-mlb2.yaml}[MLB-TCB,width=\linewidth]{\texttt{nested-env-mlb2.yaml}}{lst:nested-env-mlb2}
\end{minipage}
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.
|
