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
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
|
% 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
\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}
\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.
\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.
|
