summaryrefslogtreecommitdiff
path: root/support/latexindent/documentation/subsubsec-environments-and-their-arguments.tex
blob: 4d750c298bb1b882e149a334fbf7e2c4fd4a9929 (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
% arara: pdflatex: { 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}