% arara: pdflatex
% arara: bibtex
% arara: pdflatex
% arara: pdflatex
% !arara: indent: {overwrite: yes, trace: yes, localSettings: no, silent: yes}
\begin{filecontents}{mybib.bib}
	@online{cmh:videodemo,
		title="Video demonstration of latexindet.pl on youtube",
		url="http://www.youtube.com/watch?v=s_AMmNVg5WM"}
	@online{cpan,
		title="CPAN: Comprehensive Perl Archive Network",
		url="http://www.cpan.org/"}
	@online{strawberryperl,
		title="Strawberry Perl",
		url="http://strawberryperl.com/"}
	@online{cmhblog,
		title="A Perl script for indenting tex files",
		url="http://tex.blogoverflow.com/2012/08/a-perl-script-for-indenting-tex-files/"}
\end{filecontents}
\documentclass[11pt]{article}
%   This program is free software: you can redistribute it and/or modify
%   it under the terms of the GNU General Public License as published by
%   the Free Software Foundation, either version 3 of the License, or
%   (at your option) any later version.
%   
%   This program is distributed in the hope that it will be useful,
%   but WITHOUT ANY WARRANTY; without even the implied warranty of
%   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
%   GNU General Public License for more details.
%   
%   See <http://www.gnu.org/licenses/>.
\usepackage[left=4.5cm,right=2.5cm,showframe=false,
top=2cm,bottom=1.5cm]{geometry}                      % page setup
\usepackage{parskip}                                 % paragraph skips
\usepackage{booktabs}                                % beautiful tables
\usepackage{listings}                                % nice verbatim environments
\usepackage{titlesec}                                % customize headings
\usepackage{changepage}                              % adjust width of page
\usepackage{fancyhdr}                                % headers & footers
\usepackage[sc,format=hang,font=small]{caption}      % captions
\usepackage[backend=bibtex]{biblatex}                % bibliography
\usepackage{mdframed}                                % framed environments
\usepackage[charter]{mathdesign}                     % changes font
\usepackage[expansion=false,kerning=true]{microtype} % better kerning
\usepackage{enumitem}                                % custom lists
\usepackage{tikz}                                    % so so much
\usetikzlibrary{positioning}
\usepackage{varioref}                                % clever referencing
\usepackage[colorlinks=true,linkcolor=blue,citecolor=black]{hyperref}
\usepackage{cleveref}

\addbibresource{mybib}

\newmdenv[linecolor=red,innertopmargin=.5cm,linewidth=3pt,
	splittopskip=\topskip,skipbelow=0pt,%
]{warning}

\lstset{%
	basicstyle=\small\ttfamily,language={[LaTeX]TeX},   
	numbers=left,
	numberstyle=\ttfamily\small,
	breaklines=true,frame=single,framexleftmargin=8mm, xleftmargin=8mm,
	prebreak = \raisebox{0ex}[0ex][0ex]{\ensuremath{\hookrightarrow}},
	backgroundcolor=\color{green!5},frameround=fttt,
	rulecolor=\color{blue!70!black},
	keywordstyle=\color{blue},                    % keywords
	commentstyle=\color{purple},    % comments
	tabsize=3,
	%columns=fullflexible   
}%
\lstdefinestyle{demo}{numbers=none,xleftmargin=0mm,framexleftmargin=0mm,linewidth=1.25\textwidth}
\newcommand{\verbitem}[1]{\small\ttfamily{#1}}
% stolen from arara.sty http://mirrors.med.harvard.edu/ctan/support/arara/doc/arara.sty
\lstnewenvironment{yaml}[1][]{\lstset{%
	basicstyle=\ttfamily,
	numbers=left,
	xleftmargin=1.5em,
	breaklines=true,
	numberstyle=\ttfamily\small,
	columns=flexible,
	mathescape=false,
	#1,
}}
{}

\newcommand{\fixthis}[1]
{%
	\marginpar{\huge \color{red} \framebox{FIX}}%
	\typeout{FIXTHIS: p\thepage : #1^^J}%
}
% custom section
\titleformat{\section}
{\normalfont\Large\bfseries}
{\llap{\thesection\hskip.5cm}}
{0pt}
{}
% custom subsection
\titleformat{\subsection}
{\normalfont\bfseries}
{\llap{\thesubsection\hskip.5cm}}
{0pt}
{}
% custom subsubsection
\titleformat{\subsubsection}
{\normalfont\bfseries}
{\llap{\thesubsubsection\hskip.5cm}}
{0pt}
{}


\titlespacing\section{0pt}{12pt plus 4pt minus 2pt}{-5pt plus 2pt minus 2pt}
\titlespacing\subsection{0pt}{12pt plus 4pt minus 2pt}{-6pt plus 2pt minus 2pt}
\titlespacing\subsubsection{0pt}{12pt plus 4pt minus 2pt}{-6pt plus 2pt minus 2pt}


% cleveref settings
\crefname{table}{Table}{Tables}
\Crefname{table}{Table}{Tables}
\crefname{figure}{Figure}{Figures}
\Crefname{figure}{Figure}{Figures}
\crefname{section}{Section}{Sections}
\Crefname{section}{Section}{Sections}
\crefname{lstlisting}{Listing}{Listings}
\Crefname{lstlisting}{Listing}{Listings}

\begin{document}

% \begin{noindent}
	\title{\lstinline[basicstyle=\huge\ttfamily]!latexindent.pl!\\[1cm]
		Version 1.11R}
% \end{noindent}
\author{Chris Hughes \footnote{smr01cmh AT users.sourceforge.net}}
\maketitle
\begin{abstract}
	\lstinline!latexindent.pl! is a \lstinline!Perl! script that indents \lstinline!.tex!
	files according to an indentation scheme that the user can modify to suit their 
	taste. Environments, including those with alignment delimiters (such as \lstinline!tabular!), 
	and commands, including those that can split braces and brackets across lines, 
	are \emph{usually} handled correctly by the script. Options for \lstinline!verbatim!-like
	environments and indentation after headings (such as \lstinline!\chapter!, \lstinline!\section!, etc) 
	are also available.
\end{abstract}
			
\tableofcontents
\lstlistoflistings
			
\section{Before we begin}
\subsection{Thanks}
I first created \lstinline!latexindent.pl! to help me format chapter files 
in a big project. After I blogged about it on the 
\TeX{} stack exchange \cite{cmhblog} I received some positive feedback and 
follow-up feature requests. A big thank you to Harish Kumar who has really 
helped to drive the script forward and has put it through a number of challenging
tests-- I look forward to more challenges in the future Harish!
			 	 	 	 	 	
The \lstinline!yaml!-based interface of \lstinline!latexindent.pl! was inspired 
by the wonderful \lstinline!arara! tool; any similarities are deliberate, and 
I hope that it is perceived as the compliment that it is. Thank you to Paulo Cereda and the 
team for releasing this awesome tool; I initially worried that I was going to 
have to make a GUI for \lstinline!latexindent.pl!, but the release of \lstinline!arara! 
has meant there is no need. Thank you to Paulo for all of your advice and 
encouragement.
			 	 	 	 	 	
\subsection{License}
\lstinline!latexindent.pl! is free and open source, and it always will be.
Before you start using it on any important files, bear in mind that \lstinline!latexindent.pl! has the option to overwrite your \lstinline!.tex! files.
It will always make at least one backup (you can choose how many it makes, see \cpageref{page:onlyonebackup})
but you should still be careful when using it. The script has been tested on many
files, but there are some known limitations (see \cref{sec:knownlimitations}). 
You, the user, are responsible for ensuring that you maintain backups of your files
before running \lstinline!latexindent.pl! on them. I think it is important at this
stage to restate an important part of the license here:
\begin{quote}\itshape
	This program is distributed in the hope that it will be useful,
	but WITHOUT ANY WARRANTY; without even the implied warranty of
	MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
	GNU General Public License for more details.
\end{quote}
There is certainly no malicious intent in releasing this script, and I do hope
that it works as you expect it to-- if it does not, please first of all 
make sure that you have the correct settings, and then feel free to let me know with a 
complete minimum working example as I would like to improve the code as much as possible. 
			 	 	 	 	 	
\begin{warning}
	Before you try the script on anything important (like your thesis), test it 
	out on the sample files that come with it in the \lstinline!success! directory. 
\end{warning}
			 	 	 	 	 
			 	 	 	 	 	
\section{Demonstration: before and after}
Let's give a demonstration of some before and after code-- after all, you probably
won't want to try the script if you don't much like the results. You might also 
like to watch the video demonstration I made on youtube \cite{cmh:videodemo}
			     
As you look at \crefrange{lst:filecontentsbefore}{lst:pstricksafter}, remember
that \lstinline!latexindent.pl! is just following its rules-- there is nothing 
particular about these code snippets. All of the rules can be modified 
so that each user can personalize their indentation scheme. 
			
In each of the samples given in \crefrange{lst:filecontentsbefore}{lst:pstricksafter}
the `before' case is a `worst case scenario' with no effort to make indentation. The `after'
result would be the same, regardless of the leading white space at the beginning of 
each line which is stripped by \lstinline!latexindent.pl! (unless a \lstinline!verbatim!-like
environment or \lstinline!noIndentBlock! is specified-- more on this in \cref{sec:defuseloc}).
			
\begin{adjustwidth}{-2cm}{2cm}
	\begin{minipage}{.5\textwidth}
		\begin{lstlisting}[style=demo,caption={\lstinline!filecontents! before},label={lst:filecontentsbefore}]
\begin{filecontents}{mybib.bib}
@online{strawberryperl,
title="Strawberry Perl",
url="http://strawberryperl.com/"}
@online{cmhblog,
title="A Perl script ...
url="...
\end{filecontents}
		\end{lstlisting}
	\end{minipage}%
	\begin{minipage}{.5\textwidth}
		\begin{lstlisting}[style=demo,caption={\lstinline!filecontents! after}]
\begin{filecontents}{mybib.bib}
	@online{strawberryperl,
		title="Strawberry Perl",
		url="http://strawberryperl.com/"}
	@online{cmhblog,
		title="A Perl script for ...
		url="...
\end{filecontents}
		\end{lstlisting}
	\end{minipage}
																					 	 	 	 	 				
	\begin{minipage}{.5\textwidth}
		\begin{lstlisting}[style=demo,caption={\lstinline!tikzset! before}]
\tikzset{
shrink inner sep/.code={
\pgfkeysgetvalue...
\pgfkeysgetvalue...
}
}
		\end{lstlisting}
	\end{minipage}%
	\begin{minipage}{.5\textwidth}
		\begin{lstlisting}[style=demo,caption={\lstinline!tikzset! after}]
\tikzset{
	shrink inner sep/.code={
		\pgfkeysgetvalue...
		\pgfkeysgetvalue...
	}
}
		\end{lstlisting}
	\end{minipage}
	\begin{minipage}{.5\textwidth}
		\begin{lstlisting}[style=demo,caption={\lstinline!pstricks! before}]
\def\Picture#1{%
\def\stripH{#1}%
\begin{pspicture}[showgrid...
\psforeach{\row}{%
{{3,2.8,2.7,3,3.1}},% <=== Only this 
{2.8,1,1.2,2,3},%
...
}{%
\expandafter...
}
\end{pspicture}}
		\end{lstlisting}
	\end{minipage}%
	\begin{minipage}{.5\textwidth}
		\begin{lstlisting}[style=demo,caption={\lstinline!pstricks! after},label={lst:pstricksafter}]
\def\Picture#1{%
	\def\stripH{#1}%
	\begin{pspicture}[showgrid...
		\psforeach{\row}{%
			{{3,2.8,2.7,3,3.1}},% <=== 
			{2.8,1,1.2,2,3},%
            ...
			}{%
			\expandafter...
		}
	\end{pspicture}}
		\end{lstlisting}
	\end{minipage}
\end{adjustwidth}
			     
\section{How to use the script}
There are two ways to use \lstinline!latexindent.pl!: from the command line, 
and using \lstinline!arara!.  We will discuss how to change the settings and behaviour 
of the script in \cref{sec:defuseloc}.
			
\lstinline!latexindent.pl! ships with \lstinline!latexindent.exe! for Windows 
users, so that you can use the script with or without a Perl distribution. 
If you plan to use \lstinline!latexindent.pl! (i.e, the original Perl script) then you will 
need a few standard Perl modules-- see \vref{sec:requiredmodules} for details.
			
In what follows, we will always refer to \lstinline!latexindent.pl!, but depending on 
your operating system and preference, you might substitute \lstinline!latexindent.exe! or
simply \lstinline!latexindent!.
			     
\subsection{From the command line}\label{sec:commandline}
\lstinline!latexindent.pl! has a number of different switches/flags/options, which 
can be combined in any way that you like. \lstinline!latexindent.pl! 
produces a \lstinline!.log! file, \lstinline!indent.log! every time it
is run. There is a base of information that is written to \lstinline!indent.log!,
but other additional information will be written depending 
on which of the following options are used.
			 	 	 	 	 	
\begin{itemize}[labelsep=.5cm]
	\item[] \lstinline!latexindent.pl!
																					
	This will output a welcome message to the terminal, including the version number
	and available options.
	\item[\verbitem{-h}] \lstinline!latexindent.pl -h!
																					
	As above this will output a welcome message to the terminal, including the version number
	and available options.
	\item[] \lstinline!latexindent.pl myfile.tex!
																						 		 		 		 		 					
	This will operate on \lstinline!myfile.tex!, but will simply output to your terminal; \lstinline!myfile.tex! will	not be changed in any way using this command. 
	\item[\verbitem{-w}] \lstinline!latexindent.pl -w myfile.tex!
																						 		 		 		 		 					
	This \emph{will} overwrite \lstinline!myfile.tex!, but it will
	make a copy of \lstinline!myfile.tex! first. You can control the name of 
	the extension (default is \lstinline!.bak!), and how many different backups are made-- 
	more on this in \cref{sec:defuseloc}; see \lstinline!backupExtension! and \lstinline!onlyOneBackUp!.
																						 		 		 		 		 					
	Note that if \lstinline!latexindent.pl! can not create the backup, then it 
	will exit without touching your original file; an error message will be given
	asking you to check the permissions of the backup file.
	\item[\verbitem{-o}] \lstinline!latexindent.pl -o myfile.tex outputfile.tex!
																						 		 		 		 		 					
	This will indent \lstinline!myfile.tex! and output it to \lstinline!outputfile.tex!, 
	overwriting it (\lstinline!outputfile.tex!) if it already exists. Note that if \lstinline!latexindent.pl! is called with both
	the \lstinline!-w! and \lstinline!-o! switches, then \lstinline!-w! will
	be ignored and \lstinline!-o! will take priority (this seems safer than the 
	other way round).
																						 		 		 		 		 					
	Note that using \lstinline!-o! is equivalent to using \lstinline!latexindent.pl myfile.tex > outputfile.tex!
	\item[\verbitem{-s}] \lstinline!latexindent.pl -s myfile.tex!
																						 		 		 		 		 					
	Silent mode: no output will be given to the terminal.
	\item[\verbitem{-t}] \lstinline!latexindent.pl -t myfile.tex!
																						 		 		 		 		 					
	Tracing mode: verbose output will be given to \lstinline!indent.log!. This 
	is useful if \lstinline!latexindent.pl! has made a mistake and you're
	trying to find out where and why. You might also be interested in learning
	about \lstinline!latexindent.pl!'s thought process-- if so, this 
	switch is for you.
	\item[\verbitem{-l}] \lstinline!latexindent.pl -l myfile.tex!
																						 		 		 		 		 					
	\label{page:localswitch}
	Local settings: you might like to read \cref{sec:defuseloc} before 
	using this switch. \lstinline!latexindent.pl! will always load \lstinline!defaultSettings.yaml!
	and if it is called with the \lstinline!-l! switch and it finds \lstinline!localSettings.yaml! 
	in the same directory as \lstinline!myfile.tex! then these settings will be 
	added to the indentation scheme. Information will be given in \lstinline!indent.log! on 
	the success or failure of loading \lstinline!localSettings.yaml!.
	\item[\verbitem{-d}] \lstinline!latexindent.pl -d myfile.tex!
									
	Only \lstinline!defaultSettings.yaml!: you might like to read \cref{sec:defuseloc} before 
	using this switch. By default, \lstinline!latexindent.pl! will always search for 
	\lstinline!indentconfig.yaml! in your home directory. If you would prefer it not to do so
	then (instead of deleting or renaming \lstinline!indentconfig.yaml!) you can simply 
	call the script with the \lstinline!-d! switch; note that this will also tell 
	the script to ignore \lstinline!localSettings.yaml! even if it has been called with the 
	\lstinline!-l! switch.
								
	\item[\verbitem{-c}]\lstinline!latexindent.pl -c=/path/to/directory/ myfile.tex!
								
	If you wish to have backup files and \lstinline!indent.log! written to a directory
	other than the current working directory, then you can send these `cruft' files
	to another directory. 
    % this switch was made as a result of http://tex.stackexchange.com/questions/142652/output-latexindent-auxiliary-files-to-a-different-directory
\end{itemize}
			
\subsection{From \lstinline!arara!}
Using \lstinline!latexindent.pl! from the command line is fine for some folks, but
others may find it easier to use from \lstinline!arara!. \lstinline!latexindent.pl!
ships with an \lstinline!arara! rule, \lstinline!indent.yaml!, which can be copied 
to the directory of
your other \lstinline!arara! rules; otherwise  you can add the directory in which \lstinline!latexindent.pl!
resides to your \lstinline!araraconfig.yaml! file.
			 	 	 	 	 	
Once you have told \lstinline!arara! where to find your \lstinline!indent! rule, 
you can use it any of the ways described in \cref{lst:arara} (or combinations thereof). 
In fact, \lstinline!arara! allows yet greater flexibility-- you can use \lstinline!yes/no!, \lstinline!true/false!, or \lstinline!on/off! to toggle the various options.
			 	 	 	 	 	
\begin{lstlisting}[caption={\lstinline!arara! sample usage},label={lst:arara},escapeinside={(*@}{@*)}]
%(*@@*) arara: indent
%(*@@*) arara: indent: {overwrite: yes}
%(*@@*) arara: indent: {output: myfile.tex}
%(*@@*) arara: indent: {silent: yes}
%(*@@*) arara: indent: {trace: yes}
%(*@@*) arara: indent: {localSettings: yes}
%(*@@*) arara: indent: {onlyDefault: on}
%(*@@*) arara: indent: { cruft: /home/cmhughes/Desktop }
\documentclass{article}
...
\end{lstlisting}
			 	 	 	 	 	
Hopefully the use of these rules is fairly self-explanatory, but for completeness
\cref{tab:orbsandswitches} shows the relationship between \lstinline!arara! directive arguments and the 
switches given in \cref{sec:commandline}.
			 	 	 	 	 	
\begin{table}[!ht]
	\centering
	\caption{\lstinline!arara! directive arguments and corresponding switches}
	\label{tab:orbsandswitches}
	\begin{tabular}{lc}
		\toprule
		\lstinline!arara! directive argument & switch         \\
		\midrule
		\lstinline!overwrite!                & \lstinline!-w! \\
		\lstinline!output!                   & \lstinline!-o! \\
		\lstinline!silent!                   & \lstinline!-s! \\
		\lstinline!trace!                    & \lstinline!-t! \\
		\lstinline!localSettings!            & \lstinline!-l! \\
		\lstinline!onlyDefault!              & \lstinline!-d! \\
		\lstinline!cruft!                    & \lstinline!-c! \\
		\bottomrule
	\end{tabular}
\end{table}
		
The \lstinline!cruft! directive does not work well when used with 
directories that contain spaces.
		
\section{default, user, and local settings}\label{sec:defuseloc}
\lstinline!latexindent.pl! loads its settings from \lstinline!defaultSettings.yaml! 
(rhymes with camel). 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.
			     
\subsection{\lstinline!defaultSettings.yaml!}
If you look in \lstinline!defaultSettings.yaml! you'll find the switches 
that govern the behaviour of \lstinline!latexindent.pl!. If you're not sure where
\lstinline!defaultSettings.yaml! resides on your computer, don't worry as \lstinline!indent.log!
will tell you where to find it.
\lstinline!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.
			 	 	 	 	 	
You can certainly feel free to edit \lstinline!defaultSettings.yaml!, but 
this is not ideal as it may be overwritten when you update your distribution--
all of your hard work tweaking the script would be undone! Don't worry, 
there's a solution-- feel free to peek ahead to \cref{sec:indentconfig} if you like.
\begin{itemize}
	\item[\verbitem{defaultIndent}] \lstinline!"\t"!
																						 		 		 		 		 					
	This is the default indentation (\lstinline!\t! means a tab) used in the absence of other details 
	for the command or environment we are working with-- see \lstinline!indentRules!
	for more details (\cpageref{page:indentRules}).
																						 		 		 		 		 					
	If you're interested in experimenting with \lstinline!latexindent.pl! then you 
	can \emph{remove} all indentation by setting \lstinline!defaultIndent: ""!
	\item[\verbitem{backupExtension}] \lstinline!.bak!
																						 		 		 		 		 					
	If you call \lstinline!latexindent.pl! with the \lstinline!-w! switch (to overwrite
	\lstinline!myfile.tex!) then it will create a backup file before doing 
	any indentation: \lstinline!myfile.bak0! 
																						 		 		 		 		 					
	By default, every time you call \lstinline!latexindent.pl! after this with 
	the \lstinline!-w! switch it will create \lstinline!myfile.bak1!, \lstinline!myfile.bak2!, 
	etc.
	\item[\verbitem{onlyOneBackUp}] \lstinline!0!
																						 		 		 		 		 					
	\label{page:onlyonebackup}
	If you don't want a backup for every time that you call \lstinline!latexindent.pl! (so 
	you don't want \lstinline!myfile.bak1!, \lstinline!myfile.bak2!, etc) and you simply
	want \lstinline!myfile.bak! (or whatever you chose \lstinline!backupExtension! to be)
	then change \lstinline!onlyOneBackUp! to \lstinline!1!.
								
	\item[\verbitem{maxNumberOfBackUps}]\lstinline!0!
								
	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 \lstinline!maxNumberOfBackUps! is $0$ which will \emph{not} 
	prevent back up files being made-- in this case, the behaviour will be dictated 
    entirely by \lstinline!onlyOneBackUp!. 
    %\footnote{This was a feature request made on \href{https://github.com/cmhughes/latexindent.plx}{github}}
								
	\item[\verbitem{indentPreamble}] \lstinline!0!
																						 		 		 		 		 					
	The preamble of a document can sometimes contain some trickier code 
	for \lstinline!latexindent.pl! to work with. By default, \lstinline!latexindent.pl!
	won't try to operate on the preamble, but if you'd like it to try then 
	change \lstinline!indentPreamble! to \lstinline!1!.
	\item[\verbitem{alwaysLookforSplitBraces}] \lstinline!1!
																						 		 		 		 		 					
	This switch tells \lstinline!latexindent.pl! to look for commands that 
	can split \emph{braces} across lines, such as \lstinline!parbox!, \lstinline!tikzset!, etc. In older
	versions of \lstinline!latexindent.pl! you had to specify each one in \lstinline!checkunmatched!-- this 
	clearly became tedious, hence the introduction of \lstinline!alwaysLookforSplitBraces!. 
																						 		 		 		 		 					
	\emph{As long as you leave this switch on (set to 1) you don't need to specify which 
		commands can split braces across lines-- you can ignore the 
		fields \lstinline!checkunmatched! and \lstinline!checkunmatchedELSE! described later}.
	\item[\verbitem{alwaysLookforSplitBrackets}] \lstinline!1!
																						 		 		 		 		 					
	This switch tells \lstinline!latexindent.pl! to look for commands that 
	can split \emph{brackets} across lines, such as \lstinline!psSolid!, \lstinline!pgfplotstabletypeset!, 
	etc. In older versions of \lstinline!latexindent.pl! you had to specify each one in \lstinline!checkunmatchedbracket!-- 
	this clearly became tedious, hence the introduction of \lstinline!alwaysLookforSplitBraces!. 
																						 		 		 		 		 					
	\emph{As long as you leave this switch on (set to 1) you don't need to specify which 
		commands can split brackets across lines-- you can ignore \lstinline!checkunmatchedbracket! described later}.
							
	\item[\verbitem{removeTrailingWhitespace}] \lstinline!0!
	
	By default \lstinline!latexindent.pl! indents every line (including empty lines)
	which creates `trailing whitespace' feared by most version control systems. If
	this option is set to \lstinline!1!, trailing whitespace is removed from all
	lines, also non-empty ones. In general this should not create any problems, but
    by precaution this option is turned off by default. \footnote{Thanks to \href{https://github.com/vosskuhle}{vosskuhle} for 
	providing this feature.}
																 		 		 		 		 					
	\item[\verbitem{lookForAlignDelims}] This is the first example of a field
	in \lstinline!defaultSettings.yaml! that has more than one line; \cref{lst:aligndelims}
	shows more details.
																						 		 		 		 		 					
	\begin{yaml}[caption={\lstinline!lookForAlignDelims!},label={lst:aligndelims}]
lookForAlignDelims:
   tabular: 1
   array: 1
   matrix: 1
   bmatrix: 1
   pmatrix: 1
   align: 1
   align*: 1
   alignat: 1
   alignat*: 1
   aligned: 1
   cases: 1
   dcases: 1
   pmatrix: 1
   listabla: 1
	\end{yaml}
																						 		 		 		 		 					
	The environments specified in this field will be operated on in a special way  by \lstinline!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,lst:tabularafter}. 
																						 		 		 		 		 					
	\begin{minipage}{.5\textwidth}
		\begin{lstlisting}[caption={\lstinline!tabular! before},label={lst:tabularbefore}]
\begin{tabular}{cccc}
1&	2 &3       &4\\
5& &6       &\\
\end{tabular}
		\end{lstlisting}
	\end{minipage}
	\begin{minipage}{.5\textwidth}
		\begin{lstlisting}[caption={\lstinline!tabular! after},label={lst:tabularafter}]
\begin{tabular}{cccc}
 1 & 2 & 3 & 4 \\
 5 &   & 6 &   \\
\end{tabular}
		\end{lstlisting}
	\end{minipage}
																					 		 		 		 		 					
	If you find that \lstinline!latexindent.pl! does not perform satisfactorily on such 
	environments then you can either remove them from \lstinline!lookForAlignDelims! altogether, or set the relevant key to \lstinline!0!, for example \lstinline!tabular: 0!, or if you just want to ignore \emph{specific} 
	instances of the environment, you could wrap them in something from \lstinline!noIndentBlock! (see \cref{lst:noIndentBlock}).
																					 		 		 		 		 					
	\item[\verbitem{verbatimEnvironments}] A field that contains a list of environments
	that you would like left completely alone-- no indentation will be done
	to environments that you have specified in this field-- see \cref{lst:verbatimEnvironments}.
																					 		 		 		 		 					
	\begin{yaml}[caption={\lstinline!verbatimEnvironments!},label={lst:verbatimEnvironments}]
verbatimEnvironments:
    verbatim: 1
    lstlisting: 1
	\end{yaml}
	Note that if  you put an environment in \lstinline!verbatimEnvironments! 
	and in other fields such as \lstinline!lookForAlignDelims! or \lstinline!noAdditionalIndent! 
	then \lstinline!latexindent.pl! will \emph{always} prioritize \lstinline!verbatimEnvironments!.
																					 		 		 		 		 					
	\item[\verbitem{noIndentBlock}] If you have a block of code that you don't 
	want \lstinline!latexindent.pl! to touch (even if it is \emph{not} a verbatim-like
	environment) then you can wrap it in an environment from \lstinline!noIndentBlock!;
	you can use any name you like for this, provided you populate it as demonstrate in 
	\cref{lst:noIndentBlock}.
																					 		 		 		 		 					
	\begin{yaml}[caption={\lstinline!noIndentBlock!},label={lst:noIndentBlock}]
noIndentBlock:
    noindent: 1
    cmhtest: 1
	\end{yaml}
																					 		 		 		 		 					
	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{lstlisting}[caption={\lstinline!noIndentBlock! demonstration},label={lst:noIndentBlockdemo},escapeinside={(*@}{@*)}]
%(*@@*) \begin{noindent} 
        this code
                won't 
     be touched
                    by 
             latexindent.pl!
%(*@@*)\end{noindent} 
	\end{lstlisting}
																					 		 		 		 		 					
	\item[\verbitem{noAdditionalIndent}] If you would prefer some of your
	environments or commands not to receive any additional indent, then 
	populate \lstinline!noAdditionalIndent!; see \cref{lst:noAdditionalIndent}. 
	Note that these environments will still receive the \emph{current} level
	of indentation unless they belong to \lstinline!verbatimEnvironments!, or \lstinline!noIndentBlock!.
																					 		 		 		 		 					
	\begin{yaml}[caption={\lstinline!noAdditionalIndent!},label={lst:noAdditionalIndent}]
noAdditionalIndent:
    document: 1
    myexample: 1
    mydefinition: 1
    problem: 1
    exercises: 1
    mysolution: 1
    foreach: 0
    widepage: 1
    comment: 1
    \[: 1
    \]: 1
    frame: 0
	\end{yaml}
	Note in particular from \cref{lst:noAdditionalIndent} that if you wish content within 
	\lstinline!\[!  and \lstinline!\]! to receive no additional content then 
	you have to specify \emph{both} as \lstinline!1! (the default is \lstinline!0!). 
	If you do not specify both as the same value you may get some interesting results!
	\item[\verbitem{indentRules}] If\label{page:indentRules} you would prefer to specify 
	individual rules for certain environments or commands, just
	populate \lstinline!indentRules!; see \cref{lst:indentRules}
																					 		 		 		 		 					
	\begin{yaml}[caption={\lstinline!indentRules!},label={lst:indentRules}]
indentRules:
   myenvironment: "\t\t"
   anotherenvironment: "\t\t\t\t"
   \[: "\t"
	\end{yaml}      %%%%%\] just here to stop vim from colouring the rest of my code
	Note that in contrast to \lstinline!noAdditionalIndent! you do \emph{not} 
	need to specify both \lstinline!\[! and \lstinline!\]! in this field. 
																					 		 		 		 		 					
	If you put an environment in both \lstinline!noAdditionalIndent! and in 
	\lstinline!indentRules! then \lstinline!latexindent.pl! will resolve the conflict 
	by ignoring \lstinline!indentRules! and prioritizing \lstinline!noAdditionalIndent!.
	You will get a warning message in \lstinline!indent.log!; note that you will only 
	get one warning message per command or environment. Further discussion 
	is given in \cref{sec:fieldhierachy}.
																					 		 		 		 		 			
	\item[\verbitem{indentAfterHeadings}] 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*! etc. This field is slightly different from all 
	of the fields that we have considered previously, because each element is 
	itself a field which has two elements: \lstinline!indent! and \lstinline!level!.
	\begin{yaml}[caption={\lstinline!indentAfterHeadings!},label={lst:indentAfterHeadings}]
indentAfterHeadings:
    part:
       indent: 0
       level: 1
    chapter: 
       indent: 0
       level: 2
    section:
       indent: 0
       level: 3
    ...
	\end{yaml}
	The default settings do \emph{not} place indentation after a heading-- you 
	can easily switch them on by changing \lstinline!indent: 0! to \lstinline!indent: 1!.
	The \lstinline!level! field tells \lstinline!latexindent.pl! the hierarchy of the heading 
	structure in your document. You might, for example, like to have both \lstinline!section!
	and \lstinline!subsection! set with \lstinline!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 \lstinline!level!
	as appropriate.  You can also specify your own indentation in \lstinline!indentRules!-- 
	you will find the default \lstinline!indentRules! contains \lstinline!chapter: " "! which 
	tells \lstinline!latexindent.pl! simply to use a space character after \lstinline!\chapter! headings 
	(once \lstinline!indent! is set to \lstinline!1! for \lstinline!chapter!).
	\begin{warning}
		\emph{The following fields are marked in red, as they are not necessary
			unless you wish to micro-manage your indentation scheme.
			Note that in each case, you should \emph{not} use the backslash.}
	\end{warning}
																					 		 		 		 		 					
	% to anyone reading the source code- I know the next line isn't the
	% correct way to do it :)
	\item[\color{red}\verbitem{checkunmatched}] Assuming you keep \lstinline!alwaysLookforSplitBraces! set to \lstinline!1! (which
	is the default) then you don't need to worry about \lstinline!checkunmatched!. 
																					 		 		 		 		 					
	Should you wish to deactivate \lstinline!alwaysLookforSplitBraces! by setting it to \lstinline!0!, then 
	you can populate \lstinline!checkunmatched! with commands that can split braces across 
	lines-- see \cref{lst:checkunmatched}.
																					 		 		 		 		 					
	\begin{yaml}[caption={\lstinline!checkunmatched!},label={lst:checkunmatched}]
checkunmatched:
    parbox: 1
    vbox: 1
	\end{yaml}
	\item[\color{red}\verbitem{checkunmatchedELSE}] Similarly, assuming you keep \lstinline!alwaysLookforSplitBraces! set to \lstinline!1! (which
	is the default) then you don't need to worry about \lstinline!checkunmatchedELSE!. 
																					 		 		 		 		 					
	As in \lstinline!checkunmatched!, should you wish to deactivate \lstinline!alwaysLookforSplitBraces! by setting it to \lstinline!0!, then 
	you can populate \lstinline!checkunmatchedELSE! with commands that can split braces across 
	lines \emph{and} have an `else' statement-- see \cref{lst:checkunmatchedELSE}.
																					 		 		 		 		 					
	\begin{yaml}[caption={\lstinline!checkunmatchedELSE!},label={lst:checkunmatchedELSE}]
checkunmatchedELSE:
    pgfkeysifdefined: 1
    DTLforeach: 1
    ifthenelse: 1
	\end{yaml}
	\item[\color{red}\verbitem{checkunmatchedbracket}] Assuming you keep \lstinline!alwaysLookforSplitBrackets! 
	set to \lstinline!1! (which is the default) then you don't need to worry about \lstinline!checkunmatchedbracket!. 
																					 		 		 		 		 					
	Should you wish to deactivate \lstinline!alwaysLookforSplitBrackets! by setting it 
	to \lstinline!0!, then you can populate \lstinline!checkunmatchedbracket! with commands that can 
	split \emph{brackets} across lines-- see \cref{lst:checkunmatchedbracket}.
																					 		 		 		 		 					
	\begin{yaml}[caption={\lstinline!checkunmatchedbracket!},label={lst:checkunmatchedbracket}]
checkunmatchedbracket:
    psSolid: 1
    pgfplotstablecreatecol: 1
    pgfplotstablesave: 1
    pgfplotstabletypeset: 1
    mycommand: 1
	\end{yaml}
\end{itemize}
			 	 	 	 	 	
\subsubsection{Hierarchy of fields}\label{sec:fieldhierachy}
After reading the previous section, it should sound reasonable that 
\lstinline!noAdditionalIndent!, \lstinline!indentRules!, and 
\lstinline!verbatim! all serve mutually exclusive tasks. Naturally, you may 
well wonder what happens if you choose to ask \lstinline!latexindent.pl! to 
prioritize one above the other.
			 	 	 	 	 	
For example, let's say that you put the fields in \cref{lst:conflict} into 
one of your settings files.  
\begin{yaml}[caption={Conflicting ideas},label={lst:conflict}]
indentRules:
   myenvironment: "\t\t"
noAdditionalIndent:
   myenvironment: 1
\end{yaml}
			 	 	 	 	 	
Clearly these fields conflict: first of all 
you are telling \lstinline!latexindent.pl! that \lstinline!myenvironment! should 
receive two tabs of indentation, and then you are telling it 
not to put any indentation in the environment. \lstinline!latexindent.pl!
will always make the decision to prioritize \lstinline!noAdditionalIndent! above
\lstinline!indentRules! regardless of the order that you load them in 
your settings file. The first 
time it encounters \lstinline!myenvironment! it will put a warning in \lstinline!indent.log!
and delete the offending key from \lstinline!indentRules! so that any future 
conflicts won't have to be addressed.
			 	 	 	 	 	
Let's consider another conflicting example in \cref{lst:bigconflict}
\begin{yaml}[caption={More conflicting ideas},label={lst:bigconflict}]
lookForAlignDelims:
   myenvironment: 1
verbatimEnvironments:
   myenvironment: 1
\end{yaml}
This is quite a significant conflict-- we are first of all telling \lstinline!latexindent.pl!
to look for alignment delimiters in \lstinline!myenvironment! and then 
telling it that actually we would like \lstinline!myenvironment! to be considered 
as a \lstinline!verbatim!-like environment. Regardless of the order that we 
state \cref{lst:bigconflict} the \lstinline!verbatim! instruction will always win.
As in \cref{lst:conflict} you will only receive a warning in \lstinline!indent.log! the 
first time \lstinline!latexindent.pl! encounters \lstinline!myenvironment! as the 
offending key is deleted from \lstinline!lookForAlignDelims!.
			 	 	 	 	 	
To summarize, \lstinline!latexindent.pl! will prioritize the various fields in the 
following order:
\begin{enumerate}
	\item \lstinline!verbatimEnvironments!
	\item \lstinline!noAdditionalIndent!
	\item \lstinline!indentRules!
\end{enumerate}
\subsection{\lstinline!indentconfig.yaml! (for user settings)}\label{sec:indentconfig}
Editing \lstinline!defaultSettings.yaml! is not ideal as it may be overwritten when 
updating your distribution-- a better way to customize the settings to your liking 
is to set up your own settings file, 
\lstinline!mysettings.yaml! (or any name you like, provided it ends with \lstinline!.yaml!). 
The only thing you have to do is tell \lstinline!latexindent.pl! where to find it. 
			 	 	 	 	 	
\lstinline!latexindent.pl! will always check your home directory for \lstinline!indentconfig.yaml! (unless 
it is called with the \lstinline!-d! switch), 
which is a plain text file you can create that contains the \emph{absolute}
paths for any settings files that you wish \lstinline!latexindent.pl! to load.
Note that Mac and Linux users home directory is \lstinline!~/username! while
Windows (Vista onwards) is \lstinline!C:\Users\username! \footnote{If you're not sure 
	where to put \lstinline!indentconfig.yaml!, don't 
	worry \lstinline!latexindent.pl! will tell you in the log file exactly where to 
put it assuming it doesn't exist already.}
\Cref{lst:indentconfig} shows a sample \lstinline!indentconfig.yaml! file.
			 	 	 	 	 	
\begin{yaml}[caption={\lstinline!indentconfig.yaml! (sample)},label={lst:indentconfig}]
# Paths to user settings for latexindent.pl
#
# Note that the settings will be read in the order you 
# specify here- each successive settings file will overwrite
# the variables that you specify

paths:
- /home/cmhughes/Documents/yamlfiles/mysettings.yaml
- /home/cmhughes/folder/othersettings.yaml
- /some/other/folder/anynameyouwant.yaml
- C:\Users\chughes\Documents\mysettings.yaml
- C:\Users\chughes\Desktop\test spaces\more spaces.yaml
\end{yaml}
			 	 	 	 	 	
Note that the \lstinline!.yaml! files you specify in \lstinline!indentconfig.yaml!
will be loaded in the order that you write them in. Each file doesn't have 
to have every switch from \lstinline!defaultSettings.yaml!; in fact, I recommend 
that you only keep the switches that you want to \emph{change} in these 
settings files.
			 	 	 	 	 	
To get started with your own settings file, you might like to save a copy of 
\lstinline!defaultSettings.yaml! in another directory and call it, for 
example, \lstinline!mysettings.yaml!. Once you have added the path to \lstinline!indentconfig.yaml!
feel free to start changing the switches and adding more environments to it 
as you see fit-- have a look at \cref{lst:mysettings} for an example 
that uses four tabs for the default indent, and adds the \lstinline!tabbing!
environment to the list of environments that contains alignment delimiters.
			 	 	 	 	 	
\begin{yaml}[caption={\lstinline!mysettings.yaml! (example)},label={lst:mysettings}]
# Default value of indentation
defaultIndent: "\t\t\t\t"

# environments that have tab delimiters, add more 
# as needed
lookForAlignDelims:
   tabbing: 1
\end{yaml}
			 	 	 	 	 	
You can make sure that your settings are loaded by checking \lstinline!indent.log!
for details-- if you have specified a path that \lstinline!latexindent.pl! doesn't 
recognize then you'll get a warning, otherwise you'll get confirmation that 
\lstinline!latexindent.pl! has read your settings file \footnote{Windows users 
	may find that they have to end \lstinline!.yaml! files with a blank line}.
			 	 	 	 	 	
\begin{warning}
	When editing \lstinline!.yaml! files it is \emph{extremely} important 
	to remember how sensitive they are to spaces. I highly recommend copying 
	and pasting from \lstinline!defaultSettings.yaml! when you create your
	first \lstinline!whatevernameyoulike.yaml! file.
																					
	If \lstinline!latexindent.pl! can not read your \lstinline!.yaml! file it 
	will tell you so in \lstinline!indent.log!.
\end{warning}
			 	 	 	 	 	
\subsection{\lstinline!localSettings.yaml!}
You may remember on \cpageref{page:localswitch} we discussed the \lstinline!-l! switch
that tells \lstinline!latexindent.pl! to look for \lstinline!localSettings.yaml! in the 
\emph{same directory} as \lstinline!myfile.tex!. This settings file will 
be read \emph{after} \lstinline!defaultSettings.yaml! and, assuming they exist, 
user settings. 
			 	 	 	 	 	
In contrast to the \emph{user} settings which can be named anything you like (provided that
they are detailed in \lstinline!indentconfig.yaml!), the \emph{local} settings file
must be called \lstinline!localSettings.yaml!. It can contain any switches that you'd
like to change-- a sample is shown in \cref{lst:localSettings}.
			 	 	 	 	 	
\begin{yaml}[caption={\lstinline!localSettings.yaml! (example)},label={lst:localSettings}]
# Default value of indentation
defaultIndent: " "

# environments that have tab delimiters, add more 
# as needed
lookForAlignDelims:
   tabbing: 0

#  verbatim environments- environments specified 
#  in this hash table will not be changed at all!
verbatimEnvironments:
    cmhenvironment: 0
\end{yaml}
			 	 	 	 	 	
You can make sure that your local settings are loaded by checking \lstinline!indent.log!
for details-- if \lstinline!localSettings.yaml! can not be read then you will
get a warning, otherwise you'll get confirmation that 
\lstinline!latexindent.pl! has read \lstinline!localSettings.yaml!.
			 	 	 	 	 	
\subsection{Settings load order}\label{sec:loadorder}
\lstinline!latexindent.pl! loads the settings files in the following order:
\begin{enumerate}
	\item \lstinline!defaultSettings.yaml! (always loaded, can not be renamed)
	\item \lstinline!anyUserSettings.yaml! (and any other arbitrarily-named files specified in \lstinline!indentconfig.yaml!)
	\item \lstinline!localSettings.yaml! (if found in same directory as \lstinline!myfile.tex! and called
	with \lstinline!-l! switch; can not be renamed)
\end{enumerate}
A visual representation of this is given in \cref{fig:loadorder}.
			
\begin{figure}
	\centering
	\begin{tikzpicture}[
			needed/.style={very thick, draw=blue,fill=blue!20,
				text centered, minimum height=2.5em,rounded corners=1ex},
			optional/.style={draw=black, very thick,scale=0.8,
				text centered, minimum height=2.5em,rounded corners=1ex},
			optionalfill/.style={fill=black!10},
			connections/.style={draw=black!30,dotted,line width=3pt,text=red},
		]
		% Draw diagram elements
		\node (latexindent) [needed,circle]  {\lstinline!latexindent.pl!};
		\node (default) [needed,above right=.5cm of latexindent]  {\lstinline!defaultSettings.yaml!};
		\node (indentconfig) [optional,right=of latexindent]  {\lstinline!indentconfig.yaml!};
		\node (any) [optional,optionalfill,above right=of indentconfig]  {\lstinline!any.yaml!};
		\node (name) [optional,optionalfill,right=of indentconfig]  {\lstinline!name.yaml!};
		\node (you) [optional,optionalfill,below right=of indentconfig]  {\lstinline!you.yaml!};
		\node (want) [optional,optionalfill,below=of indentconfig]  {\lstinline!want.yaml!};
		\node (local) [optional,below=of latexindent]  {\lstinline!localSettings.yaml!};
		% Draw arrows between elements
		\draw[connections,solid] (latexindent) to[in=-90]node[pos=0.5,anchor=north]{1} (default.south) ;
		\draw[connections,optional] (latexindent) -- node[pos=0.5,anchor=north]{2} (indentconfig) ;
		\draw[connections,optional] (indentconfig) to[in=-90] (any.south) ;
		\draw[connections,optional] (indentconfig) -- (name) ;
		\draw[connections,optional] (indentconfig) to[out=-45,in=90] (you) ;
		\draw[connections,optional] (indentconfig) -- (want) ;
		\draw[connections,optional] (latexindent) -- node[pos=0.5,anchor=west]{3} (local) ;
	\end{tikzpicture}
	\caption{Schematic of the load order described in \cref{sec:loadorder}; solid lines represent 
		mandatory files, dotted lines represent optional files. \lstinline!indentconfig.yaml! can 
		contain as many files as you like-- the files will be loaded in order; if you specify 
	settings for the same field in more than one file, the most recent takes priority. }
	\label{fig:loadorder}
\end{figure}
			
\subsection{An important example}
I was working on a document that had the text shown in \cref{lst:casestudy}. 
\begin{lstlisting}[caption={When to set \lstinline!alwaysLookforSplitBrackets=0!},label={lst:casestudy},escapeinside={(*@}{@*)}]
Hence determine how many zeros the function $h(x)=f(x)-g(x)$
has on the interval $[0,9)$.(*@\label{line:interval1}@*)
\begin{shortsolution}
	The function $h$ has $10$ zeros on the interval $[0,9)$.(*@\label{line:interval2}@*)
\end{shortsolution}
\end{lstlisting}
I had allowed \lstinline!alwaysLookforSplitBrackets=1!, which is the default setting. 
Unfortunately, this caused undesired results, as \lstinline!latexindent.pl! thought that the opening 
\lstinline![!  in the interval notation (\cref{line:interval1,line:interval2}) 
was an opening brace that needed to be closed (with a corresponding \lstinline!]!). Clearly 
this was inappropriate, but also expected since \lstinline!latexindent.pl! was simply
following its matching rules.
			
In this particular instance, I set up \lstinline!localSettings.yaml! 
to contain \lstinline!alwaysLookforSplitBrackets: 0! and then specified the commands 
that could split brackets across lines (such as \lstinline!begin{axis}!) individually
in \lstinline!checkunmatchedbracket!.  Another option would have been to wrap the 
the line in an environment from \lstinline!noIndentBlock! which treats its contents
as a verbatim environment.
			
			 	 	 	 	 	
\section{Known limitations}\label{sec:knownlimitations}
There are a number of known limitations of the script, and almost certainly quite a
few that are \emph{unknown}!
			      
The main limitation is to do with the alignment routine of environments that contain 
delimiters-- in other words, environments that are entered in \lstinline!lookForAlignDelims!.
Indeed, this is the only part of the script that can \emph{potentially} remove 
lines from \lstinline!myfile.tex!. Note that \lstinline!indent.log! will always
finish with a comparison of line counts before and after. 
			      
The routine works well for `standard' blocks of code that have the same number of \lstinline!&!
per line, but it will not do anything for blocks that do not-- such examples 
include \lstinline!tabular! environments that use \lstinline!\multicolumn! or 
perhaps spread cell contents across multiple lines.  For each alignment block (\lstinline!tabular!, 
\lstinline!align!, etc) \lstinline!latexindent.pl! first of all makes a record 
of the maximum number of \lstinline!&!; if each row does not have that 
number of \lstinline!&! then it will not try to format that row. Details 
will be given in \lstinline!indent.log! assuming that \lstinline!trace! mode
is active.
			
If you have a \lstinline!verbatim!-like environment inside a \lstinline!tabular!-like
environment, the \lstinline!verbatim! environment \emph{will} be formatted, which 
is probably not what you want. I hope to address this in future versions, but for the 
moment wrap it in a \lstinline!noIndentBlock! (see \cpageref{lst:noIndentBlockdemo}).
			      
I hope that this script is useful to some-- if you find an example where the 
script does not behave as you think it should, feel free to e-mail me or else
come and find me on the \url{http://tex.stackexchange.com} site; I'm often around 
and in the chat room.
			      
\printbibliography[heading=bibintoc]
			
\appendix
\section{Required \lstinline!Perl! modules}\label{sec:requiredmodules}
If you intend to use \lstinline!latexindent.pl! and \emph{not} one of the supplied standalone executable files, then you will need a few standard Perl modules-- if you can run the 
minimum code in \cref{lst:helloworld} (\lstinline!perl helloworld.pl!) then you will be able to run \lstinline!latexindent.pl!, otherwise you may 
need to install the missing modules.
			 	 	 	 	 	
\begin{lstlisting}[language=Perl,caption={\lstinline!helloworld.pl!},label={lst:helloworld}]
#!/usr/bin/perl

use strict;
use warnings;           
use FindBin;            
use YAML::Tiny;         
use File::Copy;         
use File::Basename;     
use Getopt::Std;        
use File::HomeDir;      

print "hello world";
exit;
\end{lstlisting}
My default installation on Ubuntu 12.04 did \emph{not} come
with all of these modules as standard, but Strawberry Perl for Windows \cite{strawberryperl}
did.
				
Installing the modules given in \cref{lst:helloworld} will vary depending on your 
operating system and \lstinline!Perl! distribution. For example, Ubuntu users 
might visit the software center, and Strawberry Perl users on Windows might use 
\lstinline!CPAN client!. All of the modules are readily available on CPAN \cite{cpan}.
			
\section{The \lstinline!arara! rule}
The \lstinline!arara! rule (\lstinline!indent.yaml!) contains lines such as those
given in \cref{lst:arararule}. With this setup, the user \emph{always} has 
to specify whether or not they want (in this example) to use the \lstinline!trace!
identifier.
\begin{yaml}[caption={The \lstinline!arara! rule},label={lst:arararule},numbers=none]
...
arguments:
- identifier: trace
  flag: <arara> @{ isTrue( parameters.trace, "-t" ) }
...
\end{yaml}
			
If you would like to have the \lstinline!trace! option on by default every time you 
call \lstinline!latexindent.pl! from \lstinline!arara! (without having to write \lstinline!% arara: indent: {trace: yes}!), then simply
amend \cref{lst:arararule} so that it looks like \cref{lst:arararulemod}.
\begin{yaml}[caption={The \lstinline!arara! rule (modified)},label={lst:arararulemod},numbers=none]
...
arguments:
- identifier: trace
  flag: <arara> @{ isTrue( parameters.trace, "-t" ) }
  default: "-t"
...
\end{yaml}
			
With this modification in place, you now simply to write \lstinline!% arara: indent! and 
\lstinline!trace! mode will be activated by default. If you wish to turn off \lstinline!trace!
mode then you can write \lstinline!% arara: indent: {trace: off}!.
			
Of course, you can apply these types of modifications to \emph{any} of the identifiers, 
but proceed with caution if you intend to do this for \lstinline!overwrite!.
			
\end{document}
