path: root/Master/texmf-dist/doc/support/latexindent/sec-default-user-local.tex

% arara: pdflatex: {shell: yes, files: [latexindent]}
\section{defaultSettings.yaml}\label{sec:defuseloc}
 \texttt{latexindent.pl} loads its settings from \texttt{defaultSettings.yaml}. The idea is to
 separate the behaviour of the script from the internal working -- this is very similar to
 the way that we separate content from form when writing our documents in \LaTeX.

 If you look in \texttt{defaultSettings.yaml} you'll find the switches that govern the behaviour
 of \texttt{latexindent.pl}. If you're not sure where \texttt{defaultSettings.yaml} resides on
 your computer, don't worry as \texttt{indent.log} will tell you where to find it.
 \texttt{defaultSettings.yaml} is commented, but here is a description of what each switch is
 designed to do. The default value is given in each case; whenever you see
 \emph{integer} in \emph{this} section, assume that it must be
 greater than or equal to \texttt{0} unless otherwise stated.

\yamltitle{fileExtensionPreference}*{fields}
	\texttt{latexindent.pl} can be called to
	act on a file without specifying the file extension.  For example we can call
	\begin{commandshell}
latexindent.pl myfile
\end{commandshell}
	in which case the script will look for \texttt{myfile} with the extensions
	specified in \texttt{fileExtensionPreference} in their numeric order. If no match is found, the
	script will exit. As with all of the fields, you should change and/or add to this as
	necessary.

	\cmhlistingsfromfile[style=fileExtensionPreference]*{../defaultSettings.yaml}[width=.8\linewidth,before=\centering,yaml-TCB]{\texttt{fileExtensionPreference}}{lst:fileExtensionPreference}

	Calling \texttt{latexindent.pl myfile} with the (default) settings specified in
	\cref{lst:fileExtensionPreference} means that the script will first look for
	\texttt{myfile.tex}, then \texttt{myfile.sty}, \texttt{myfile.cls}, and
	finally \texttt{myfile.bib} in order\footnote{Throughout this manual, listings shown with line numbers represent code
		taken directly from \texttt{defaultSettings.yaml}.}.

\yamltitle{backupExtension}*{extension name}

	If you call \texttt{latexindent.pl} with the \texttt{-w} switch (to overwrite
	\texttt{myfile.tex}) then it will create a backup file before doing any indentation;
	the default extension is \texttt{.bak}, so, for example,
	\texttt{myfile.bak0} would be created when calling \texttt{latexindent.pl myfile.tex} for the
	first time.

	By default, every time you subsequently call \texttt{latexindent.pl} with the
	\texttt{-w} to act upon \texttt{myfile.tex}, it will create successive
	back up files: \texttt{myfile.bak1}, \texttt{myfile.bak2}, etc.

\yamltitle{onlyOneBackUp}*{integer}
	\label{page:onlyonebackup}
	If you don't want a backup for every time that you call \texttt{latexindent.pl} (so
	you don't want \texttt{myfile.bak1}, \texttt{myfile.bak2}, etc) and you
	simply want \texttt{myfile.bak} (or whatever you chose \texttt{backupExtension} to be) then change \texttt{onlyOneBackUp} to
	\texttt{1}; the default value of \texttt{onlyOneBackUp} is
	\texttt{0}.

\yamltitle{maxNumberOfBackUps}*{integer}
	Some users may only want a finite number of backup files, say at most
	$3$, in which case, they can change this switch. The smallest value of
	\texttt{maxNumberOfBackUps} is $0$ which will \emph{not}
	prevent backup files being made; in this case, the behaviour will be dictated entirely by
	\texttt{onlyOneBackUp}. The default value of \texttt{maxNumberOfBackUps} is
	\texttt{0}.

\yamltitle{cycleThroughBackUps}*{integer}
	Some users may wish to cycle through backup files, by deleting the oldest backup file and
	keeping only the most recent; for example, with \texttt{maxNumberOfBackUps: 4}, and
	\texttt{cycleThroughBackUps} set to \texttt{1} then the \texttt{copy}
	procedure given below would be obeyed.

	\begin{commandshell}
copy myfile.bak1 to myfile.bak0
copy myfile.bak2 to myfile.bak1
copy myfile.bak3 to myfile.bak2
copy myfile.bak4 to myfile.bak3
\end{commandshell}
	The default value of \texttt{cycleThroughBackUps} is \texttt{0}.

\yamltitle{logFilePreferences}*{fields}
	\texttt{latexindent.pl} writes information to \texttt{indent.log}, some
	of which can be customized by changing \texttt{logFilePreferences}; see
	\cref{lst:logFilePreferences}. If you load your own user settings (see \vref{sec:indentconfig})
	then \texttt{latexindent.pl} will detail them in \texttt{indent.log}; you can choose
	not to have the details logged by switching \texttt{showEveryYamlRead} to
	\texttt{0}. Once all of your settings have been loaded, you can see the
	amalgamated settings in the log file by switching \texttt{showAmalgamatedSettings} to
	\texttt{1}, if you wish.

	\cmhlistingsfromfile[style=logFilePreferences,]*{../defaultSettings.yaml}[width=.9\linewidth,before=\centering,yaml-TCB]{\texttt{logFilePreferences}}{lst:logFilePreferences}

	When%
	\announce{2018-01-13}{showDecorationStartCodeBlockTrace feature for log file} either of the
	\texttt{trace} modes (see \cpageref{page:traceswitch}) are active, you will receive
	detailed information in \texttt{indent.log}. You can specify character strings to
	appear before and after the notification of a found code block using, respectively,
	\texttt{showDecorationStartCodeBlockTrace} and \texttt{showDecorationFinishCodeBlockTrace}. A demonstration is given in
	\vref{app:logfile-demo}.

	The log file will end with the characters given in \texttt{endLogFileWith}, and will
	report the \texttt{GitHub} address of \texttt{latexindent.pl} to the log file if
	\texttt{showGitHubInfoFooter} is set to \texttt{1}.

	\texttt{latexindent.pl}%
	\announce{2018-01-13}{log file pattern layout for log file} uses the \texttt{log4perl} module \cite{log4perl}
	to handle the creation of the logfile. You can specify the layout of the information
	given in the logfile using any of the \texttt{Log Layouts} detailed at
	\cite{log4perl}.

\yamltitle{verbatimEnvironments}*{fields}

	A field that contains a list of environments that you would like left completely alone --
	no indentation will be performed on environments that you have specified in this field,
	see \cref{lst:verbatimEnvironments}.

	\begin{cmhtcbraster}[raster column skip=.1\linewidth]
		\cmhlistingsfromfile[style=verbatimEnvironments]*{../defaultSettings.yaml}[width=.8\linewidth,before=\centering,yaml-TCB]{\texttt{verbatimEnvironments}}{lst:verbatimEnvironments}
		\cmhlistingsfromfile[style=verbatimCommands]*{../defaultSettings.yaml}[width=.8\linewidth,before=\centering,yaml-TCB]{\texttt{verbatimCommands}}{lst:verbatimCommands}
	\end{cmhtcbraster}

	Note that if you put an environment in	\texttt{verbatimEnvironments} and in other fields such
	as \texttt{lookForAlignDelims} or \texttt{noAdditionalIndent} then \texttt{latexindent.pl} will
	\emph{always} prioritize  \texttt{verbatimEnvironments}.

\yamltitle{verbatimCommands}*{fields}
	A field that contains a list of commands that are verbatim commands, for example
	\lstinline|\lstinline|; any commands populated in this field are protected from line
	breaking routines (only relevant if the \texttt{-m} is active, see
	\vref{sec:modifylinebreaks}).

\yamltitle{noIndentBlock}*{fields}

	If you have a block of code that you don't want \texttt{latexindent.pl} to touch (even if
	it is \emph{not} a verbatim-like environment) then you can wrap it in an
	environment from \texttt{noIndentBlock}; you can use any name you like for this,
	provided you populate it as demonstrate in \cref{lst:noIndentBlock}.

	\cmhlistingsfromfile[style=noIndentBlock]*{../defaultSettings.yaml}[width=.4\linewidth,before=\centering,yaml-TCB]{\texttt{noIndentBlock}}{lst:noIndentBlock}

	Of course, you don't want to have to specify these as null environments in your code, so
	you use them with a comment symbol, \lstinline!%!, followed by as many spaces
	(possibly none) as you like; see \cref{lst:noIndentBlockdemo} for example.

	\begin{cmhlistings}[style=demo,escapeinside={(*@}{@*)}]{\texttt{noIndentBlock} demonstration}{lst:noIndentBlockdemo}
%(*@@*) \begin{noindent}
        this code
                won't
     be touched
                    by
             latexindent.pl!
%(*@@*)\end{noindent}
	\end{cmhlistings}

\yamltitle{removeTrailingWhitespace}*{fields}\label{yaml:removeTrailingWhitespace}

	Trailing white space can be removed both \emph{before} and
	\emph{after} processing the document, as detailed in \cref{lst:removeTrailingWhitespace};
	each of the fields can take the values \texttt{0} or
	\texttt{1}. See \vref{lst:removeTWS-before,lst:env-mlb5-modAll,lst:env-mlb5-modAll-remove-WS} for before and after results. Thanks
	to \cite{vosskuhle} for providing this feature.

	\begin{minipage}{.4\textwidth}
		\cmhlistingsfromfile[style=removeTrailingWhitespace]*{../defaultSettings.yaml}[before=\centering,yaml-TCB]{removeTrailingWhitespace}{lst:removeTrailingWhitespace}
	\end{minipage}%
	\hfill
	\begin{minipage}{.5\textwidth}
		\begin{yaml}[numbers=none]{removeTrailingWhitespace (alt)}[before=\centering]{lst:removeTrailingWhitespace-alt}
removeTrailingWhitespace: 1
\end{yaml}
	\end{minipage}%

	You can specify \texttt{removeTrailingWhitespace} simply as \texttt{0} or
	\texttt{1}, if you wish; in this case,%
	\announce{2017-06-28}{removeTrailingWhitespace} \texttt{latexindent.pl} will set both \texttt{beforeProcessing} and
	\texttt{afterProcessing} to the value you specify; see \cref{lst:removeTrailingWhitespace-alt}.
\yamltitle{fileContentsEnvironments}*{field}

	Before \texttt{latexindent.pl} determines the difference between preamble (if any) and
	the main document, it first searches for any of the environments specified in
	\texttt{fileContentsEnvironments}, see \cref{lst:fileContentsEnvironments}. The behaviour of
	\texttt{latexindent.pl} on these environments is determined by their location (preamble
	or not), and the value \texttt{indentPreamble}, discussed next.

	\cmhlistingsfromfile[style=fileContentsEnvironments]*{../defaultSettings.yaml}[width=.8\linewidth,before=\centering,yaml-TCB]{\texttt{fileContentsEnvironments}}{lst:fileContentsEnvironments}

\yamltitle{indentPreamble}{0|1}

	The preamble of a document can sometimes contain some trickier code for
	\texttt{latexindent.pl} to operate upon. By default, \texttt{latexindent.pl} won't try to
	operate on the preamble (as \texttt{indentPreamble} is set to \texttt{0}, by
	default), but if you'd like \texttt{latexindent.pl} to try then change
	\texttt{indentPreamble} to \texttt{1}.

\yamltitle{lookForPreamble}*{fields}

	Not all files contain preamble; for example, \texttt{sty},
	\texttt{cls} and \texttt{bib} files typically do
	\emph{not}. Referencing \cref{lst:lookForPreamble}, if you set, for example,
	\texttt{.tex} to \texttt{0}, then regardless of the setting of the
	value of \texttt{indentPreamble}, preamble will not be assumed when operating upon
	\texttt{.tex} files.

	\cmhlistingsfromfile[style=lookForPreamble]*{../defaultSettings.yaml}[width=.8\linewidth,before=\centering,yaml-TCB]{lookForPreamble}{lst:lookForPreamble}
\yamltitle{preambleCommandsBeforeEnvironments}{0|1}
	Assuming that \texttt{latexindent.pl} is asked to operate upon the preamble of a
	document, when this switch is set to \texttt{0} then environment code blocks
	will be sought first, and then command code blocks. When this switch is set to
	\texttt{1}, commands will be sought first. The example that first motivated
	this switch contained the code given in \cref{lst:motivatepreambleCommandsBeforeEnvironments}.

	\begin{cmhlistings}{Motivating \texttt{preambleCommandsBeforeEnvironments}}{lst:motivatepreambleCommandsBeforeEnvironments}
...
preheadhook={\begin{mdframed}[style=myframedstyle]},
postfoothook=\end{mdframed},
...
\end{cmhlistings}

\yamltitle{defaultIndent}*{horizontal space}
	This is the default indentation (\lstinline!\t! means a tab, and is the default
	value) used in the absence of other details for the command or environment we are working
	with; see \texttt{indentRules} in \vref{sec:noadd-indent-rules} for more details.

	If you're interested in experimenting with \texttt{latexindent.pl} then you can
	\emph{remove} all indentation by setting \texttt{defaultIndent: ""}.

\yamltitle{lookForAlignDelims}*{fields}\label{yaml:lookforaligndelims}
	This contains a list of environments and/or commands that are operated upon in a special
	way by \texttt{latexindent.pl} (see \cref{lst:aligndelims:basic}). In fact, the fields in \texttt{lookForAlignDelims} can
	actually take two different forms: the \emph{basic} version is shown in
	\cref{lst:aligndelims:basic} and the \emph{advanced} version in
	\cref{lst:aligndelims:advanced}; we will discuss each in turn.

	\begin{yaml}[numbers=none]{\texttt{lookForAlignDelims} (basic)}[width=.8\linewidth,before=\centering]{lst:aligndelims:basic}
lookForAlignDelims:
   tabular: 1
   tabularx: 1
   longtable: 1
   array: 1
   matrix: 1
   ...
	\end{yaml}

	The environments specified in this field will be operated on in a special way by
	\texttt{latexindent.pl}. In particular, it will try and align each column by its
	alignment tabs. It does have some limitations (discussed further in
	\cref{sec:knownlimitations}), but in many cases it will produce results such as those in
	\cref{lst:tabularbefore:basic,lst:tabularafter:basic}.

	If you find that \texttt{latexindent.pl} does not perform satisfactorily on such
	environments then you can set the relevant key to \texttt{0}, for example
	\texttt{tabular: 0}; alternatively, if you just want to ignore
	\emph{specific} instances of the environment, you could wrap them in something
	from \texttt{noIndentBlock} (see \vref{lst:noIndentBlock}).

	\begin{cmhtcbraster}
		\cmhlistingsfromfile{demonstrations/tabular1.tex}{\texttt{tabular1.tex}}{lst:tabularbefore:basic}
		\cmhlistingsfromfile{demonstrations/tabular1-default.tex}{\texttt{tabular1.tex} default output}{lst:tabularafter:basic}
	\end{cmhtcbraster}

	If, for example, you wish to remove the alignment of the \lstinline!\\! within a
	delimiter-aligned block, then the advanced form of \texttt{lookForAlignDelims} shown in
	\cref{lst:aligndelims:advanced} is for you.

	\cmhlistingsfromfile*[style=lookForAlignDelims]*{../defaultSettings.yaml}[width=.8\linewidth,before=\centering,yaml-TCB]{\texttt{lookForAlignDelims} (advanced)}{lst:aligndelims:advanced}

	Note that you can use a mixture of the basic and advanced form: in
	\cref{lst:aligndelims:advanced} \texttt{tabular} and \texttt{tabularx} are advanced
	and \texttt{longtable} is basic. When using the advanced form, each field should
	receive at least 1 sub-field, and \emph{can}
	(but does not have to) receive any of the following
	fields:
	\begin{itemize}
		\item \texttt{delims}: binary switch (0 or 1) equivalent to simply specifying, for
		      example, \texttt{tabular: 1} in the basic version shown in \cref{lst:aligndelims:basic}. If
		      \texttt{delims} is set to \texttt{0} then the align at ampersand
		      routine will not be called for this code block (default: 1);
		\item \texttt{alignDoubleBackSlash}: binary switch (0 or 1) to determine if \lstinline!\\!
		      should be aligned (default: 1);
		\item \texttt{spacesBeforeDoubleBackSlash}: optionally,%
		      \announce{2018-01-13}*{update to spacesBeforeDoubleBackSlash in ampersand alignment} specifies the number (integer $\geq$ 0) of spaces
		      to be inserted before \lstinline!\\! (default: 1). \footnote{Previously this only activated if \texttt{alignDoubleBackSlash} was set to \texttt{0}.}
		\item \announce{2017-06-19}{multiColumnGrouping} \texttt{multiColumnGrouping}: binary switch (0 or 1) that details if
		      \texttt{latexindent.pl} should group columns
		      above and below a \lstinline!\multicolumn! command (default: 0);
		\item \announce{2017-06-19}{alignRowsWithoutMaxDelims} \texttt{alignRowsWithoutMaxDelims}: binary switch (0 or 1) that details if
		      rows that do not contain the maximum number of delimeters should be formatted so as to
		      have the ampersands aligned (default: 1);
		\item \announce{2018-01-13}{spacesBeforeAmpersand in ampersand alignment}\texttt{spacesBeforeAmpersand}: optionally specifies the number (integer
		      $\geq$ 0) of
		      spaces to be placed \emph{before} ampersands (default: 1);
		\item \announce{2018-01-13}{spacesAfterAmpersand in ampersand alignment}\texttt{spacesAfterAmpersand}: optionally specifies the number (integer
		      $\geq$ 0) of
		      spaces to be placed \emph{After} ampersands (default: 1);
		\item \announce{2018-01-13}{justification of cells in ampersand alignment}\texttt{justification}: optionally specifies the justification of
		      each cell as either \emph{left} or \emph{right} (default: left);
		\item \announce*{2020-03-21}{align final double back slash}{alignFinalDoubleBackSlash} optionally specifies if the
		      \emph{final} double back slash should be used for alignment (default: 0);
		\item \announce*{2020-03-21}{don't measure feature}{dontMeasure} optionally specifies if
		      user-specified cells, rows or the largest entries should \emph{not} be
		      measured (default: 0);
		\item \announce*{2020-03-21}{delimiter RegEx feature}{delimiterRegEx} optionally specifies the pattern
		      matching to be used for the alignment delimeter (default: \lstinline3 '(?<!\\)(&)'3);
		\item \announce*{2020-03-21}{delimiter justification}{delimiterJustification} optionally specifies the justification
		      for the alignment delimeters (default: left); note that this feature is only useful if
		      you have delimiters of different lengths in the same column, discussed in
		      \cref{sec:delimiter-reg-ex}.
	\end{itemize}

	We will explore most of these features using the file \texttt{tabular2.tex} in
	\cref{lst:tabular2} (which contains a \lstinline!\multicolumn! command), and the YAML files in \crefrange{lst:tabular2YAML}{lst:tabular8YAML}; we will explore
	\texttt{alignFinalDoubleBackSlash} in \cref{lst:tabular4}; the \texttt{dontMeasure} feature
	will be described in \cref{sec:dontMeasure}, and \texttt{delimiterRegEx} in
	\cref{sec:delimiter-reg-ex}.

	\cmhlistingsfromfile{demonstrations/tabular2.tex}{\texttt{tabular2.tex}}{lst:tabular2}
	\begin{minipage}{.45\textwidth}
		\cmhlistingsfromfile[style=yaml-LST]*{demonstrations/tabular2.yaml}[yaml-TCB]{\texttt{tabular2.yaml}}{lst:tabular2YAML}
	\end{minipage}%
	\hfill
	\begin{minipage}{.48\textwidth}
		\cmhlistingsfromfile[style=yaml-LST]*{demonstrations/tabular3.yaml}[yaml-TCB]{\texttt{tabular3.yaml}}{lst:tabular3YAML}
	\end{minipage}%

	\begin{minipage}{.45\textwidth}
		\cmhlistingsfromfile[style=yaml-LST]*{demonstrations/tabular4.yaml}[yaml-TCB]{\texttt{tabular4.yaml}}{lst:tabular4YAML}
	\end{minipage}%
	\hfill
	\begin{minipage}{.48\textwidth}
		\cmhlistingsfromfile[style=yaml-LST]*{demonstrations/tabular5.yaml}[yaml-TCB]{\texttt{tabular5.yaml}}{lst:tabular5YAML}
	\end{minipage}%

	\begin{minipage}{.45\textwidth}
		\cmhlistingsfromfile[style=yaml-LST]*{demonstrations/tabular6.yaml}[yaml-TCB]{\texttt{tabular6.yaml}}{lst:tabular6YAML}
	\end{minipage}%
	\hfill
	\begin{minipage}{.48\textwidth}
		\cmhlistingsfromfile[style=yaml-LST]*{demonstrations/tabular7.yaml}[yaml-TCB]{\texttt{tabular7.yaml}}{lst:tabular7YAML}
	\end{minipage}%

	\begin{minipage}{.48\textwidth}
		\cmhlistingsfromfile[style=yaml-LST]*{demonstrations/tabular8.yaml}[yaml-TCB]{\texttt{tabular8.yaml}}{lst:tabular8YAML}
	\end{minipage}%

	On running the commands
	\begin{commandshell}
latexindent.pl tabular2.tex 
latexindent.pl tabular2.tex -l tabular2.yaml
latexindent.pl tabular2.tex -l tabular3.yaml
latexindent.pl tabular2.tex -l tabular2.yaml,tabular4.yaml
latexindent.pl tabular2.tex -l tabular2.yaml,tabular5.yaml
latexindent.pl tabular2.tex -l tabular2.yaml,tabular6.yaml
latexindent.pl tabular2.tex -l tabular2.yaml,tabular7.yaml
latexindent.pl tabular2.tex -l tabular2.yaml,tabular8.yaml
\end{commandshell}
	we obtain the respective outputs given in \crefrange{lst:tabular2-default}{lst:tabular2-mod8}.

	\begin{widepage}
		\cmhlistingsfromfile{demonstrations/tabular2-default.tex}{\texttt{tabular2.tex} default output}{lst:tabular2-default}
		\cmhlistingsfromfile{demonstrations/tabular2-mod2.tex}{\texttt{tabular2.tex} using \cref{lst:tabular2YAML}}{lst:tabular2-mod2}
		\cmhlistingsfromfile{demonstrations/tabular2-mod3.tex}{\texttt{tabular2.tex} using \cref{lst:tabular3YAML}}{lst:tabular2-mod3}
		\cmhlistingsfromfile{demonstrations/tabular2-mod4.tex}{\texttt{tabular2.tex} using \cref{lst:tabular2YAML,lst:tabular4YAML}}{lst:tabular2-mod4}
		\cmhlistingsfromfile{demonstrations/tabular2-mod5.tex}{\texttt{tabular2.tex} using \cref{lst:tabular2YAML,lst:tabular5YAML}}{lst:tabular2-mod5}
		\cmhlistingsfromfile{demonstrations/tabular2-mod6.tex}{\texttt{tabular2.tex} using \cref{lst:tabular2YAML,lst:tabular6YAML}}{lst:tabular2-mod6}
		\cmhlistingsfromfile{demonstrations/tabular2-mod7.tex}{\texttt{tabular2.tex} using \cref{lst:tabular2YAML,lst:tabular7YAML}}{lst:tabular2-mod7}
		\cmhlistingsfromfile{demonstrations/tabular2-mod8.tex}{\texttt{tabular2.tex} using \cref{lst:tabular2YAML,lst:tabular8YAML}}{lst:tabular2-mod8}
	\end{widepage}

	Notice in particular:
	\begin{itemize}
		\item in both \cref{lst:tabular2-default,lst:tabular2-mod2} all rows have been aligned at the ampersand, even those
		      that do not contain the maximum number of ampersands (3 ampersands, in this case);
		\item in \cref{lst:tabular2-default} the columns have been aligned at the ampersand;
		\item in \cref{lst:tabular2-mod2} the \lstinline!\multicolumn! command has grouped the
		      $2$ columns beneath \emph{and} above it, because
		      \texttt{multiColumnGrouping} is set to $1$ in \cref{lst:tabular2YAML};
		\item in \cref{lst:tabular2-mod3} rows~3 and~6 have \emph{not} been aligned at the
		      ampersand, because \texttt{alignRowsWithoutMaxDelims} has been to set to $0$ in
		      \cref{lst:tabular3YAML}; however, the \lstinline!\\! \emph{have} still
		      been aligned;
		\item in \cref{lst:tabular2-mod4} the columns beneath and above the \lstinline!\multicolumn!
		      commands have been grouped (because \texttt{multiColumnGrouping} is set to
		      $1$), and there are at least $4$ spaces
		      \emph{before} each aligned ampersand because \texttt{spacesBeforeAmpersand} is set to
		      $4$;
		\item in \cref{lst:tabular2-mod5} the columns beneath and above the \lstinline!\multicolumn!
		      commands have been grouped (because \texttt{multiColumnGrouping} is set to
		      $1$), and there are at least $4$ spaces
		      \emph{after} each aligned ampersand because \texttt{spacesAfterAmpersand} is set to
		      $4$;
		\item in \cref{lst:tabular2-mod6} the \lstinline!\\! have \emph{not} been
		      aligned, because \texttt{alignDoubleBackSlash} is set to \texttt{0}, otherwise the
		      output is the same as \cref{lst:tabular2-mod2};
		\item in \cref{lst:tabular2-mod7} the \lstinline!\\! \emph{have} been
		      aligned, and because \texttt{spacesBeforeDoubleBackSlash} is set to \texttt{0}, there are
		      no spaces ahead of them; the output is otherwise the same as \cref{lst:tabular2-mod2}.
		\item in \cref{lst:tabular2-mod8} the cells have been \emph{right}-justified; note
		      that cells above and below the \lstinline!\multicol! statements have still been group
		      correctly, because of the settings in \cref{lst:tabular2YAML}.
	\end{itemize}

	We explore%
	\announce*{2020-03-21}{alignFinalDoubleBackSlash demonstration} the
	\texttt{alignFinalDoubleBackSlash} feature by using the file in \cref{lst:tabular4}. Upon
	running the following commands
	\begin{commandshell}
latexindent.pl tabular4.tex -o=+-default
latexindent.pl tabular4.tex -o=+-FDBS -y="lookForAlignDelims:tabular:alignFinalDoubleBackSlash:1"
\end{commandshell}
	then we receive the respective outputs given in \cref{lst:tabular4-default} and
	\cref{lst:tabular4-FDBS}.

	\begin{cmhtcbraster}[raster columns=3,
			raster left skip=-3.75cm,
			raster right skip=-2cm,]
		\cmhlistingsfromfile*{demonstrations/tabular4.tex}{\texttt{tabular4.tex}}{lst:tabular4}
		\cmhlistingsfromfile*{demonstrations/tabular4-default.tex}{\texttt{tabular4-default.tex}}{lst:tabular4-default}
		\cmhlistingsfromfile*{demonstrations/tabular4-FDBS.tex}{\texttt{tabular4-FDBS.tex}}{lst:tabular4-FDBS}
	\end{cmhtcbraster}

	We note that in:
	\begin{itemize}
		\item \cref{lst:tabular4-default}, by default, the \emph{first} set of double back
		      slashes in the first row of the \texttt{tabular} environment have been used for
		      alignment;
		\item \cref{lst:tabular4-FDBS}, the \emph{final} set of double back slashes in the
		      first row have been used, because we specified \texttt{alignFinalDoubleBackSlash} as 1.
	\end{itemize}

	As of Version 3.0, the alignment routine works on mandatory and optional arguments within
	commands, and also within `special' code blocks (see \texttt{specialBeginEnd} on
	\cpageref{yaml:specialBeginEnd}); for example, assuming that you have a command called
	\lstinline!\matrix! and that it is populated within \texttt{lookForAlignDelims} (which it is, by default), and that
	you run the command
	\begin{commandshell}
latexindent.pl matrix1.tex 
\end{commandshell}
	then the before-and-after results shown in \cref{lst:matrixbefore,lst:matrixafter} are achievable by
	default.

	\begin{cmhtcbraster}
		\cmhlistingsfromfile{demonstrations/matrix1.tex}{\texttt{matrix1.tex}}{lst:matrixbefore}
		\cmhlistingsfromfile{demonstrations/matrix1-default.tex}{\texttt{matrix1.tex} default output}{lst:matrixafter}
	\end{cmhtcbraster}

	If you have blocks of code that you wish to align at the \&  character that are
	\emph{not} wrapped in, for example, \lstinline!\begin{tabular}! \ldots
	\lstinline!\end{tabular}!, then you can use the mark up illustrated in
	\cref{lst:alignmentmarkup}; the default output is shown in \cref{lst:alignmentmarkup-default}. Note
	that the \lstinline!%*! must be next to each other, but that there can be any
	number of spaces (possibly none) between the
	\lstinline!*! and \lstinline!\begin{tabular}!; note also that you may use any
	environment name that you have specified in \texttt{lookForAlignDelims}.

	\begin{cmhtcbraster}
		\cmhlistingsfromfile{demonstrations/align-block.tex}{\texttt{align-block.tex}}{lst:alignmentmarkup}
		\cmhlistingsfromfile{demonstrations/align-block-default.tex}{\texttt{align-block.tex} default output}{lst:alignmentmarkup-default}
	\end{cmhtcbraster}

	With reference to \vref{tab:code-blocks} and the, yet undiscussed, fields of
	\texttt{noAdditionalIndent} and \texttt{indentRules}
	(see \vref{sec:noadd-indent-rules}), these comment-marked blocks are
	considered \texttt{environments}.

\subsection{lookForAlignDelims: the dontMeasure feature}\label{sec:dontMeasure}
	The%
	\announce*{2020-03-21}{don't measure feature} \texttt{lookForAlignDelims}
	field can, optionally, receive the \texttt{dontMeasure} option which can be specified
	in a few different ways. We will explore this feature in relation to the code given in
	\cref{lst:tabular-DM}; the default output is shown in \cref{lst:tabular-DM-default}.

	\begin{cmhtcbraster}
		\cmhlistingsfromfile*{demonstrations/tabular-DM.tex}{\texttt{tabular-DM.tex}}{lst:tabular-DM}
		\cmhlistingsfromfile*{demonstrations/tabular-DM-default.tex}{\texttt{tabular-DM.tex} default output}{lst:tabular-DM-default}
	\end{cmhtcbraster}

	The \texttt{dontMeasure} field can be specified as \texttt{largest}, and in
	which case, the largest element will not be measured; with reference to the YAML file
	given in \cref{lst:dontMeasure1}, we can run the command
	\begin{commandshell} 
latexindent.pl tabular-DM.tex -l=dontMeasure1.yaml
\end{commandshell}
	and receive the output given in \cref{lst:tabular-DM-mod1}.

	\begin{cmhtcbraster}
		\cmhlistingsfromfile*{demonstrations/tabular-DM-mod1.tex}{\texttt{tabular-DM.tex} using \cref{lst:dontMeasure1}}{lst:tabular-DM-mod1}
		\cmhlistingsfromfile*{demonstrations/dontMeasure1.yaml}[yaml-TCB]{\texttt{dontMeasure1.yaml}}{lst:dontMeasure1}
	\end{cmhtcbraster}

	We note that the \emph{largest} column entries have not contributed to the
	measuring routine.

	The \texttt{dontMeasure} field can also be specified in the form demonstrated in
	\cref{lst:dontMeasure2}. On running the following commands,
	\begin{commandshell} 
latexindent.pl tabular-DM.tex -l=dontMeasure2.yaml
\end{commandshell}
	we receive the output in \cref{lst:tabular-DM-mod2}.

	\begin{cmhtcbraster}
		\cmhlistingsfromfile*{demonstrations/tabular-DM-mod2.tex}{\texttt{tabular-DM.tex} using \cref{lst:dontMeasure2} or \cref{lst:dontMeasure3}}{lst:tabular-DM-mod2}
		\cmhlistingsfromfile*{demonstrations/dontMeasure2.yaml}[yaml-TCB]{\texttt{dontMeasure2.yaml}}{lst:dontMeasure2}
	\end{cmhtcbraster}

	We note that in \cref{lst:dontMeasure2} we have specified entries not to be measured, one
	entry per line.

	The \texttt{dontMeasure} field can also be specified in the forms demonstrated in
	\cref{lst:dontMeasure3} and \cref{lst:dontMeasure4}. Upon running the commands
	\begin{commandshell} 
latexindent.pl tabular-DM.tex -l=dontMeasure3.yaml
latexindent.pl tabular-DM.tex -l=dontMeasure4.yaml
\end{commandshell}
	we receive the output given in \cref{lst:tabular-DM-mod3}
	\begin{cmhtcbraster}[raster columns=3,
			raster left skip=-3.5cm,
			raster right skip=-2cm,
			raster column skip=.03\linewidth]
		\cmhlistingsfromfile*{demonstrations/tabular-DM-mod3.tex}{\texttt{tabular-DM.tex} using \cref{lst:dontMeasure3} or \cref{lst:dontMeasure3}}{lst:tabular-DM-mod3}
		\cmhlistingsfromfile*{demonstrations/dontMeasure3.yaml}[yaml-TCB]{\texttt{dontMeasure3.yaml}}{lst:dontMeasure3}
		\cmhlistingsfromfile*{demonstrations/dontMeasure4.yaml}[yaml-TCB]{\texttt{dontMeasure4.yaml}}{lst:dontMeasure4}
	\end{cmhtcbraster}
	We note that in:
	\begin{itemize}
		\item \cref{lst:dontMeasure3} we have specified entries not to be measured, each one has a
		      \emph{string} in the \texttt{this}
		      field, together with an optional specification of \texttt{applyTo} as
		      \texttt{cell};
		\item \cref{lst:dontMeasure4} we have specified entries not to be measured as a
		      \emph{regular expression} using
		      the \texttt{regex} field, together with an optional specification of
		      \texttt{applyTo} as \texttt{cell} field, together with an optional
		      specification of \texttt{applyTo} as \texttt{cell}.
	\end{itemize}
	In both cases, the default value of \texttt{applyTo} is \texttt{cell},
	and does not need to be specified.

	We may also specify the \texttt{applyTo} field as \texttt{row}, a
	demonstration of which is given in \cref{lst:dontMeasure5}; upon running
	\begin{commandshell} 
latexindent.pl tabular-DM.tex -l=dontMeasure5.yaml
\end{commandshell}
	we receive the output in \cref{lst:tabular-DM-mod5}.
	\begin{cmhtcbraster}
		\cmhlistingsfromfile*{demonstrations/tabular-DM-mod5.tex}{\texttt{tabular-DM.tex} using \cref{lst:dontMeasure5}}{lst:tabular-DM-mod5}
		\cmhlistingsfromfile*{demonstrations/dontMeasure5.yaml}[yaml-TCB]{\texttt{dontMeasure5.yaml}}{lst:dontMeasure5}
	\end{cmhtcbraster}

	Finally, the \texttt{applyTo} field can be specified as \texttt{row},
	together with a \texttt{regex} expression. For example, for the settings given
	in \cref{lst:dontMeasure6}, upon running
	\begin{commandshell} 
latexindent.pl tabular-DM.tex -l=dontMeasure6.yaml
\end{commandshell}
	we receive the output in \cref{lst:tabular-DM-mod6}.

	\begin{cmhtcbraster}
		\cmhlistingsfromfile*{demonstrations/tabular-DM-mod6.tex}{\texttt{tabular-DM.tex} using \cref{lst:dontMeasure6}}{lst:tabular-DM-mod6}
		\cmhlistingsfromfile*{demonstrations/dontMeasure6.yaml}[yaml-TCB]{\texttt{dontMeasure6.yaml}}{lst:dontMeasure6}
	\end{cmhtcbraster}

\subsection{lookForAlignDelims: the delimiterRegEx and delimiterJustification feature}\label{sec:delimiter-reg-ex}
	The delimiter alignment%
	\announce*{2020-03-21}{delimiterRegEx feature} will, by
	default, align code blocks at the ampersand character. The behaviour is controlled by the
	\texttt{delimiterRegEx} field within \texttt{lookForAlignDelims}; the default value is
	\lstinline3'(?<!\\)(&)'3, which can be read as: \emph{an ampersand, as long as it is not immediately preceeded by a backslash}.

	\begin{warning}
		Important: note the `capturing' parenthesis in the \lstinline!(&)! which are necessary; if you
		intend to customise this field, then be sure to include them appropriately.
	\end{warning}

	We demonstrate how to customise this with respect to the code given in
	\cref{lst:tabbing}; the default output from \lstinline!latexindent.pl! is given in
	\cref{lst:tabbing-default}.

	\begin{cmhtcbraster}
		\cmhlistingsfromfile*{demonstrations/tabbing.tex}{\texttt{tabbing.tex}}{lst:tabbing}
		\cmhlistingsfromfile*{demonstrations/tabbing-default.tex}{\texttt{tabbing.tex} default output}{lst:tabbing-default}
	\end{cmhtcbraster}

	Let's say that we wish to align the code at either the \lstinline!\=! or
	\lstinline!\>!. We employ the settings given in \cref{lst:delimiterRegEx1} and run
	the command
	\begin{commandshell}
latexindent.pl tabbing.tex -l=delimiterRegEx1.yaml
\end{commandshell}
	to receive the output given in \cref{lst:tabbing-mod1}.

	\begin{cmhtcbraster}
		\cmhlistingsfromfile*{demonstrations/tabbing-mod1.tex}{\texttt{tabbing.tex} using \cref{lst:delimiterRegEx1}}{lst:tabbing-mod1}
		\cmhlistingsfromfile*{demonstrations/delimiterRegEx1.yaml}[yaml-TCB]{\texttt{delimiterRegEx1.yaml}}{lst:delimiterRegEx1}
	\end{cmhtcbraster}
	We note that:
	\begin{itemize}
		\item in \cref{lst:tabbing-mod1} the code has been aligned, as intended, at both the
		      \lstinline!\=! and \lstinline!\>!;
		\item in \cref{lst:delimiterRegEx1} we have heeded the warning and captured the expression using
		      grouping parenthesis, specified a backslash using \lstinline!\\! and said that
		      it must be followed by either \lstinline!=! or \lstinline!>!.
	\end{itemize}
	We can explore \texttt{delimiterRegEx} a little further using the settings in
	\cref{lst:delimiterRegEx2} and run the command
	\begin{commandshell}
latexindent.pl tabbing.tex -l=delimiterRegEx2.yaml
\end{commandshell}
	to receive the output given in \cref{lst:tabbing-mod2}.

	\begin{cmhtcbraster}
		\cmhlistingsfromfile*{demonstrations/tabbing-mod2.tex}{\texttt{tabbing.tex} using \cref{lst:delimiterRegEx2}}{lst:tabbing-mod2}
		\cmhlistingsfromfile*{demonstrations/delimiterRegEx2.yaml}[yaml-TCB]{\texttt{delimiterRegEx2.yaml}}{lst:delimiterRegEx2}
	\end{cmhtcbraster}
	We note that only the \lstinline!\>! have been aligned.

	Of course, the other lookForAlignDelims options can be used alongside the
	\texttt{delimiterRegEx}; regardless of the type of delimiter being used (ampersand or
	anything else), the fields from \vref{lst:aligndelims:advanced} remain the same; for example,
	using the settings in \cref{lst:delimiterRegEx3}, and running
	\begin{commandshell}
latexindent.pl tabbing.tex -l=delimiterRegEx3.yaml
\end{commandshell}
	to receive the output given in \cref{lst:tabbing-mod3}.

	\begin{cmhtcbraster}
		\cmhlistingsfromfile*{demonstrations/tabbing-mod3.tex}{\texttt{tabbing.tex} using \cref{lst:delimiterRegEx3}}{lst:tabbing-mod3}
		\cmhlistingsfromfile*{demonstrations/delimiterRegEx3.yaml}[yaml-TCB]{\texttt{delimiterRegEx3.yaml}}{lst:delimiterRegEx3}
	\end{cmhtcbraster}

	It is possible that delimiters specified within \texttt{delimiterRegEx} can be of
	different lengths. Consider the file in \cref{lst:tabbing1}, and associated YAML in
	\cref{lst:delimiterRegEx4}. Note that the \cref{lst:delimiterRegEx4} specifies the option for
	the delimiter to be either
	\lstinline!#! or
	\lstinline!\>!, \emph{which are different lengths}. Upon running the command
	\begin{commandshell}
latexindent.pl tabbing1.tex -l=delimiterRegEx4.yaml -o=+-mod4
\end{commandshell}
	we receive the output in \cref{lst:tabbing1-mod4}.

	\begin{cmhtcbraster}[raster columns=3,
			raster left skip=-3.5cm,
			raster right skip=-2cm,
			raster column skip=.03\linewidth]
		\cmhlistingsfromfile*{demonstrations/tabbing1.tex}{\texttt{tabbing1.tex}}{lst:tabbing1}
		\cmhlistingsfromfile*{demonstrations/tabbing1-mod4.tex}{\texttt{tabbing1-mod4.tex}}{lst:tabbing1-mod4}
		\cmhlistingsfromfile*{demonstrations/delimiterRegEx4.yaml}[yaml-TCB]{\texttt{delimiterRegEx4.yaml}}{lst:delimiterRegEx4}
	\end{cmhtcbraster}

	You can set the \emph{delimiter} justification as either \texttt{left} (default)
	or \texttt{right}, which will only have effect when delimiters in the same
	column have different lengths. Using the settings in \cref{lst:delimiterRegEx5} and running
	the command
	\begin{commandshell}
latexindent.pl tabbing1.tex -l=delimiterRegEx5.yaml -o=+-mod5
\end{commandshell}
	gives the output in \cref{lst:tabbing1-mod5}.

	\begin{cmhtcbraster}
		\cmhlistingsfromfile*{demonstrations/tabbing1-mod5.tex}{\texttt{tabbing1-mod5.tex}}{lst:tabbing1-mod5}
		\cmhlistingsfromfile*{demonstrations/delimiterRegEx5.yaml}[yaml-TCB]{\texttt{delimiterRegEx5.yaml}}{lst:delimiterRegEx5}
	\end{cmhtcbraster}

	Note that in \cref{lst:tabbing1-mod5} the second set of delimiters have been
	\emph{right aligned} -- it is quite subtle!

\yamltitle{indentAfterItems}*{fields}
	The environment names specified in \texttt{indentAfterItems} tell \texttt{latexindent.pl}
	to look for \lstinline!\item! commands; if these switches are set to
	\texttt{1} then indentation will be performed so as indent the code after
	each \texttt{item}. A demonstration is given in \cref{lst:itemsbefore,lst:itemsafter}

	\begin{cmhtcbraster}[raster columns=3,
			raster left skip=-3.5cm,
			raster right skip=-2cm,
			raster column skip=.03\linewidth]
		\cmhlistingsfromfile[style=indentAfterItems]*{../defaultSettings.yaml}[width=.8\linewidth,before=\centering,yaml-TCB]{\texttt{indentAfterItems}}{lst:indentafteritems}
		\cmhlistingsfromfile{demonstrations/items1.tex}{\texttt{items1.tex}}{lst:itemsbefore}
		\cmhlistingsfromfile{demonstrations/items1-default.tex}{\texttt{items1.tex} default output}{lst:itemsafter}
	\end{cmhtcbraster}

\yamltitle{itemNames}*{fields}
	If you have your own \texttt{item} commands (perhaps you prefer to use
	\texttt{myitem}, for example) then you can put populate them in
	\texttt{itemNames}. For example, users of the \texttt{exam} document class
	might like to add \texttt{parts} to \texttt{indentAfterItems} and
	\texttt{part} to \texttt{itemNames} to their user settings (see
	\vref{sec:indentconfig} for details of how to configure user settings, and
	\vref{lst:mysettings} \\ in particular \label{page:examsettings}.)

	\cmhlistingsfromfile[style=itemNames]*{../defaultSettings.yaml}[width=.8\linewidth,before=\centering,yaml-TCB]{\texttt{itemNames}}{lst:itemNames}

\yamltitle{specialBeginEnd}*{fields}\label{yaml:specialBeginEnd}
	The fields specified%
	\announce{2017-08-21}*{specialBeginEnd} in
	\texttt{specialBeginEnd} are, in their default state, focused on math mode begin and end
	statements, but there is no requirement for this to be the case; \cref{lst:specialBeginEnd}
	shows the default settings of \texttt{specialBeginEnd}.

	\cmhlistingsfromfile[style=specialBeginEnd]*{../defaultSettings.yaml}[width=.8\linewidth,before=\centering,yaml-TCB]{\texttt{specialBeginEnd}}{lst:specialBeginEnd}

	The field \texttt{displayMath} represents \lstinline!\[...\]!,
	\texttt{inlineMath} represents
	\lstinline!$...$! and \texttt{displayMathTex} represents \lstinline!$$...$$!.
	You can, of course, rename these in your own YAML files (see \vref{sec:localsettings});
	indeed, you might like to set up your own special begin and end statements.

	A demonstration of the before-and-after results are shown in \cref{lst:specialbefore,lst:specialafter}.

	\begin{cmhtcbraster}
		\cmhlistingsfromfile{demonstrations/special1.tex}{\texttt{special1.tex} before}{lst:specialbefore}
		\cmhlistingsfromfile{demonstrations/special1-default.tex}{\texttt{special1.tex} default output}{lst:specialafter}
	\end{cmhtcbraster}

	For each field, \texttt{lookForThis} is set to \texttt{1} by default,
	which means that \texttt{latexindent.pl} will look for this pattern; you can tell
	\texttt{latexindent.pl} not to look for the pattern, by setting \texttt{lookForThis}
	to \texttt{0}.

	There are%
	\announce{2017-08-21}{specialBeforeCommand} examples in which it
	is advantageous to search for \texttt{specialBeginEnd} fields \emph{before}
	searching for commands, and the \texttt{specialBeforeCommand} switch controls this behaviour.
	For example, consider the file shown in \cref{lst:specialLRbefore}.

	\cmhlistingsfromfile{demonstrations/specialLR.tex}{\texttt{specialLR.tex}}{lst:specialLRbefore}

	Now consider the YAML files shown in \cref{lst:specialsLeftRight-yaml,lst:specialBeforeCommand-yaml}

	\begin{cmhtcbraster}
		\cmhlistingsfromfile[]*{demonstrations/specialsLeftRight.yaml}[width=.8\linewidth,before=\centering,yaml-TCB]{\texttt{specialsLeftRight.yaml}}{lst:specialsLeftRight-yaml}
		\cmhlistingsfromfile[]*{demonstrations/specialBeforeCommand.yaml}[width=.8\linewidth,before=\centering,yaml-TCB]{\texttt{specialBeforeCommand.yaml}}{lst:specialBeforeCommand-yaml}
	\end{cmhtcbraster}

	Upon running the following commands
	\begin{widepage}
		\begin{commandshell}
latexindent.pl specialLR.tex -l=specialsLeftRight.yaml      
latexindent.pl specialLR.tex -l=specialsLeftRight.yaml,specialBeforeCommand.yaml      
\end{commandshell}
	\end{widepage}
	we receive the respective outputs in \cref{lst:specialLR-comm-first-tex,lst:specialLR-special-first-tex}.

	\begin{minipage}{.49\linewidth}
		\cmhlistingsfromfile{demonstrations/specialLR-comm-first.tex}{\texttt{specialLR.tex} using \cref{lst:specialsLeftRight-yaml}}{lst:specialLR-comm-first-tex}
	\end{minipage}
	\hfill
	\begin{minipage}{.49\linewidth}
		\cmhlistingsfromfile{demonstrations/specialLR-special-first.tex}{\texttt{specialLR.tex} using \cref{lst:specialsLeftRight-yaml,lst:specialBeforeCommand-yaml}}{lst:specialLR-special-first-tex}
	\end{minipage}

	Notice that in:
	\begin{itemize}
		\item \cref{lst:specialLR-comm-first-tex} the \lstinline!\left! has been treated as a
		      \emph{command}, with one optional argument;
		\item \cref{lst:specialLR-special-first-tex} the \texttt{specialBeginEnd} pattern in \cref{lst:specialsLeftRight-yaml}
		      has been obeyed because \cref{lst:specialBeforeCommand-yaml} specifies that the
		      \texttt{specialBeginEnd} should be sought \emph{before} commands.
	\end{itemize}

	You can,optionally, specify%
	\announce{2018-04-27}{update to specialBeginEnd} the
	\texttt{middle} field for anything that you specify in \texttt{specialBeginEnd}.
	For example, let's consider the \texttt{.tex} file in \cref{lst:special2}.

	\cmhlistingsfromfile{demonstrations/special2.tex}{\texttt{special2.tex}}{lst:special2}

	Upon saving the YAML settings in \cref{lst:middle-yaml,lst:middle1-yaml} and running the commands
	\begin{commandshell}
latexindent.pl special2.tex -l=middle
latexindent.pl special2.tex -l=middle1
\end{commandshell}
	then we obtain the output given in \cref{lst:special2-mod1,lst:special2-mod2}.

	\begin{cmhtcbraster}
		\cmhlistingsfromfile{demonstrations/middle.yaml}[yaml-TCB]{\texttt{middle.yaml}}{lst:middle-yaml}
		\cmhlistingsfromfile{demonstrations/special2-mod1.tex}{\texttt{special2.tex} using \cref{lst:middle-yaml}}{lst:special2-mod1}
	\end{cmhtcbraster}

	\begin{cmhtcbraster}
		\cmhlistingsfromfile{demonstrations/middle1.yaml}[yaml-TCB]{\texttt{middle1.yaml}}{lst:middle1-yaml}
		\cmhlistingsfromfile{demonstrations/special2-mod2.tex}{\texttt{special2.tex} using \cref{lst:middle1-yaml}}{lst:special2-mod2}
	\end{cmhtcbraster}

	We note that:
	\begin{itemize}
		\item in \cref{lst:special2-mod1} the bodies of each of the \texttt{Elsif} statements
		      have been indented appropriately;
		\item the \texttt{Else} statement has \emph{not} been indented
		      appropriately in \cref{lst:special2-mod1} -- read on!
		\item we have specified multiple settings for the \texttt{middle} field using the
		      syntax demonstrated in \cref{lst:middle1-yaml} so that the body of the
		      \texttt{Else} statement has been indented appropriately in
		      \cref{lst:special2-mod2}.
	\end{itemize}

	You may%
	\announce{2018-08-13}{specialBeginEnd verbatim} specify fields in
	\texttt{specialBeginEnd} to be treated as verbatim code blocks by changing
	\texttt{lookForThis} to be \texttt{verbatim}.

	For example, beginning with the code in \cref{lst:special3-mod1} and the YAML in
	\cref{lst:special-verb1-yaml}, and running
	\begin{commandshell}
latexindent.pl special3.tex -l=special-verb1
\end{commandshell}
	then the output in \cref{lst:special3-mod1} is unchanged.

	\begin{cmhtcbraster}
		\cmhlistingsfromfile{demonstrations/special-verb1.yaml}[yaml-TCB]{\texttt{special-verb1.yaml}}{lst:special-verb1-yaml}
		\cmhlistingsfromfile{demonstrations/special3-mod1.tex}{\texttt{special3.tex} and output using \cref{lst:special-verb1-yaml}}{lst:special3-mod1}
	\end{cmhtcbraster}

	We can combine the \texttt{specialBeginEnd} with the \texttt{lookForAlignDelims} feature. We
	begin with the code in \cref{lst:special-align}.

	\cmhlistingsfromfile*{demonstrations/special-align.tex}{\texttt{special-align.tex}}{lst:special-align}

	Let's assume that our goal is to align the code at the \texttt{edge} and
	\texttt{node} text; we employ the code given in \cref{lst:edge-node1} and run
	the command
	\begin{commandshell}
latexindent.pl special-align.tex -l edge-node1.yaml -o=+-mod1
\end{commandshell}
	to receive the output in \cref{lst:special-align-mod1}.

	\begin{cmhtcbraster}[ raster left skip=-3.5cm,]
		\cmhlistingsfromfile*{demonstrations/edge-node1.yaml}[yaml-TCB]{\texttt{edge-node1.yaml}}{lst:edge-node1}
		\cmhlistingsfromfile*{demonstrations/special-align-mod1.tex}{\texttt{special-align.tex} using \cref{lst:edge-node1}}{lst:special-align-mod1}
	\end{cmhtcbraster}

	The output in \cref{lst:special-align-mod1} is not quite ideal. We can tweak the settings
	within \cref{lst:edge-node1} in order to improve the output; in particular, we employ
	the code in \cref{lst:edge-node2} and run the command
	\begin{commandshell}
latexindent.pl special-align.tex -l edge-node2.yaml -o=+-mod2
\end{commandshell}
	to receive the output in \cref{lst:special-align-mod2}.

	\begin{cmhtcbraster}[ raster left skip=-3.5cm,]
		\cmhlistingsfromfile*{demonstrations/edge-node2.yaml}[yaml-TCB]{\texttt{edge-node2.yaml}}{lst:edge-node2}
		\cmhlistingsfromfile*{demonstrations/special-align-mod2.tex}{\texttt{special-align.tex} using \cref{lst:edge-node2}}{lst:special-align-mod2}
	\end{cmhtcbraster}

\yamltitle{indentAfterHeadings}*{fields}
	This field enables the user to specify indentation rules that take effect after heading
	commands such as \lstinline!\part!, \lstinline!\chapter!,
	\lstinline!\section!, \lstinline!\subsection*!, or indeed any user-specified command
	written in this field.\footnote{There is a slight
		difference in interface for this field when comparing Version 2.2 to Version 3.0; see \vref{app:differences} for details.}

	\cmhlistingsfromfile[style=indentAfterHeadings]*{../defaultSettings.yaml}[width=.8\linewidth,before=\centering,yaml-TCB]{\texttt{indentAfterHeadings}}{lst:indentAfterHeadings}

	The default settings do \emph{not} place indentation after a heading, but
	you can easily switch them on by changing \texttt{indentAfterThisHeading} from 0 to 1. The
	\texttt{level} field tells \texttt{latexindent.pl} the hierarchy of the heading
	structure in your document. You might, for example, like to have both
	\texttt{section} and \texttt{subsection} set with \texttt{level: 3}
	because you do not want the indentation to go too deep.

	You can add any of your own custom heading commands to this field, specifying the
	\texttt{level} as appropriate.  You can also specify your own indentation in
	\texttt{indentRules} (see \vref{sec:noadd-indent-rules}); you will find the default \texttt{indentRules} contains
	\lstinline!chapter: " "! which tells \texttt{latexindent.pl} simply to use a space
	character after \texttt{\chapter} headings (once \texttt{indent} is set to
	\texttt{1} for \texttt{chapter}).

	For example, assuming that you have the code in \cref{lst:headings1yaml} saved into
	\texttt{headings1.yaml}, and that you have the text from \cref{lst:headings1} saved
	into \texttt{headings1.tex}.

	\begin{cmhtcbraster}
		\cmhlistingsfromfile[style=yaml-LST]*{demonstrations/headings1.yaml}[yaml-TCB]{\texttt{headings1.yaml}}{lst:headings1yaml}
		\cmhlistingsfromfile{demonstrations/headings1.tex}{\texttt{headings1.tex}}{lst:headings1}
	\end{cmhtcbraster}

	If you run the command
	\begin{commandshell}
latexindent.pl headings1.tex -l=headings1.yaml
\end{commandshell}
	then you should receive the output given in \cref{lst:headings1-mod1}.

	\begin{minipage}{.45\textwidth}
		\cmhlistingsfromfile[showtabs=true]{demonstrations/headings1-mod1.tex}{\texttt{headings1.tex} using \cref{lst:headings1yaml}}{lst:headings1-mod1}
	\end{minipage}%
	\hfill
	\begin{minipage}{.45\textwidth}
		\cmhlistingsfromfile[showtabs=true]{demonstrations/headings1-mod2.tex}{\texttt{headings1.tex} second modification}{lst:headings1-mod2}
	\end{minipage}

	Now say that you modify the \texttt{YAML} from \cref{lst:headings1yaml} so that
	the \texttt{paragraph} \texttt{level} is \texttt{1}; after
	running
	\begin{commandshell}
latexindent.pl headings1.tex -l=headings1.yaml
\end{commandshell}
	you should receive the code given in \cref{lst:headings1-mod2}; notice that the
	\texttt{paragraph} and \texttt{subsection} are at the same indentation level.

\yamltitle{maximumIndentation}*{horizontal space}
	You can control the maximum indentation given to your file
	by%
	\announce{2017-08-21}{maximumIndentation} specifying the
	\texttt{maximumIndentation} field as horizontal space (but \emph{not} including
	tabs). This feature uses the \texttt{Text::Tabs} module \cite{texttabs}, and
	is \emph{off} by default.

	For example, consider the example shown in \cref{lst:mult-nested} together with the
	default output shown in \cref{lst:mult-nested-default}.

	\begin{cmhtcbraster}[raster column skip=.1\linewidth]
		\cmhlistingsfromfile{demonstrations/mult-nested.tex}{\texttt{mult-nested.tex}}{lst:mult-nested}
		\cmhlistingsfromfile[showtabs=true]{demonstrations/mult-nested-default.tex}{\texttt{mult-nested.tex} default output}{lst:mult-nested-default}
	\end{cmhtcbraster}

	Now say that, for example, you have the \texttt{max-indentation1.yaml} from
	\cref{lst:max-indentation1yaml} and that you run the following command:
	\begin{commandshell}
latexindent.pl mult-nested.tex -l=max-indentation1
\end{commandshell}
	You should receive the output shown in \cref{lst:mult-nested-max-ind1}.

	\begin{cmhtcbraster}
		\cmhlistingsfromfile[style=yaml-LST]*{demonstrations/max-indentation1.yaml}[yaml-TCB]{\texttt{max-indentation1.yaml}}{lst:max-indentation1yaml}
		\cmhlistingsfromfile[showspaces=true]{demonstrations/mult-nested-max-ind1.tex}{\texttt{mult-nested.tex} using \cref{lst:max-indentation1yaml}}{lst:mult-nested-max-ind1}
	\end{cmhtcbraster}

	Comparing the output in \cref{lst:mult-nested-default,lst:mult-nested-max-ind1} we notice that the (default) tabs of
	indentation have been replaced by a single space.

	In general, when using the \texttt{maximumIndentation} feature, any leading tabs will be
	replaced by equivalent spaces except, of course, those found in \texttt{verbatimEnvironments} (see \vref{lst:verbatimEnvironments})
	or \texttt{noIndentBlock} (see \vref{lst:noIndentBlock}).

\subsection{The code blocks known latexindent.pl}\label{subsubsec:code-blocks}
	As of Version 3.0, \texttt{latexindent.pl} processes documents using code blocks; each of
	these are shown in \cref{tab:code-blocks}.

	\begin{table}[!htp]
		\begin{widepage}
			\centering
			\caption{Code blocks known to \texttt{latexindent.pl}}\label{tab:code-blocks}
			\begin{tabular}{m{.3\linewidth}@{\hspace{.25cm}}m{.4\linewidth}@{\hspace{.25cm}}m{.2\linewidth}}
				\toprule
				Code block                    & characters allowed in name                                                                                     & example                                                                                                                                                                                                                                     \\
				\midrule
				environments                  & \lstinline!a-zA-Z@\*0-9_\\!                                                                                        &
				\begin{lstlisting}[,nolol=true,]
\begin{myenv}
body of myenv
\end{myenv}
  \end{lstlisting}
				\\\cmidrule{2-3}
				optionalArguments             & \emph{inherits} name from parent (e.g environment name)                                                        &
				\begin{lstlisting}[,nolol=true,]
[
opt arg text
]
  \end{lstlisting}
				\\\cmidrule{2-3}
				mandatoryArguments            & \emph{inherits} name from parent (e.g environment name)                                                        &
				\begin{lstlisting}[,nolol=true,]
{
mand arg text
}
  \end{lstlisting}
				\\\cmidrule{2-3}
				commands                      & \lstinline!+a-zA-Z@\*0-9_\:!                                                                                        & \lstinline!\mycommand!$\langle$\itshape{arguments}$\rangle$                                                                                                                                                                                \\\cmidrule{2-3}
				keyEqualsValuesBracesBrackets & \lstinline!a-zA-Z@\*0-9_\/.\h\{\}:\#-!                                                                                        & \lstinline!my key/.style=!$\langle$\itshape{arguments}$\rangle$                                                                                                                                                                                \\\cmidrule{2-3}
				namedGroupingBracesBrackets   & \lstinline!0-9\.a-zA-Z@\*><!                                                                                        & \lstinline!in!$\langle$\itshape{arguments}$\rangle$                                                                                                                                                                                \\\cmidrule{2-3}
				UnNamedGroupingBracesBrackets & \centering\emph{No name!}                                                                                      & \lstinline!{! or \lstinline![! or \lstinline!,! or \lstinline!&! or \lstinline!)! or \lstinline!(! or \lstinline!$! followed by $\langle$\itshape{arguments}$\rangle$ \\\cmidrule{2-3}
				ifElseFi                      & \lstinline!@a-zA-Z! but must begin with either \newline \lstinline!\if! of \lstinline!\@if! &
				\begin{lstlisting}[,nolol=true,]
\ifnum...
...
\else
...
\fi
  \end{lstlisting}                                                                                                                                                                                                                                                                                                                                                                      \\\cmidrule{2-3}
				items                         & User specified, see \vref{lst:indentafteritems,lst:itemNames}                                                  &
				\begin{lstlisting}[,nolol=true,]
\begin{enumerate}
  \item ...
\end{enumerate}
  \end{lstlisting}                                                                                                                                                                                                                                                                                                                                                                      \\\cmidrule{2-3}
				specialBeginEnd               & User specified, see \vref{lst:specialBeginEnd}                                                                 &
				\begin{lstlisting}[,nolol=true,]
\[
  ...
\]
  \end{lstlisting}                                                                                                                                                                                                                                                                                                                                                                      \\\cmidrule{2-3}
				afterHeading                  & User specified, see \vref{lst:indentAfterHeadings}                                                             &
				\begin{lstlisting}[,morekeywords={chapter},nolol=true,]
\chapter{title}
  ...
\section{title}
  \end{lstlisting}                                                                                                                                                                                                                                                                                                                                                                      \\\cmidrule{2-3}
				filecontents                  & User specified, see \vref{lst:fileContentsEnvironments}                                                        &
				\begin{lstlisting}[,nolol=true,]
\begin{filecontents}
...
\end{filecontents}
  \end{lstlisting}                                                                                                                                                                                                                                                                                                                                                                      \\
				\bottomrule
			\end{tabular}
		\end{widepage}
	\end{table}

	We will refer to these code blocks in what follows.%
	\announce{2019-07-13}{fine tuning of code blocks} Note that the fine tuning of the definition of the code blocks
	detailed in \cref{tab:code-blocks} is discussed in \vref{sec:finetuning}.