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