summaryrefslogtreecommitdiff
path: root/support/latexindent/documentation/subsec-commands-and-their-options.tex
blob: cb2d099994532688c2b03a9f395c15fb34c45faa (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
% arara: pdflatex: { 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}