% 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}
