% arara: pdflatex: {shell: yes, files: [latexindent]}
\section{How to use the script}
 \texttt{latexindent.pl} ships as part of the \TeX Live distribution for
 Linux and Mac users; \texttt{latexindent.exe} ships as part of the \TeX Live
 and MiK\TeX{} distributions for Windows users. These files are also available
 from github \cite{latexindent-home} should you wish to use them without
 a \TeX{} distribution; in this case, you may like to read \vref{sec:updating-path}
 which details how the \texttt{path} variable can be updated.

 In what follows, we will always refer to \texttt{latexindent.pl}, but depending on
 your operating system and preference, you might substitute \texttt{latexindent.exe} or
 simply \texttt{latexindent}.

 There are two ways to use \texttt{latexindent.pl}: from the command line,
 and using \texttt{arara}; we discuss these in \cref{sec:commandline} and
 \cref{sec:arara} respectively. We will discuss how to change the settings and
 behaviour of the script in \vref{sec:defuseloc}.

 \texttt{latexindent.pl} ships with \texttt{latexindent.exe} for Windows
 users, so that you can use the script with or without a Perl distribution.
 If you plan to use \texttt{latexindent.pl} (i.e, the original Perl script) then you will
 need a few standard Perl modules -- see \vref{sec:requiredmodules} for details.

\subsection{From the command line}\label{sec:commandline}
	\texttt{latexindent.pl} has a number of different switches/flags/options, which
	can be combined in any way that you like, either in short or long form as detailed below.
	\texttt{latexindent.pl}  produces a \texttt{.log} file, \texttt{indent.log}, every time it
	is run; the name of the log file can be customised, but we will
	refer to the log file as \texttt{indent.log} throughout this document.
	There is a base of information that is written to \texttt{indent.log},
	but other additional information will be written depending
	on which of the following options are used.

	\begin{commandshell}
latexindent.pl
      \end{commandshell}

	This will output a welcome message to the terminal, including the version number
	and available options.

\flagbox{-h, --help}

	\begin{commandshell}
latexindent.pl -h
      \end{commandshell}

	As above this will output a welcome message to the terminal, including the version number
	and available options.
	\begin{commandshell}
latexindent.pl myfile.tex
      \end{commandshell}

	This will operate on \texttt{myfile.tex}, but will simply output to your terminal; \texttt{myfile.tex} will	not be changed
	by \texttt{latexindent.pl} in any way using this command.

\flagbox{-w, --overwrite}
	\begin{commandshell}
latexindent.pl -w myfile.tex
latexindent.pl --overwrite myfile.tex
latexindent.pl myfile.tex --overwrite 
      \end{commandshell}

	This \emph{will} overwrite \texttt{myfile.tex}, but it will
	make a copy of \texttt{myfile.tex} first. You can control the name of
	the extension (default is \texttt{.bak}), and how many different backups are made --
	more on this in \cref{sec:defuseloc}, and in particular see \texttt{backupExtension} and \texttt{onlyOneBackUp}.

	Note that if \texttt{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.

\flagbox{-o=output.tex,--outputfile=output.tex}
	\begin{commandshell} 
latexindent.pl -o=output.tex myfile.tex
latexindent.pl myfile.tex -o=output.tex 
latexindent.pl --outputfile=output.tex myfile.tex
latexindent.pl --outputfile output.tex myfile.tex
      \end{commandshell}

	This will indent \texttt{myfile.tex} and output it to \texttt{output.tex},
	overwriting it (\texttt{output.tex}) if it already exists\footnote{Users of version 2.* should
		note the subtle change in syntax}. Note that if \texttt{latexindent.pl} is called with both
	the \texttt{-w} and \texttt{-o} switches, then \texttt{-w} will
	be ignored and \texttt{-o} will take priority (this seems safer than the
	other way round).

	Note that using \texttt{-o} is equivalent to using
	\begin{commandshell}
latexindent.pl myfile.tex > output.tex
\end{commandshell}
	See \vref{app:differences} for details of how the interface has changed
	from Version 2.2 to Version 3.0 for this flag.
\flagbox{-s, --silent}
	\begin{commandshell}
latexindent.pl -s myfile.tex
latexindent.pl myfile.tex -s
      \end{commandshell}

	Silent mode: no output will be given to the terminal.

\flagbox{-t, --trace}
	\begin{commandshell}
latexindent.pl -t myfile.tex
latexindent.pl myfile.tex -t
      \end{commandshell}

	\label{page:traceswitch}
	Tracing mode: verbose output will be given to \texttt{indent.log}. This
	is useful if \texttt{latexindent.pl} has made a mistake and you're
	trying to find out where and why. You might also be interested in learning
	about \texttt{latexindent.pl}'s thought process -- if so, this
	switch is for you, although it should be noted that, especially for large files, this does affect
	performance of the script.

\flagbox{-tt, --ttrace}
	\begin{commandshell}
latexindent.pl -tt myfile.tex
latexindent.pl myfile.tex -tt
      \end{commandshell}

	\emph{More detailed} tracing mode: this option gives more details to \texttt{indent.log}
	than the standard \texttt{trace} option (note that, even more so than with \texttt{-t},
	especially for large files, performance of the script will be affected).

\flagbox{-l, --local[=myyaml.yaml,other.yaml,...]}
	\begin{commandshell}
latexindent.pl -l myfile.tex
latexindent.pl -l=myyaml.yaml myfile.tex
latexindent.pl -l myyaml.yaml myfile.tex
latexindent.pl -l first.yaml,second.yaml,third.yaml myfile.tex
latexindent.pl -l=first.yaml,second.yaml,third.yaml myfile.tex
latexindent.pl myfile.tex -l=first.yaml,second.yaml,third.yaml 
      \end{commandshell}

	\label{page:localswitch}
	\texttt{latexindent.pl} will always load \texttt{defaultSettings.yaml} (rhymes with camel)
	and if it is called with the \texttt{-l} switch and it finds \texttt{localSettings.yaml}
	in the same directory as \texttt{myfile.tex} then these settings will be
	added to the indentation scheme. Information will be given in \texttt{indent.log} on
	the success or failure of loading \texttt{localSettings.yaml}.

	The \texttt{-l} flag can take an \emph{optional} parameter which details the name (or names separated by commas) of a YAML file(s)
	that resides in the same directory as \texttt{myfile.tex}; you can use this option if you would
	like to load a settings file in the current working directory that is \emph{not} called \texttt{localSettings.yaml}.
	In fact, you can specify \emph{relative} path names to the current directory, but \emph{not}
	absolute paths -- for absolute paths, see \vref{sec:indentconfig}.
	Explicit demonstrations of how to use the \texttt{-l} switch are given throughout this documentation.

\flagbox{-d, --onlydefault}
	\begin{commandshell}
latexindent.pl -d myfile.tex
      \end{commandshell}

	Only \texttt{defaultSettings.yaml}: you might like to read \cref{sec:defuseloc} before
	using this switch. By default, \texttt{latexindent.pl} will always search for
	\texttt{indentconfig.yaml} or \texttt{.indentconfig.yaml}  in your home directory. If you would prefer it not to do so
	then (instead of deleting or renaming \texttt{indentconfig.yaml}/\texttt{.indentconfig.yaml}) you can simply
	call the script with the \texttt{-d} switch; note that this will also tell
	the script to ignore \texttt{localSettings.yaml} even if it has been called with the
	\texttt{-l} switch.

\flagbox{-c, --cruft=<directory>}
	\begin{commandshell}
latexindent.pl -c=/path/to/directory/ myfile.tex
      \end{commandshell}

	If you wish to have backup files and \texttt{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

\flagbox{-g, --logfile}
	\begin{commandshell}
latexindent.pl -g=other.log myfile.tex
latexindent.pl -g other.log myfile.tex
latexindent.pl --logfile other.log myfile.tex
latexindent.pl myfile.tex -g other.log 
      \end{commandshell}

	By default, \texttt{latexindent.pl} reports information to \texttt{indent.log}, but if you wish to change the
	name of this file, simply call the script with your chosen name after the \texttt{-g} switch as demonstrated above.

\flagbox{-m, --modifylinebreaks}
	\begin{commandshell}
latexindent.pl -m myfile.tex
latexindent.pl -modifylinebreaks myfile.tex
      \end{commandshell}

	One of the most exciting developments in Version~3.0 is the ability to modify line breaks; for full details
	see \vref{sec:modifylinebreaks}

	\texttt{latexindent.pl} can also be called on a file without the file extension, for
	example
	\begin{commandshell}
latexindent.pl myfile
    \end{commandshell}
	and in which case, you can specify
	the order in which extensions are searched for; see \vref{lst:fileExtensionPreference}
	for full details.

\subsection{From \texttt{arara}}\label{sec:arara}
	Using \texttt{latexindent.pl} from the command line is fine for some folks, but
	others may find it easier to use from \texttt{arara}. \texttt{arara} ships with
	a rule, \texttt{indent.yaml}, but in case you do not have this rule, you can find it at \cite{paulo}.

	You can use the rule in any of the ways described in \cref{lst:arara} (or combinations thereof).
	In fact, \texttt{arara} allows yet greater flexibility -- you can use \texttt{yes/no}, \texttt{true/false}, or \texttt{on/off} to toggle the various options.
	\begin{cmhlistings}[style=demo,escapeinside={(*@}{@*)}]{\texttt{arara} sample usage}{lst:arara}
%(*@@*) 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{cmhlistings}
	%(*@@*) arara: indent: { modifylinebreaks: yes }

	Hopefully the use of these rules is fairly self-explanatory, but for completeness
	\cref{tab:orbsandswitches} shows the relationship between \texttt{arara} directive arguments and the
	switches given in \cref{sec:commandline}.

	\begin{table}[!ht]
		\centering
		\caption{\texttt{arara} directive arguments and corresponding switches}
		\label{tab:orbsandswitches}
		\begin{tabular}{lc}
			\toprule
			\texttt{arara} directive argument & switch      \\
			\midrule
			\texttt{overwrite}                & \texttt{-w} \\
			\texttt{output}                   & \texttt{-o} \\
			\texttt{silent}                   & \texttt{-s} \\
			\texttt{trace}                    & \texttt{-t} \\
			\texttt{localSettings}            & \texttt{-l} \\
			\texttt{onlyDefault}              & \texttt{-d} \\
			\texttt{cruft}                    & \texttt{-c} \\
			\texttt{modifylinebreaks}         & \texttt{-m} \\
			\bottomrule
		\end{tabular}
	\end{table}

	The \texttt{cruft} directive does not work well when used with
	directories that contain spaces.

