% arara: pdflatex: {shell: yes, files: [latexindent]}
\appendix
	\section{Required \texttt{Perl} modules}\label{sec:requiredmodules}
	 If you intend to use \texttt{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} (\texttt{perl helloworld.pl}) then you will be able to run \texttt{latexindent.pl}, otherwise you may
	 need to install the missing modules.

	 \begin{cmhlistings}[language=Perl]{\texttt{helloworld.pl}}{lst:helloworld}
#!/usr/bin/perl

use strict;
use warnings;
use utf8;
use PerlIO::encoding;
use Unicode::GCString;
use open ':std', ':encoding(UTF-8)';
use FindBin;
use YAML::Tiny;
use File::Copy;
use File::Basename;
use File::HomeDir;
use Getopt::Long;
use Data::Dumper;

print "hello world";
exit;
\end{cmhlistings}
	 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 \texttt{Perl} distribution. For example, Ubuntu users
	 might visit the software center, or else run
	 \begin{commandshell}
sudo perl -MCPAN -e 'install "File::HomeDir"'
 \end{commandshell}

	 Linux users may be interested in exploring Perlbrew \cite{perlbrew}; possible installation and setup
	 options follow for Ubuntu (other distributions will need slightly different commands).
	 \begin{commandshell}
sudo apt-get install perlbrew
perlbrew install perl-5.20.1
perlbrew switch perl-5.20.1
sudo apt-get install curl
curl -L http://cpanmin.us | perl - App::cpanminus
cpanm YAML::Tiny
cpanm File::HomeDir
\end{commandshell}

	 Strawberry Perl users on Windows might use
	 \texttt{CPAN client}. All of the modules are readily available on CPAN \cite{cpan}.

	 \texttt{indent.log} will contain details of the location
	 of the Perl modules on your system.  \texttt{latexindent.exe} is a standalone
	 executable for Windows (and therefore does not require a Perl distribution) and caches copies of the Perl modules onto your system; if you
	 wish to see where they are cached, use the  \texttt{trace} option, e.g
	 \begin{dosprompt}
latexindent.exe -t myfile.tex
 \end{dosprompt}

	\section{Updating the \texttt{path} variable}\label{sec:updating-path}
	 \texttt{latexindent.pl} has a few scripts (available at \cite{latexindent-home}) that can update the \texttt{path} variables\footnote{Thanks to \cite{jasjuang} for this feature!}. If you're
	 on a Linux or Mac machine, then you'll want \texttt{CMakeLists.txt} from \cite{latexindent-home}.
	\subsection{Add to path for Linux}
		To add \texttt{latexindent.pl} to the path for Linux, follow these steps:
		\begin{enumerate}
			\item download  \texttt{latexindent.pl} and its associated modules, \texttt{defaultSettings.yaml},
			      to your chosen directory from \cite{latexindent-home} ;
			\item within your directory, create a directory called \texttt{path-helper-files} and
			      download \texttt{CMakeLists.txt} and \lstinline!cmake_uninstall.cmake.in!
			      from \cite{latexindent-home}/path-helper-files to this directory;
			\item run
			      \begin{commandshell}
ls /usr/local/bin
          \end{commandshell}
			      to see what is \emph{currently} in there;
			\item run the following commands
			      \begin{commandshell}
sudo apt-get install cmake
sudo apt-get update && sudo apt-get install build-essential
mkdir build && cd build
cmake ../path-helper-files
sudo make install
\end{commandshell}
			\item run
			      \begin{commandshell}
ls /usr/local/bin
          \end{commandshell}
			      again to check that \texttt{latexindent.pl}, its modules and \texttt{defaultSettings.yaml} have been added.
		\end{enumerate}
		To \emph{remove} the files, run
		\begin{commandshell}
sudo make uninstall}.
    \end{commandshell}
	\subsection{Add to path for Windows}
		To add \texttt{latexindent.exe} to the path for Windows, follow these steps:
		\begin{enumerate}
			\item download  \texttt{latexindent.exe}, \texttt{defaultSettings.yaml},  \texttt{add-to-path.bat}
			      from \cite{latexindent-home} to your chosen directory;
			\item open a command prompt and run the following command to see what is \emph{currently} in your \lstinline!%path%! variable;
			      \begin{dosprompt}
echo %path%
          \end{dosprompt}
			\item right click on \texttt{add-to-path.bat} and \emph{Run as administrator};
			\item log out, and log back in;
			\item open a command prompt and run
			      \begin{dosprompt}
echo %path%
          \end{dosprompt}
			      to check that the appropriate directory has been added to your \lstinline!%path%!.
		\end{enumerate}
		To \emph{remove} the directory from your \lstinline!%path%!, run \texttt{remove-from-path.bat} as administrator.

	\section{Differences from Version 2.2 to 3.0}\label{app:differences}
	 There are a few (small) changes to the interface when comparing Version 2.2 to Version 3.0.
	 Explicitly, in previous versions you might have run, for example,
	 \begin{commandshell}
latexindent.pl -o myfile.tex outputfile.tex
 \end{commandshell}
	 whereas in Version 3.0 you would run any of the following, for example,
	 \begin{commandshell}
latexindent.pl -o=outputfile.tex myfile.tex
latexindent.pl -o outputfile.tex myfile.tex
latexindent.pl myfile.tex -o outputfile.tex 
latexindent.pl myfile.tex -o=outputfile.tex 
latexindent.pl myfile.tex -outputfile=outputfile.tex 
latexindent.pl myfile.tex -outputfile outputfile.tex 
 \end{commandshell}
	 noting that the \emph{output} file is given \emph{next to} the \texttt{-o} switch.

	 The fields given in \cref{lst:obsoleteYaml} are \emph{obsolete} from Version 3.0
	 onwards.
	 \begin{yaml}[style=yaml-LST,numbers=none]{Obsolete YAML fields from Version 3.0}[colframe=white!25!red,colbacktitle=white!75!red,colback=white!90!red,]{lst:obsoleteYaml}
alwaysLookforSplitBrackets
alwaysLookforSplitBrackets
checkunmatched
checkunmatchedELSE
checkunmatchedbracket
constructIfElseFi
\end{yaml}

	 There is a slight difference when specifying indentation after headings; specifically,
	 we now write \texttt{indentAfterThisHeading} instead of \texttt{indent}. See \cref{lst:indentAfterThisHeadingOld,lst:indentAfterThisHeadingNew}

	 \begin{minipage}{.45\textwidth}
		 \begin{yaml}[style=yaml-LST,numbers=none]{\texttt{indentAfterThisHeading} in Version 2.2}{lst:indentAfterThisHeadingOld}
indentAfterHeadings:
    part:
       indent: 0
       level: 1
\end{yaml}
	 \end{minipage}%
	 \hfill
	 \begin{minipage}{.45\textwidth}
		 \begin{yaml}[style=yaml-LST,numbers=none]{\texttt{indentAfterThisHeading} in Version 3.0}{lst:indentAfterThisHeadingNew}
indentAfterHeadings:
    part:
       indentAfterThisHeading: 0
       level: 1
\end{yaml}
	 \end{minipage}%

	 To specify \texttt{noAdditionalIndent} for display-math environments in Version 2.2, you would write YAML
	 as in \cref{lst:noAdditionalIndentOld}; as of Version 3.0, you would write YAML as in \cref{lst:indentAfterThisHeadingNew1}
	 or, if you're using \texttt{-m} switch, \cref{lst:indentAfterThisHeadingNew2}.

	 \begin{minipage}{.45\textwidth}
		 \begin{yaml}[style=yaml-LST,numbers=none]{\texttt{noAdditionalIndent} in Version 2.2}{lst:noAdditionalIndentOld}
noAdditionalIndent:
    \[: 0
    \]: 0
\end{yaml}
	 \end{minipage}%
	 \hfill
	 \begin{minipage}{.45\textwidth}
		 \begin{yaml}[style=yaml-LST,numbers=none]{\texttt{noAdditionalIndent} for \texttt{displayMath} in Version 3.0}{lst:indentAfterThisHeadingNew1}
specialBeginEnd:
    displayMath:
        begin: '\\\['
        end: '\\\]'
        lookForThis: 0
\end{yaml}

		 \begin{yaml}[style=yaml-LST,numbers=none]{\texttt{noAdditionalIndent} for \texttt{displayMath}  in Version 3.0}{lst:indentAfterThisHeadingNew2}
noAdditionalIndent:
    displayMath: 1
\end{yaml}
	 \end{minipage}%

	 \mbox{}\hfill     \begin{minipage}{.25\textwidth}
		 \hrule

		 \hfill\itshape End

	 \end{minipage}
