summaryrefslogtreecommitdiff
path: root/support/latexindent/documentation/sec-fine-tuning.tex
blob: 8798b276ab7e141ec5ca53ecf8f2da1e4ea464e4 (plain)
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
% 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,enhanced jigsaw,breakable,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}.

  \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}