summaryrefslogtreecommitdiff
path: root/support/latexindent/documentation/sec-fine-tuning.tex
blob: 9a2cbbb5c81793306d5031c5d669a6ce0196e975 (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
% 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.

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

 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
 \begin{commandshell}
latexindent.pl finetuning1.tex -l=fine-tuning1.yaml
\end{commandshell}
 and the associated (desired) output is given in \cref{lst:finetuning1-mod1}.

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