summaryrefslogtreecommitdiff
path: root/support/latexindent/documentation/sec-fine-tuning.tex
blob: 669bff5737c47c6665d182fb28420242201c5cee (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
% arara: pdflatex: {shell: yes, 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.

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