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
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
|
% arara: pdflatex: { files: [latexindent]}
\section{Fine tuning}\label{sec:finetuning}
\texttt{latexindent.pl} operates by looking for the code blocks detailed in
\vref{tab:code-blocks}.
\announce{2019-07-13}{details of fine tuning of code blocks} The fine tuning of the
details of such code blocks is controlled by the \texttt{fineTuning} field, detailed in
\cref{lst:fineTuning}.
This field is for those that would like to peek under the bonnet/hood and make some fine
tuning to \texttt{latexindent.pl}'s operating.
\index{warning!fine tuning}
\index{regular expressions!fine tuning}
\index{regular expressions!environments}
\index{regular expressions!ifElseFi}
\index{regular expressions!commands}
\index{regular expressions!keyEqualsValuesBracesBrackets}
\index{regular expressions!NamedGroupingBracesBrackets}
\index{regular expressions!UnNamedGroupingBracesBrackets}
\index{regular expressions!arguments}
\index{regular expressions!modifyLineBreaks}
\index{regular expressions!lowercase alph a-z}
\index{regular expressions!uppercase alph A-Z}
\index{regular expressions!numeric 0-9}
\index{regular expressions!at least one +}
\index{regular expressions!horizontal space \textbackslash{h}}
\begin{warning}
Making changes to the fine tuning may have significant consequences for your indentation
scheme, proceed with caution!
\end{warning}
\begin{widepage}
\cmhlistingsfromfile[style=fineTuning]{../defaultSettings.yaml}[width=.95\linewidth,before=\centering,yaml-TCB]{\texttt{fineTuning}}{lst:fineTuning}
\end{widepage}
The fields given in \cref{lst:fineTuning} are all \emph{regular expressions}. This manual
is not intended to be a tutorial on regular expressions; you might like to read, for
example, \cite{masteringregexp} for a detailed covering of the topic.
We make the following comments with reference to \cref{lst:fineTuning}:
\begin{enumerate}
\item the \texttt{environments:name} field details that the \emph{name} of an environment can
contain:
\begin{enumerate}
\item \texttt{a-z} lower case letters
\item \texttt{A-Z} upper case letters
\item \texttt{@} the \texttt{@} 'letter'
\item \lstinline!\*! stars
\item \texttt{0-9} numbers
\item \lstinline!_! underscores
\item \lstinline!\! backslashes
\end{enumerate}
\index{regular expressions!at least one +}
The \texttt{+} at the end means \emph{at least one} of the above characters.
\item the \texttt{ifElseFi:name} field:
\begin{enumerate}
\item \lstinline^@?^ means that it \emph{can possibly} begin with
\lstinline^@^
\item followed by \texttt{if}
\item followed by 0 or more characters from \texttt{a-z}, \texttt{A-Z} and \texttt{@}
\item the \texttt{?} the end means \emph{non-greedy}, which means `stop the match as soon as
possible'
\end{enumerate}
\item the \texttt{keyEqualsValuesBracesBrackets} contains some interesting syntax:
\begin{enumerate}
\item \lstinline!|! means `or'
\item \lstinline^(?:(?<!\\)\{)^ the \lstinline^(?:...)^ uses a \emph{non-capturing} group --
you don't necessarily need to worry about what this means, but just know that for the
\texttt{fineTuning} feature you should only ever use \emph{non}-capturing groups, and
\emph{not} capturing groups, which are simply
\lstinline!(...)!
\item \lstinline^(?<!\\)\{)^ means a \lstinline^{^ but it can \emph{not}
be immediately preceded by a \lstinline!\!
\end{enumerate}
\item in the \texttt{arguments:before} field
\begin{enumerate}
\item \lstinline^\d\h*^ means a digit (i.e. a number), followed by 0 or more horizontal
spaces
\item \lstinline^;?,?^ means \emph{possibly} a semi-colon, and possibly a comma
\item \lstinline^\<.*?\>^ is designed for 'beamer'-type commands; the
\lstinline^.*?^ means anything in between \lstinline^<...>^
\end{enumerate}
\item the \texttt{modifyLineBreaks} field refers to fine tuning settings detailed in
\vref{sec:modifylinebreaks}. In particular:
\begin{enumerate}
\item \texttt{betterFullStop} is in relation to the one sentence per line routine, detailed in
\vref{sec:onesentenceperline}
\item \texttt{doubleBackSlash} is in relation to the \texttt{DBSStartsOnOwnLine} and
\texttt{DBSFinishesWithLineBreak} polyswitches surrounding double back slashes, see
\vref{subsec:dbs}
\item \texttt{comma} is in relation to the \texttt{CommaStartsOnOwnLine} and
\texttt{CommaFinishesWithLineBreak} polyswitches surrounding commas in optional and
mandatory arguments; see \vref{tab:poly-switch-mapping}
\end{enumerate}
\end{enumerate}
It is not obvious from \cref{lst:fineTuning}, but each of the \texttt{follow},
\texttt{before} and \texttt{between} fields allow trailing comments, line breaks, and
horizontal spaces between each character.
\index{warning!capture groups}
\begin{warning}
For the \texttt{fineTuning} feature you should only ever use \emph{non}-capturing groups,
such as \lstinline!(?:...)! and \emph{not} capturing groups, which are \lstinline!(...)!
\end{warning}
\begin{example}
As a demonstration, consider the file given in \cref{lst:finetuning1}, together with its
default output using the command
\begin{commandshell}
latexindent.pl finetuning1.tex
\end{commandshell}
is given in \cref{lst:finetuning1-default}.
\begin{cmhtcbraster}[raster column skip=.01\linewidth]
\cmhlistingsfromfile{demonstrations/finetuning1.tex}{\texttt{finetuning1.tex}}{lst:finetuning1}
\cmhlistingsfromfile{demonstrations/finetuning1-default.tex}{\texttt{finetuning1.tex} default}{lst:finetuning1-default}
\end{cmhtcbraster}
It's clear from \cref{lst:finetuning1-default} that the indentation scheme has not worked as
expected. We can \emph{fine tune} the indentation scheme by employing the settings
given in \cref{lst:fine-tuning1} and running the command
\index{switches!-l demonstration}
\begin{commandshell}
latexindent.pl finetuning1.tex -l=fine-tuning1.yaml
\end{commandshell}
and the associated (desired) output is given in \cref{lst:finetuning1-mod1}.
\index{regular expressions!at least one +}
\begin{cmhtcbraster}[raster column skip=.01\linewidth]
\cmhlistingsfromfile{demonstrations/finetuning1-mod1.tex}{\texttt{finetuning1.tex} using \cref{lst:fine-tuning1}}{lst:finetuning1-mod1}
\cmhlistingsfromfile[style=yaml-LST]{demonstrations/fine-tuning1.yaml}[yaml-TCB]{\texttt{finetuning1.yaml}}{lst:fine-tuning1}
\end{cmhtcbraster}
\end{example}
\begin{example}
Let's have another demonstration; consider the file given in \cref{lst:finetuning2}, together with its
default output using the command
\begin{commandshell}
latexindent.pl finetuning2.tex
\end{commandshell}
is given in \cref{lst:finetuning2-default}.
\begin{cmhtcbraster}[raster column skip=.01\linewidth,
raster left skip=-3.75cm,
raster right skip=0cm,]
\cmhlistingsfromfile{demonstrations/finetuning2.tex}{\texttt{finetuning2.tex}}{lst:finetuning2}
\cmhlistingsfromfile{demonstrations/finetuning2-default.tex}{\texttt{finetuning2.tex} default}{lst:finetuning2-default}
\end{cmhtcbraster}
It's clear from \cref{lst:finetuning2-default} that the indentation scheme has not worked as
expected. We can \emph{fine tune} the indentation scheme by employing the settings
given in \cref{lst:fine-tuning2} and running the command
\index{switches!-l demonstration}
\begin{commandshell}
latexindent.pl finetuning2.tex -l=fine-tuning2.yaml
\end{commandshell}
and the associated (desired) output is given in \cref{lst:finetuning2-mod1}.
\begin{cmhtcbraster}[raster column skip=.01\linewidth,
raster left skip=-3.75cm,
raster right skip=0cm,]
\cmhlistingsfromfile{demonstrations/finetuning2-mod1.tex}{\texttt{finetuning2.tex} using \cref{lst:fine-tuning2}}{lst:finetuning2-mod1}
\cmhlistingsfromfile[style=yaml-LST]{demonstrations/fine-tuning2.yaml}[yaml-TCB]{\texttt{finetuning2.yaml}}{lst:fine-tuning2}
\end{cmhtcbraster}
In particular, note that the settings in \cref{lst:fine-tuning2} specify that \texttt{NamedGroupingBracesBrackets}
and \texttt{UnNamedGroupingBracesBrackets} can follow \texttt{"} and that we allow \lstinline!---! between arguments.
\end{example}
\begin{example}
You can tweak the \texttt{fineTuning} using the \texttt{-y} switch, but to be sure to use quotes appropriately.
For example, starting with the code in \cref{lst:finetuning3} and running the following command
\begin{commandshell}
latexindent.pl -m -y='modifyLineBreaks:oneSentencePerLine:manipulateSentences: 1, modifyLineBreaks:oneSentencePerLine:sentencesBeginWith:a-z: 1, fineTuning:modifyLineBreaks:betterFullStop: "(?:\.|;|:(?![a-z]))|(?:(?<!(?:(?:e\.g)|(?:i\.e)|(?:etc))))\.(?!(?:[a-z]|[A-Z]|\-|~|\,|[0-9]))"' issue-243.tex -o=+-mod1
\end{commandshell}
gives the output shown in \cref{lst:finetuning3-mod1}.
\cmhlistingsfromfile{demonstrations/finetuning3.tex}{\texttt{finetuning3.tex}}{lst:finetuning3}
\cmhlistingsfromfile{demonstrations/finetuning3-mod1.tex}{\texttt{finetuning3.tex} using -y switch}{lst:finetuning3-mod1}
\end{example}
\begin{example}
We can tweak the \texttt{fineTuning} for how trailing comments are classified. For motivation, let's consider
the code given in \cref{lst:finetuning4}
\cmhlistingsfromfile{demonstrations/finetuning4.tex}{\texttt{finetuning4.tex}}{lst:finetuning4}
We will compare the settings given in \cref{lst:href1,lst:href2}.
\begin{cmhtcbraster}[raster column skip=.01\linewidth,
raster left skip=0cm,
raster right skip=-0.5cm,]
\cmhlistingsfromfile[style=yaml-LST]{demonstrations/href1.yaml}[MLB-TCB]{\texttt{href1.yaml}}{lst:href1}
\cmhlistingsfromfile[style=yaml-LST]{demonstrations/href2.yaml}[MLB-TCB]{\texttt{href2.yaml}}{lst:href2}
\end{cmhtcbraster}
Upon running the following commands
\begin{commandshell}
latexindent.pl -m finetuning4.tex -o=+-mod1 -l=href1
latexindent.pl -m finetuning4.tex -o=+-mod2 -l=href2
\end{commandshell}
we receive the respective output in \cref{lst:finetuning4-mod1,lst:finetuning4-mod2}.
\begin{widepage}
\cmhlistingsfromfile{demonstrations/finetuning4-mod1.tex}{\texttt{finetuning4.tex} using \cref{lst:href1}}{lst:finetuning4-mod1}
\cmhlistingsfromfile{demonstrations/finetuning4-mod2.tex}{\texttt{finetuning4.tex} using \cref{lst:href2}}{lst:finetuning4-mod2}
\end{widepage}
We note that in:
\begin{itemize}
\item \cref{lst:finetuning4-mod1} the trailing comments are assumed to be everything following
the first comment symbol, which has meant that everything following it has been moved to
the end of the line; this is undesirable, clearly!
\item \cref{lst:finetuning4-mod2} has fine-tuned the trailing comment matching, and says that
\% cannot
be immediately preceeded by the words `Handbook', `for' or `Spoken', which means that
none of the \% symbols have been treated as trailing comments, and the output is
desirable.
\end{itemize}
Another approach to this situation, which does not use \texttt{fineTuning}, is to use \texttt{noIndentBlock}
which we discussed in \vref{lst:noIndentBlock};
using the settings in \cref{lst:href3} and running the command
\begin{commandshell}
latexindent.pl -m finetuning4.tex -o=+-mod3 -l=href3
\end{commandshell}
then we receive the same output given in \cref{lst:finetuning4-mod2}; see also \texttt{paragraphsStopAt}
in \vref{lst:paragraphsStopAt}.
\cmhlistingsfromfile[style=yaml-LST]{demonstrations/href3.yaml}[MLB-TCB]{\texttt{href3.yaml}}{lst:href3}
With reference to the \texttt{body} field in \cref{lst:href3}, we note that the \texttt{body} field can
be interpreted as: the fewest number of zero or more characters that are not right braces. This
is an example of character class.
\index{regular expressions!character class demonstration}
\end{example}
\begin{example}
We can use the \texttt{fineTuning} field to assist in the formatting of bibliography files.
\index{bibliography files}
\index{regular expressions!delimiterRegEx}
\index{regular expressions!capturing parenthesis}
\index{regular expressions!ampersand alignment}
\index{delimiters!delimiterRegEx}
Starting with the file in \cref{lst:bib1} and running the command
\begin{commandshell}
latexindent.pl bib1.tex -o=+-mod1
\end{commandshell}
gives the output in \cref{lst:bib1-mod1}.
\begin{widepage}
\begin{cmhtcbraster}[raster column skip=.01\linewidth]
\cmhlistingsfromfile{demonstrations/bib1.bib}{\texttt{bib1.bib}}{lst:bib1}
\cmhlistingsfromfile{demonstrations/bib1-mod1.bib}{\texttt{bib1-mod1.bib}}{lst:bib1-mod1}
\end{cmhtcbraster}
\end{widepage}
Let's assume that we would like to format the output so as to align the \texttt{=} symbols.
Using the settings in \cref{lst:bibsettings1} and running the command
\begin{commandshell}
latexindent.pl bib1.bib -l bibsettings1.yaml -o=+-mod2
\end{commandshell}
gives the output in \cref{lst:bib1-mod2}.
\begin{widepage}
\begin{cmhtcbraster}[raster column skip=.1\linewidth]
\cmhlistingsfromfile{demonstrations/bib1-mod2.bib}{\texttt{bib1.bib} using \cref{lst:bibsettings1}}{lst:bib1-mod2}
\cmhlistingsfromfile[style=yaml-LST]{demonstrations/bibsettings1.yaml}[yaml-TCB]{\texttt{bibsettings1.yaml}}{lst:bibsettings1}
\end{cmhtcbraster}
\end{widepage}
Some notes about \cref{lst:bibsettings1}:
\begin{itemize}
\item we have populated the \texttt{lookForAlignDelims} field with the \texttt{online} command,
and have used the \texttt{delimiterRegEx}, discussed in \vref{sec:delimiter-reg-ex};
\item we have tweaked the \texttt{keyEqualsValuesBracesBrackets} code block so that it will
\emph{not} be found following a comma; this means that, in contrast to the default
behaviour, the lines such as \lstinline!date={2013-05-23},! will \emph{not} be treated as
key-equals-value braces;
\item the adjustment to \texttt{keyEqualsValuesBracesBrackets} necessitates the associated
change to the \texttt{UnNamedGroupingBracesBrackets} field so that they will be searched
for following \texttt{=} symbols.
\end{itemize}
\end{example}
\begin{example}
We can build upon \cref{lst:bibsettings1} for slightly more complicated bibliography files.
Starting with the file in \cref{lst:bib2} and running the command
\begin{commandshell}
latexindent.pl bib2.bib -l bibsettings1.yaml -o=+-mod1
\end{commandshell}
gives the output in \cref{lst:bib2-mod1}.
\begin{widepage}
\cmhlistingsfromfile{demonstrations/bib2.bib}{\texttt{bib2.bib}}{lst:bib2}
\cmhlistingsfromfile{demonstrations/bib2-mod1.bib}{\texttt{bib2-mod1.bib}}{lst:bib2-mod1}
\end{widepage}
The output in \cref{lst:bib2-mod1} is not ideal, as the \texttt{=} symbol within the url
field has been incorrectly used as an alignment delimiter.
We address this by tweaking the \texttt{delimiterRegEx} field in \cref{lst:bibsettings2}.
\cmhlistingsfromfile[style=yaml-LST]{demonstrations/bibsettings2.yaml}[yaml-TCB]{\texttt{bibsettings2.yaml}}{lst:bibsettings2}
Upon running the command
\begin{commandshell}
latexindent.pl bib2.bib -l bibsettings1.yaml,bibsettings2.yaml -o=+-mod2
\end{commandshell}
we receive the \emph{desired} output in \cref{lst:bib2-mod2}.
\cmhlistingsfromfile{demonstrations/bib2-mod2.bib}{\texttt{bib2-mod2.bib}}{lst:bib2-mod2}
With reference to \cref{lst:bibsettings2} we note that the \texttt{delimiterRegEx} has been adjusted so that \texttt{=} symbols are used as the delimiter,
but only when they are \emph{not preceeded} by either \texttt{v} or \texttt{spfreload}.
\end{example}
|
