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
|
% 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=0.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}
|
