summaryrefslogtreecommitdiff
path: root/support/latexindent/documentation/subsec-commands-and-their-options.tex
blob: d38d4e3f5491ec12c80d635d023ddc44b969011f (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
% arara: pdflatex: {shell: yes, files: [latexindent]}
\subsection{Commands and the strings between their arguments}\label{subsec:commands-string-between}
	The \texttt{command} code blocks will always look for optional (square bracketed)
	and mandatory (curly braced) arguments which can contain comments, line breaks and
	`beamer' commands \lstinline!<.*?>!  between them. There are switches that can allow
	them to contain other strings, which we discuss next.

\yamltitle{commandCodeBlocks}*{fields}

	The \texttt{commandCodeBlocks} field%
	\announce{2018-04-27}*{commandCodeBlocks}
	contains a few switches detailed in \cref{lst:commandCodeBlocks}.

	\cmhlistingsfromfile[style=commandCodeBlocks]*{../defaultSettings.yaml}[width=.8\linewidth,before=\centering,yaml-TCB]{\texttt{commandCodeBlocks}}{lst:commandCodeBlocks}

\yamltitle{roundParenthesesAllowed}{0|1}

	The need for this field was mostly motivated by commands found in code used to generate
	images in \texttt{PSTricks} and \texttt{tikz}; for example, let's consider
	the code given in \cref{lst:pstricks1}.

	\begin{minipage}{.45\textwidth}
		\cmhlistingsfromfile{demonstrations/pstricks1.tex}{\texttt{pstricks1.tex}}{lst:pstricks1}
	\end{minipage}
	\hfill
	\begin{minipage}{.45\textwidth}
		\cmhlistingsfromfile{demonstrations/pstricks1-default.tex}{\texttt{pstricks1} default output}{lst:pstricks1-default}
	\end{minipage}

	Notice that the \lstinline!\defFunction! command has an optional argument, followed by a
	mandatory argument, followed by a round-parenthesis argument, $(u,v)$.

	By default, because \texttt{roundParenthesesAllowed} is set to $1$ in
	\cref{lst:commandCodeBlocks}, then \texttt{latexindent.pl} will allow round parenthesis between
	optional and mandatory arguments. In the case of the code in \cref{lst:pstricks1},
	\texttt{latexindent.pl} finds \emph{all} the arguments of
	\lstinline!defFunction!, both before and after \lstinline!(u,v)!.

	The default output from running \texttt{latexindent.pl} on \cref{lst:pstricks1} actually
	leaves it unchanged (see \cref{lst:pstricks1-default}); note in particular, this is because of
	\texttt{noAdditionalIndentGlobal} as discussed on \cpageref{page:command:noAddGlobal}.

	Upon using the YAML settings in \cref{lst:noRoundParentheses}, and running the command
	\index{switches!-l demonstration}
	\begin{commandshell}
latexindent.pl pstricks1.tex -l noRoundParentheses.yaml
\end{commandshell}
	we obtain the output given in  \cref{lst:pstricks1-nrp}.

	\begin{cmhtcbraster}[raster column skip=.1\linewidth]
		\cmhlistingsfromfile{demonstrations/pstricks1-nrp.tex}{\texttt{pstricks1.tex} using \cref{lst:noRoundParentheses}}{lst:pstricks1-nrp}
		\cmhlistingsfromfile[style=yaml-LST]*{demonstrations/noRoundParentheses.yaml}[yaml-TCB]{\texttt{noRoundParentheses.yaml}}{lst:noRoundParentheses}
	\end{cmhtcbraster}

	Notice the difference between \cref{lst:pstricks1-default} and \cref{lst:pstricks1-nrp}; in
	particular, in \cref{lst:pstricks1-nrp}, because round parentheses are
	\emph{not} allowed, \texttt{latexindent.pl} finds that the
	\lstinline!\defFunction! command finishes at the first opening round parenthesis. As such,
	the remaining braced, mandatory, arguments are found to be \texttt{UnNamedGroupingBracesBrackets} (see \vref{tab:code-blocks}) which,
	by default, assume indentation for their body, and hence the tabbed indentation in
	\cref{lst:pstricks1-nrp}.

	Let's explore this using the YAML given in \cref{lst:defFunction} and run the command
	\index{switches!-l demonstration}
	\begin{commandshell}
latexindent.pl pstricks1.tex -l defFunction.yaml
\end{commandshell}
	then the output is as in \cref{lst:pstricks1-indent-rules}.

	\begin{cmhtcbraster}[raster column skip=.1\linewidth]
		\cmhlistingsfromfile[showspaces=true]{demonstrations/pstricks1-indent-rules.tex}{\texttt{pstricks1.tex} using \cref{lst:defFunction}}{lst:pstricks1-indent-rules}
		\cmhlistingsfromfile[style=yaml-LST]*{demonstrations/defFunction.yaml}[yaml-TCB]{\texttt{defFunction.yaml}}{lst:defFunction}
	\end{cmhtcbraster}

	Notice in \cref{lst:pstricks1-indent-rules} that the \emph{body} of the
	\lstinline!defFunction! command i.e, the subsequent lines containing arguments after the
	command name, have received the single space of indentation specified by
	\cref{lst:defFunction}.

\yamltitle{stringsAllowedBetweenArguments}*{fields}
	\texttt{tikz} users may well specify code such as that given in
	\cref{lst:tikz-node1}; processing this code using
	\texttt{latexindent.pl} gives the default output in \cref{lst:tikz-node1-default}.

	\begin{minipage}{.45\textwidth}
		\cmhlistingsfromfile[columns=fixed]*{demonstrations/tikz-node1.tex}{\texttt{tikz-node1.tex}}{lst:tikz-node1}
	\end{minipage}
	\hfill
	\begin{minipage}{.45\textwidth}
		\cmhlistingsfromfile[columns=fixed]*{demonstrations/tikz-node1-default.tex}{\texttt{tikz-node1} default output}{lst:tikz-node1-default}
	\end{minipage}

	With reference to \vref{lst:commandCodeBlocks}, we see that the strings
	\begin{quote}
		to, node, ++
	\end{quote}
	are all allowed to appear between arguments; importantly, you are encouraged to add
	further names to this field as necessary. This means that when \texttt{latexindent.pl}
	processes \cref{lst:tikz-node1}, it consumes:
	\begin{itemize}
		\item the optional argument \lstinline![thin]!
		\item the round-bracketed argument \lstinline!(c)! because \texttt{roundParenthesesAllowed} is
		      $1$ by default
		\item the string \lstinline!to! (specified in \texttt{stringsAllowedBetweenArguments})
		\item the optional argument \lstinline![in=110,out=-90]!
		\item the string \lstinline!++! (specified in \texttt{stringsAllowedBetweenArguments})
		\item the round-bracketed argument \lstinline!(0,-0.5cm)! because \texttt{roundParenthesesAllowed} is
		      $1$ by default
		\item the string \lstinline!node! (specified in \texttt{stringsAllowedBetweenArguments})
		\item the optional argument \lstinline![below,align=left,scale=0.5]!
	\end{itemize}

	We can explore this further, for example using \cref{lst:draw} and running the
	command
	\index{switches!-l demonstration}
	\begin{commandshell}
latexindent.pl tikz-node1.tex -l draw.yaml  
\end{commandshell}
	we receive the output given in \cref{lst:tikz-node1-draw}.

	\begin{cmhtcbraster}[raster column skip=.1\linewidth]
		\cmhlistingsfromfile[showspaces=true]{demonstrations/tikz-node1-draw.tex}{\texttt{tikz-node1.tex} using \cref{lst:draw}}{lst:tikz-node1-draw}
		\cmhlistingsfromfile[style=yaml-LST]*{demonstrations/draw.yaml}[yaml-TCB]{\texttt{draw.yaml}}{lst:draw}
	\end{cmhtcbraster}

	Notice that each line after the \lstinline!\draw! command (its `body') in
	\cref{lst:tikz-node1-draw} has been given the appropriate two-spaces worth of indentation
	specified in \cref{lst:draw}.

	Let's compare this with the output from using the YAML settings in
	\cref{lst:no-strings}, and running the command
	\index{switches!-l demonstration}
	\begin{commandshell}
latexindent.pl tikz-node1.tex -l no-strings.yaml  
\end{commandshell}
	given in \cref{lst:tikz-node1-no-strings}.

	\begin{cmhtcbraster}[raster column skip=.1\linewidth]
		\cmhlistingsfromfile{demonstrations/tikz-node1-no-strings.tex}{\texttt{tikz-node1.tex} using \cref{lst:no-strings}}{lst:tikz-node1-no-strings}
		\cmhlistingsfromfile[style=yaml-LST]*{demonstrations/no-strings.yaml}[yaml-TCB]{\texttt{no-strings.yaml}}{lst:no-strings}
	\end{cmhtcbraster}

	In this case, \texttt{latexindent.pl} sees that:
	\begin{itemize}
		\item the \lstinline!\draw! command finishes after the \lstinline!(c)!, as
		      \texttt{stringsAllowedBetweenArguments} has been set to $0$ so there are no strings
		      allowed between arguments;
		\item it finds a \texttt{namedGroupingBracesBrackets} called \texttt{to} (see \vref{tab:code-blocks}) \emph{with}
		      argument \lstinline![in=110,out=-90]!
		\item it finds another \texttt{namedGroupingBracesBrackets} but this time called \texttt{node} with
		      argument \lstinline![below,align=left,scale=0.5]!
	\end{itemize}

	Referencing \vref{lst:commandCodeBlocks},%
	\announce{2018-04-27}*{amalgamate feature in commandCodeBlocks}, we see that the first field in the \texttt{stringsAllowedBetweenArguments} is
	\texttt{amalgamate} and is set to \texttt{1} by default. This is for
	users who wish to specify their settings in multiple YAML files. For example, by using
	the settings in either \cref{lst:amalgamate-demo} or\cref{lst:amalgamate-demo1} is equivalent to
	using the settings in \cref{lst:amalgamate-demo2}.

	\begin{cmhtcbraster}[raster columns=3,
			raster left skip=-3.5cm,
			raster right skip=-2cm,
			raster column skip=.03\linewidth]
		\cmhlistingsfromfile[style=yaml-LST]*{demonstrations/amalgamate-demo.yaml}[yaml-TCB]{\texttt{amalgamate-demo.yaml}}{lst:amalgamate-demo}
		\cmhlistingsfromfile[style=yaml-LST]*{demonstrations/amalgamate-demo1.yaml}[yaml-TCB]{\texttt{amalgamate-demo1.yaml}}{lst:amalgamate-demo1}
		\cmhlistingsfromfile[style=yaml-LST]*{demonstrations/amalgamate-demo2.yaml}[yaml-TCB]{\texttt{amalgamate-demo2.yaml}}{lst:amalgamate-demo2}
	\end{cmhtcbraster}

	We specify \texttt{amalgamate} to be set to \texttt{0} and in which case
	any settings loaded prior to those specified, including the default, will be overwritten.
	For example, using the settings in \cref{lst:amalgamate-demo3} means that only the strings
	specified in that field will be used.

	\cmhlistingsfromfile[style=yaml-LST]*{demonstrations/amalgamate-demo3.yaml}[yaml-TCB]{\texttt{amalgamate-demo3.yaml}}{lst:amalgamate-demo3}

	It is important to note that the \texttt{amalgamate} field, if used, must be in the
	first field, and specified using the syntax given in \cref{lst:amalgamate-demo1,lst:amalgamate-demo2,lst:amalgamate-demo3}.

	We may explore this feature further with the code in \cref{lst:for-each}, whose
	default output is given in \cref{lst:for-each-default}.

	\begin{cmhtcbraster}[raster column skip=.1\linewidth]
		\cmhlistingsfromfile{demonstrations/for-each.tex}{\texttt{for-each.tex}}{lst:for-each}
		\cmhlistingsfromfile{demonstrations/for-each-default.tex}{\texttt{for-each} default output}{lst:for-each-default}
	\end{cmhtcbraster}

	Let's compare this with the output from using the YAML settings in
	\cref{lst:foreach}, and running the command
	\index{switches!-l demonstration}
	\begin{commandshell}
latexindent.pl for-each.tex -l foreach.yaml  
\end{commandshell}
	given in \cref{lst:for-each-mod1}.

	\begin{cmhtcbraster}[raster column skip=.1\linewidth]
		\cmhlistingsfromfile{demonstrations/for-each-mod1.tex}{\texttt{for-each.tex} using \cref{lst:foreach}}{lst:for-each-mod1}
		\cmhlistingsfromfile[style=yaml-LST]*{demonstrations/foreach.yaml}[yaml-TCB]{\texttt{foreach.yaml}}{lst:foreach}
	\end{cmhtcbraster}

	You might like to compare the output given in \cref{lst:for-each-default} and
	\cref{lst:for-each-mod1}. Note,in particular, in \cref{lst:for-each-default} that the
	\texttt{foreach} command has not included any of the subsequent strings, and that
	the braces have been treated as a \texttt{namedGroupingBracesBrackets}. In \cref{lst:for-each-mod1} the
	\texttt{foreach} command has been allowed to have \lstinline!\x/\y! and
	\texttt{in} between arguments because of the settings given in
	\cref{lst:foreach}.

\yamltitle{commandNameSpecial}*{fields}
	There are some special command names%
	\announce{2018-04-27}*{commandNameSpecial} that do not fit within the names recognised by
	\texttt{latexindent.pl}, the first one of which is \lstinline!\@ifnextchar[!. From the
	perspective of \texttt{latexindent.pl}, the whole of the text \lstinline!\@ifnextchar[! is
	a command, because it is immediately followed by sets of mandatory arguments. However,
	without the \texttt{commandNameSpecial} field, \texttt{latexindent.pl} would not be able to
	label it as such, because the \lstinline![! is, necessarily, not matched by a
	closing \lstinline!]!.

	For example, consider the sample file in \cref{lst:ifnextchar}, which has default
	output in \cref{lst:ifnextchar-default}.

	\begin{cmhtcbraster}[raster column skip=.1\linewidth]
		\cmhlistingsfromfile{demonstrations/ifnextchar.tex}{\texttt{ifnextchar.tex}}{lst:ifnextchar}
		\cmhlistingsfromfile{demonstrations/ifnextchar-default.tex}{\texttt{ifnextchar.tex} default output}{lst:ifnextchar-default}
	\end{cmhtcbraster}

	Notice that in \cref{lst:ifnextchar-default} the \texttt{parbox} command has been able
	to indent its body, because \texttt{latexindent.pl} has successfully found the command
	\lstinline!\@ifnextchar! first; the pattern-matching of \texttt{latexindent.pl} starts
	from \emph{the inner most <thing> and works outwards}, discussed in more detail on \cpageref{page:phases}.

	For demonstration, we can compare this output with that given in \cref{lst:ifnextchar-off}
	in which the settings from \cref{lst:no-ifnextchar} have dictated that no special command
	names, including the \lstinline!\@ifnextchar[! command, should not be searched for
	specially; as such, the \texttt{parbox} command has been \emph{unable}
	to indent its body successfully, because the \lstinline!\@ifnextchar[! command has not been
	found.

	\begin{cmhtcbraster}[raster column skip=.1\linewidth]
		\cmhlistingsfromfile{demonstrations/ifnextchar-off.tex}{\texttt{ifnextchar.tex} using \cref{lst:no-ifnextchar}}{lst:ifnextchar-off}
		\cmhlistingsfromfile[style=yaml-LST]*{demonstrations/no-ifnextchar.yaml}[yaml-TCB]{\texttt{no-ifnextchar.yaml}}{lst:no-ifnextchar}
	\end{cmhtcbraster}

	The \texttt{amalgamate} field can be used for \texttt{commandNameSpecial}, just as for
	\texttt{stringsAllowedBetweenArguments}. The same condition holds as stated previously, which we state
	again here:
	\index{warning!amalgamate field}

	\begin{warning}
		It is important to note that the \texttt{amalgamate} field, if used, in either \texttt{commandNameSpecial} or \texttt{stringsAllowedBetweenArguments} must be in the first field,
		and specified using the syntax given in \cref{lst:amalgamate-demo1,lst:amalgamate-demo2,lst:amalgamate-demo3}.
	\end{warning}