summaryrefslogtreecommitdiff
path: root/support/latexindent/documentation/subsubsec-environments-and-their-arguments.tex
blob: 262ffe878a513b16b5ae2b0ef8fb1d2795f35788 (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
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
% arara: pdflatex: {shell: yes, files: [latexindent]}
\subsubsection{Environments and their arguments}\label{subsubsec:env-and-their-args}
	There are a few different YAML switches governing the indentation of environments; let's
	start with the code shown in \cref{lst:myenvtex}.

	\cmhlistingsfromfile{demonstrations/myenvironment-simple.tex}{\texttt{myenv.tex}}{lst:myenvtex}

\yamltitle{noAdditionalIndent}*{fields}
	If we do not wish \texttt{myenv} to receive any additional indentation, we have a few
	choices available to us, as demonstrated in \cref{lst:myenv-noAdd1,lst:myenv-noAdd2}.

	\begin{minipage}{.45\textwidth}
		\cmhlistingsfromfile[style=yaml-LST]*{demonstrations/myenv-noAdd1.yaml}[width=.8\linewidth,before=\centering,yaml-TCB]{\texttt{myenv-noAdd1.yaml}}{lst:myenv-noAdd1}
	\end{minipage}
	\hfill
	\begin{minipage}{.45\textwidth}
		\cmhlistingsfromfile[style=yaml-LST]*{demonstrations/myenv-noAdd2.yaml}[width=.8\linewidth,before=\centering,yaml-TCB]{\texttt{myenv-noAdd2.yaml}}{lst:myenv-noAdd2}
	\end{minipage}

	On applying either of the following commands,
	\index{switches!-l demonstration}
	\begin{commandshell}
latexindent.pl myenv.tex -l myenv-noAdd1.yaml  
latexindent.pl myenv.tex -l myenv-noAdd2.yaml  
\end{commandshell}
	we obtain the output given in \cref{lst:myenv-output}; note in particular that the
	environment \texttt{myenv} has not received any \emph{additional} indentation, but that
	the \texttt{outer} environment \emph{has} still received indentation.

	\cmhlistingsfromfile{demonstrations/myenvironment-simple-noAdd-body1.tex}{\texttt{myenv.tex} output (using either \cref{lst:myenv-noAdd1} or \cref{lst:myenv-noAdd2})}{lst:myenv-output}

	Upon changing the YAML files to those shown in \cref{lst:myenv-noAdd3,lst:myenv-noAdd4},
	and running either
	\index{switches!-l demonstration}
	\begin{commandshell}
latexindent.pl myenv.tex -l myenv-noAdd3.yaml  
latexindent.pl myenv.tex -l myenv-noAdd4.yaml  
\end{commandshell}
	we obtain the output given in \cref{lst:myenv-output-4}.

	\begin{minipage}{.45\textwidth}
		\cmhlistingsfromfile[style=yaml-LST]*{demonstrations/myenv-noAdd3.yaml}[width=.8\linewidth,before=\centering,yaml-TCB]{\texttt{myenv-noAdd3.yaml}}{lst:myenv-noAdd3}
	\end{minipage}
	\hfill
	\begin{minipage}{.45\textwidth}
		\cmhlistingsfromfile[style=yaml-LST]*{demonstrations/myenv-noAdd4.yaml}[width=.8\linewidth,before=\centering,yaml-TCB]{\texttt{myenv-noAdd4.yaml}}{lst:myenv-noAdd4}
	\end{minipage}

	\cmhlistingsfromfile{demonstrations/myenvironment-simple-noAdd-body4.tex}{\texttt{myenv.tex output} (using either \cref{lst:myenv-noAdd3} or \cref{lst:myenv-noAdd4})}{lst:myenv-output-4}

	Let's now allow \texttt{myenv} to have some optional and mandatory arguments, as in
	\cref{lst:myenv-args}.

	\cmhlistingsfromfile{demonstrations/myenvironment-args.tex}{\texttt{myenv-args.tex}}{lst:myenv-args}

	Upon running
	\index{switches!-l demonstration}
	\begin{commandshell}
latexindent.pl -l=myenv-noAdd1.yaml myenv-args.tex  
\end{commandshell}
	we obtain the output shown in \cref{lst:myenv-args-noAdd1}; note that the optional
	argument, mandatory argument and body \emph{all} have received no additional indent. This
	is because, when \texttt{noAdditionalIndent} is specified in `scalar' form (as in
	\cref{lst:myenv-noAdd1}), then \emph{all} parts of the environment (body, optional and
	mandatory arguments) are assumed to want no additional indent.
	\cmhlistingsfromfile{demonstrations/myenvironment-args-noAdd-body1.tex}{\texttt{myenv-args.tex} using \cref{lst:myenv-noAdd1}}{lst:myenv-args-noAdd1}

	We may customise \texttt{noAdditionalIndent} for optional and mandatory arguments of the
	\texttt{myenv} environment, as shown in, for example,
	\cref{lst:myenv-noAdd5,lst:myenv-noAdd6}.

	\begin{minipage}{.49\textwidth}
		\cmhlistingsfromfile[style=yaml-LST]*{demonstrations/myenv-noAdd5.yaml}[width=.8\linewidth,before=\centering,yaml-TCB]{\texttt{myenv-noAdd5.yaml}}{lst:myenv-noAdd5}
	\end{minipage}
	\hfill
	\begin{minipage}{.49\textwidth}
		\cmhlistingsfromfile[style=yaml-LST]*{demonstrations/myenv-noAdd6.yaml}[width=.8\linewidth,before=\centering,yaml-TCB]{\texttt{myenv-noAdd6.yaml}}{lst:myenv-noAdd6}
	\end{minipage}

	Upon running
	\index{switches!-l demonstration}
	\begin{commandshell}
latexindent.pl myenv.tex -l myenv-noAdd5.yaml  
latexindent.pl myenv.tex -l myenv-noAdd6.yaml  
\end{commandshell}
	we obtain the respective outputs given in
	\cref{lst:myenv-args-noAdd5,lst:myenv-args-noAdd6}. Note that in
	\cref{lst:myenv-args-noAdd5} the text for the \emph{optional} argument has not received
	any additional indentation, and that in \cref{lst:myenv-args-noAdd6} the \emph{mandatory}
	argument has not received any additional indentation; in both cases, the \emph{body} has
	not received any additional indentation.

	\begin{minipage}{.45\textwidth}
		\cmhlistingsfromfile{demonstrations/myenvironment-args-noAdd5.tex}{\texttt{myenv-args.tex} using \cref{lst:myenv-noAdd5}}{lst:myenv-args-noAdd5}
	\end{minipage}
	\hfill
	\begin{minipage}{.45\textwidth}
		\cmhlistingsfromfile{demonstrations/myenvironment-args-noAdd6.tex}{\texttt{myenv-args.tex} using \cref{lst:myenv-noAdd6}}{lst:myenv-args-noAdd6}
	\end{minipage}

\yamltitle{indentRules}*{fields}
	We may also specify indentation rules for environment code blocks using the
	\texttt{indentRules} field; see, for example, \cref{lst:myenv-rules1,lst:myenv-rules2}.

	\begin{cmhtcbraster}[raster column skip=.1\linewidth]
		\cmhlistingsfromfile[style=yaml-LST]*{demonstrations/myenv-rules1.yaml}[width=.8\linewidth,before=\centering,yaml-TCB]{\texttt{myenv-rules1.yaml}}{lst:myenv-rules1}
		\cmhlistingsfromfile[style=yaml-LST]*{demonstrations/myenv-rules2.yaml}[width=.8\linewidth,before=\centering,yaml-TCB]{\texttt{myenv-rules2.yaml}}{lst:myenv-rules2}
	\end{cmhtcbraster}

	On applying either of the following commands,
	\index{switches!-l demonstration}
	\begin{commandshell}
latexindent.pl myenv.tex -l myenv-rules1.yaml  
latexindent.pl myenv.tex -l myenv-rules2.yaml  
\end{commandshell}
	we obtain the output given in \cref{lst:myenv-rules-output}; note in particular that the
	environment \texttt{myenv} has received one tab (from the \texttt{outer} environment)
	plus three spaces from \cref{lst:myenv-rules1} or \ref{lst:myenv-rules2}.

	\cmhlistingsfromfile[showtabs=true,showspaces=true]{demonstrations/myenv-rules1.tex}{\texttt{myenv.tex} output (using either \cref{lst:myenv-rules1} or \cref{lst:myenv-rules2})}{lst:myenv-rules-output}

	If you specify a field in \texttt{indentRules} using anything other than horizontal
	space, it will be ignored.

	Returning to the example in \cref{lst:myenv-args} that contains optional and mandatory
	arguments. Upon using \cref{lst:myenv-rules1} as in
	\index{switches!-l demonstration}
	\begin{commandshell}
latexindent.pl myenv-args.tex -l=myenv-rules1.yaml  
\end{commandshell}
	we obtain the output in \cref{lst:myenv-args-rules1}; note that the body, optional
	argument and mandatory argument of \texttt{myenv} have \emph{all} received the same
	customised indentation.
	\cmhlistingsfromfile[showtabs=true,showspaces=true]{demonstrations/myenvironment-args-rules1.tex}{\texttt{myenv-args.tex} using \cref{lst:myenv-rules1}}{lst:myenv-args-rules1}

	You can specify different indentation rules for the different features using, for
	example, \cref{lst:myenv-rules3,lst:myenv-rules4}

	\begin{minipage}{.49\textwidth}
		\cmhlistingsfromfile[style=yaml-LST]*{demonstrations/myenv-rules3.yaml}[width=.9\linewidth,before=\centering,yaml-TCB]{\texttt{myenv-rules3.yaml}}{lst:myenv-rules3}
	\end{minipage}
	\hfill
	\begin{minipage}{.49\textwidth}
		\cmhlistingsfromfile[style=yaml-LST]*{demonstrations/myenv-rules4.yaml}[width=.9\linewidth,before=\centering,yaml-TCB]{\texttt{myenv-rules4.yaml}}{lst:myenv-rules4}
	\end{minipage}

	After running
	\index{switches!-l demonstration}
	\begin{commandshell}
latexindent.pl myenv-args.tex -l myenv-rules3.yaml  
latexindent.pl myenv-args.tex -l myenv-rules4.yaml  
\end{commandshell}
	then we obtain the respective outputs given in
	\cref{lst:myenv-args-rules3,lst:myenv-args-rules4}.

	\begin{widepage}
		\begin{minipage}{.5\textwidth}
			\cmhlistingsfromfile[showtabs=true,showspaces=true]{demonstrations/myenvironment-args-rules3.tex}{\texttt{myenv-args.tex} using \cref{lst:myenv-rules3}}{lst:myenv-args-rules3}
		\end{minipage}%
		\hfill
		\begin{minipage}{.5\textwidth}
			\cmhlistingsfromfile[showtabs=true,showspaces=true]{demonstrations/myenvironment-args-rules4.tex}{\texttt{myenv-args.tex} using \cref{lst:myenv-rules4}}{lst:myenv-args-rules4}
		\end{minipage}
	\end{widepage}

	Note that in \cref{lst:myenv-args-rules3}, the optional argument has only received a
	single space of indentation, while the mandatory argument has received the default (tab)
	indentation; the environment body has received three spaces of indentation.

	In \cref{lst:myenv-args-rules4}, the optional argument has received the default (tab)
	indentation, the mandatory argument has received two tabs of indentation, and the body
	has received three spaces of indentation.

\yamltitle{noAdditionalIndentGlobal}*{fields}
	Assuming that your environment name is not found within neither
	\texttt{noAdditionalIndent} nor \texttt{indentRules}, the next place that
	\texttt{latexindent.pl} will look is \texttt{noAdditionalIndentGlobal}, and in particular
	\emph{for the environments} key (see \cref{lst:noAdditionalIndentGlobal:environments}).

	\cmhlistingsfromfile[style=noAdditionalIndentGlobalEnv]*{../defaultSettings.yaml}[width=.5\linewidth,before=\centering,yaml-TCB]{\texttt{noAdditionalIndentGlobal}}{lst:noAdditionalIndentGlobal:environments}

	Let's say that you change the value of \texttt{environments} to \texttt{1} in
	\cref{lst:noAdditionalIndentGlobal:environments}, and that you run
	\index{switches!-l demonstration}

	\begin{widepage}
		\begin{commandshell}
latexindent.pl myenv-args.tex -l env-noAdditionalGlobal.yaml
latexindent.pl myenv-args.tex -l myenv-rules1.yaml,env-noAdditionalGlobal.yaml
\end{commandshell}
	\end{widepage}

	The respective output from these two commands are in
	\cref{lst:myenv-args-no-add-global1,lst:myenv-args-no-add-global2}; in
	\cref{lst:myenv-args-no-add-global1} notice that \emph{both} environments receive no
	additional indentation but that the arguments of \texttt{myenv} still \emph{do} receive
	indentation. In \cref{lst:myenv-args-no-add-global2} notice that the \emph{outer}
	environment does not receive additional indentation, but because of the settings from
	\texttt{myenv-rules1.yaml} (in \vref{lst:myenv-rules1}), the \texttt{myenv} environment
	still \emph{does} receive indentation.

	\begin{minipage}{.45\textwidth}
		\cmhlistingsfromfile{demonstrations/myenvironment-args-rules1-noAddGlobal1.tex}{\texttt{myenv-args.tex} using \cref{lst:noAdditionalIndentGlobal:environments}}{lst:myenv-args-no-add-global1}
	\end{minipage}
	\hfill
	\begin{minipage}{.45\textwidth}
		\cmhlistingsfromfile{demonstrations/myenvironment-args-rules1-noAddGlobal2.tex}{\texttt{myenv-args.tex} using \cref{lst:noAdditionalIndentGlobal:environments,lst:myenv-rules1}}{lst:myenv-args-no-add-global2}
	\end{minipage}

	In fact, \texttt{noAdditionalIndentGlobal} also contains keys that control the
	indentation of optional and mandatory arguments; on referencing
	\cref{lst:opt-args-no-add-glob,lst:mand-args-no-add-glob}

	\begin{minipage}{.49\textwidth}
		\cmhlistingsfromfile[style=yaml-LST]*{demonstrations/opt-args-no-add-glob.yaml}[width=.8\linewidth,before=\centering,yaml-TCB]{\texttt{opt-args-no-add-glob.yaml}}{lst:opt-args-no-add-glob}
	\end{minipage}
	\hfill
	\begin{minipage}{.49\textwidth}
		\cmhlistingsfromfile[style=yaml-LST]*{demonstrations/mand-args-no-add-glob.yaml}[width=.8\linewidth,before=\centering,yaml-TCB]{\texttt{mand-args-no-add-glob.yaml}}{lst:mand-args-no-add-glob}
	\end{minipage}

	we may run the commands
	\index{switches!-l demonstration}
	\begin{commandshell}
latexindent.pl myenv-args.tex -local opt-args-no-add-glob.yaml
latexindent.pl myenv-args.tex -local mand-args-no-add-glob.yaml
\end{commandshell}
	which produces the respective outputs given in
	\cref{lst:myenv-args-no-add-opt,lst:myenv-args-no-add-mand}. Notice that in
	\cref{lst:myenv-args-no-add-opt} the \emph{optional} argument has not received any
	additional indentation, and in \cref{lst:myenv-args-no-add-mand} the \emph{mandatory}
	argument has not received any additional indentation.

	\begin{minipage}{.45\textwidth}
		\cmhlistingsfromfile{demonstrations/myenvironment-args-rules1-noAddGlobal3.tex}{\texttt{myenv-args.tex} using \cref{lst:opt-args-no-add-glob}}{lst:myenv-args-no-add-opt}
	\end{minipage}
	\hfill
	\begin{minipage}{.45\textwidth}
		\cmhlistingsfromfile{demonstrations/myenvironment-args-rules1-noAddGlobal4.tex}{\texttt{myenv-args.tex} using \cref{lst:mand-args-no-add-glob}}{lst:myenv-args-no-add-mand}
	\end{minipage}

\yamltitle{indentRulesGlobal}*{fields}
	The final check that \texttt{latexindent.pl} will make is to look for
	\texttt{indentRulesGlobal} as detailed in \cref{lst:indentRulesGlobal:environments}.

	\cmhlistingsfromfile[style=indentRulesGlobalEnv]*{../defaultSettings.yaml}[width=.5\linewidth,before=\centering,yaml-TCB]{\texttt{indentRulesGlobal}}{lst:indentRulesGlobal:environments}

	If you change the \texttt{environments} field to anything involving horizontal space, say
	\lstinline!" "!, and then run the following commands
	\index{switches!-l demonstration}

	\begin{commandshell}
latexindent.pl myenv-args.tex -l env-indentRules.yaml
latexindent.pl myenv-args.tex -l myenv-rules1.yaml,env-indentRules.yaml
\end{commandshell}
	then the respective output is shown in
	\cref{lst:myenv-args-indent-rules-global1,lst:myenv-args-indent-rules-global2}. Note that
	in \cref{lst:myenv-args-indent-rules-global1}, both the environment blocks have received
	a single-space indentation, whereas in \cref{lst:myenv-args-indent-rules-global2} the
	\texttt{outer} environment has received single-space indentation (specified by
	\texttt{indentRulesGlobal}), but \texttt{myenv} has received \lstinline!"   "!, as
	specified by the particular \texttt{indentRules} for \texttt{myenv}
	\vref{lst:myenv-rules1}.

	\begin{minipage}{.45\textwidth}
		\cmhlistingsfromfile[showspaces=true]{demonstrations/myenvironment-args-global-rules1.tex}{\texttt{myenv-args.tex} using \cref{lst:indentRulesGlobal:environments}}{lst:myenv-args-indent-rules-global1}
	\end{minipage}
	\hfill
	\begin{minipage}{.45\textwidth}
		\cmhlistingsfromfile[showspaces=true]{demonstrations/myenvironment-args-global-rules2.tex}{\texttt{myenv-args.tex} using \cref{lst:myenv-rules1,lst:indentRulesGlobal:environments}}{lst:myenv-args-indent-rules-global2}
	\end{minipage}

	You can specify \texttt{indentRulesGlobal} for both optional and mandatory arguments, as
	detailed in \cref{lst:opt-args-indent-rules-glob,lst:mand-args-indent-rules-glob}

	\begin{minipage}{.49\textwidth}
		\cmhlistingsfromfile[style=yaml-LST]*{demonstrations/opt-args-indent-rules-glob.yaml}[width=.9\linewidth,before=\centering,yaml-TCB]{\texttt{opt-args-indent-rules-glob.yaml}}{lst:opt-args-indent-rules-glob}
	\end{minipage}
	\hfill
	\begin{minipage}{.49\textwidth}
		\cmhlistingsfromfile[style=yaml-LST]*{demonstrations/mand-args-indent-rules-glob.yaml}[width=.9\linewidth,before=\centering,yaml-TCB]{\texttt{mand-args-indent-rules-glob.yaml}}{lst:mand-args-indent-rules-glob}
	\end{minipage}

	Upon running the following commands
	\index{switches!-l demonstration}
	\begin{commandshell}
latexindent.pl myenv-args.tex -local opt-args-indent-rules-glob.yaml
latexindent.pl myenv-args.tex -local mand-args-indent-rules-glob.yaml
\end{commandshell}
	we obtain the respective outputs in
	\cref{lst:myenv-args-indent-rules-global3,lst:myenv-args-indent-rules-global4}. Note that
	the \emph{optional} argument in \cref{lst:myenv-args-indent-rules-global3} has received
	two tabs worth of indentation, while the \emph{mandatory} argument has done so in
	\cref{lst:myenv-args-indent-rules-global4}.

	\begin{widepage}
		\begin{minipage}{.55\textwidth}
			\cmhlistingsfromfile[showtabs=true]{demonstrations/myenvironment-args-global-rules3.tex}{\texttt{myenv-args.tex} using \cref{lst:opt-args-indent-rules-glob}}{lst:myenv-args-indent-rules-global3}
		\end{minipage}
		\hfill
		\begin{minipage}{.55\textwidth}
			\cmhlistingsfromfile[showtabs=true]{demonstrations/myenvironment-args-global-rules4.tex}{\texttt{myenv-args.tex} using \cref{lst:mand-args-indent-rules-glob}}{lst:myenv-args-indent-rules-global4}
		\end{minipage}
	\end{widepage}