% arara: pdflatex: {shell: yes, files: [latexindent]}
\section{indentconfig.yaml, local settings and the -y switch }\label{sec:indentconfig}
 The behaviour of \texttt{latexindent.pl} is controlled from the settings specified in any
 of the YAML files that you tell it to load. By default, \texttt{latexindent.pl} will only
 load \texttt{defaultSettings.yaml}, but there are a few ways that you can tell it to load your
 own settings files.

\subsection{indentconfig.yaml and .indentconfig.yaml}
	\texttt{latexindent.pl} will always check your home directory for \texttt{indentconfig.yaml}
	and  \texttt{.indentconfig.yaml} (unless
	it is called with the \texttt{-d} switch), which is a plain text file you can create that contains the
	\emph{absolute} paths for any settings files that you wish \texttt{latexindent.pl}
	to load. There is no difference between \texttt{indentconfig.yaml} and
	\texttt{.indentconfig.yaml}, other than the fact that \texttt{.indentconfig.yaml} is a `hidden'
	file; thank you to \cite{jacobo-diaz-hidden-config} for providing this feature. In what follows, we
	will use \texttt{indentconfig.yaml}, but it is understood that this could equally represent
	\texttt{.indentconfig.yaml}. If you have both files in existence then \texttt{indentconfig.yaml}
	takes priority.

	For Mac and Linux users, their home directory is \texttt{~/username} while Windows
	(Vista onwards) is \lstinline!C:\Users\username!\footnote{If you're not sure
		where to put \texttt{indentconfig.yaml}, don't
		worry \texttt{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 \texttt{indentconfig.yaml} file.

	\begin{yaml}{\texttt{indentconfig.yaml} (sample)}{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 \texttt{.yaml} files you specify in \texttt{indentconfig.yaml} will be
	loaded in the order in which you write them. Each file doesn't have to have every switch
	from \texttt{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
	\texttt{defaultSettings.yaml} in another directory and call it, for example,
	\texttt{mysettings.yaml}. Once you have added the path to \texttt{indentconfig.yaml} you can
	change the switches and add more code-block names to it as you see fit -- have a look at
	\cref{lst:mysettings} for an example that uses four tabs for the default indent, adds
	the \texttt{tabbing} environment/command to the list of environments that contains
	alignment delimiters; you might also like to refer to the many YAML files detailed
	throughout the rest of this documentation.

	\begin{yaml}{\texttt{mysettings.yaml} (example)}{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 \texttt{indent.log} for
	details -- if you have specified a path that \texttt{latexindent.pl} doesn't recognise
	then you'll get a warning, otherwise you'll get confirmation that \texttt{latexindent.pl}
	has read your settings file \footnote{Windows users
		may find that they have to end \texttt{.yaml} files with a blank line}.

	\begin{warning}
		When editing \texttt{.yaml} files it is \emph{extremely} important
		to remember how sensitive they are to spaces. I highly recommend copying
		and pasting from \texttt{defaultSettings.yaml} when you create your
		first \texttt{whatevernameyoulike.yaml} file.

		If \texttt{latexindent.pl} can not read your \texttt{.yaml} file it
		will tell you so in \texttt{indent.log}.
	\end{warning}

\subsection{localSettings.yaml}\label{sec:localsettings}
	The \texttt{-l} switch tells \texttt{latexindent.pl} to look for
	\texttt{localSettings.yaml} in the \emph{same directory} as \texttt{myfile.tex}.  For
	example, if you use the following command
	\begin{commandshell}
latexindent.pl -l myfile.tex
\end{commandshell}
	then \texttt{latexindent.pl} will (assuming it exists) load \texttt{localSettings.yaml} from
	the same directory as \texttt{myfile.tex}.

	If you'd prefer to name your \texttt{localSettings.yaml} file something different, (say,
	\texttt{mysettings.yaml} as in \cref{lst:mysettings}) then you can call
	\texttt{latexindent.pl} using, for example,
	\begin{commandshell}
latexindent.pl -l=mysettings.yaml myfile.tex
\end{commandshell}

	Any settings file(s) specified using the \texttt{-l} switch will be read
	\emph{after} \texttt{defaultSettings.yaml} and, assuming they exist, any user setting
	files specified in \texttt{indentconfig.yaml}.

	Your settings file can contain any switches that you'd like to change; a sample is shown
	in \cref{lst:localSettings}, and you'll find plenty of further examples throughout this
	manual.

	\begin{yaml}{\texttt{localSettings.yaml} (example)}{lst:localSettings}
#  verbatim environments - environments specified
#  here will not be changed at all!
verbatimEnvironments:
    cmhenvironment: 0
    myenv: 1
\end{yaml}

	You can make sure that your settings file has been loaded by checking
	\texttt{indent.log} for details; if it can not be read then you receive a warning,
	otherwise you'll get confirmation that \texttt{latexindent.pl} has read your settings
	file.

\subsection{The -y|yaml switch}\label{sec:yamlswitch}
	You%
	\announce{2017-08-21}{demonstration of the -y switch} may use the
	\texttt{-y} switch to load your settings;  for example, if you wished to
	specify the settings from \cref{lst:localSettings} using the \texttt{-y} switch,
	then you could use the following command:
	\begin{commandshell}
latexindent.pl -y="verbatimEnvironments:cmhenvironment:0;myenv:1" myfile.tex
\end{commandshell}
	Note the use of \texttt{;} to specify another field within
	\texttt{verbatimEnvironments}. This is shorthand, and equivalent, to using the following
	command:
	\begin{commandshell}
latexindent.pl -y="verbatimEnvironments:cmhenvironment:0,verbatimEnvironments:myenv:1" myfile.tex
\end{commandshell}
	You may, of course, specify settings using the \texttt{-y} switch as well as,
	for example, settings loaded using the \texttt{-l} switch; for example,
	\begin{commandshell}
latexindent.pl -l=mysettings.yaml -y="verbatimEnvironments:cmhenvironment:0;myenv:1" myfile.tex
\end{commandshell}
	Any settings specified using the \texttt{-y} switch will be loaded
	\emph{after} any specified using \texttt{indentconfig.yaml} and the
	\texttt{-l} switch.

	If you wish to specify any regex-based settings using the \texttt{-y} switch,
	it is important not to use quotes surrounding the regex; for example, with reference to
	the `one sentence per line' feature (\vref{sec:onesentenceperline}) and the listings within
	\vref{lst:sentencesEndWith}, the following settings give the option to have sentences end
	with a semicolon
	\begin{commandshell}
latexindent.pl -m --yaml='modifyLineBreaks:oneSentencePerLine:sentencesEndWith:other:\;'
\end{commandshell}

\subsection{Settings load order}\label{sec:loadorder}
	\texttt{latexindent.pl} loads the settings files in the following order:
	\begin{enumerate}
		\item \texttt{defaultSettings.yaml} is always loaded, and can not be renamed;
		\item \texttt{anyUserSettings.yaml} and any other arbitrarily-named files specified in
		      \texttt{indentconfig.yaml};
		\item \texttt{localSettings.yaml} but only if found in the same directory as \texttt{myfile.tex}
		      and called with \texttt{-l} switch; this file can be renamed, provided that
		      the call to \texttt{latexindent.pl} is adjusted accordingly (see \cref{sec:localsettings}).
		      You may specify both relative and absolute%
		      \announce{2017-08-21}*{-l absolute paths} paths to other YAML files using the \texttt{-l} switch,
		      separating multiple files using commas;
		\item any settings%
		      \announce{2017-08-21}{-y switch load order} specified in the
		      \texttt{-y} switch.
	\end{enumerate}
	A visual representation of this is given in \cref{fig:loadorder}.

	\begin{figure}[!htb]
		\centering
		\input{figure-schematic}
		\caption{Schematic of the load order described in \cref{sec:loadorder}; solid lines represent
			mandatory files, dotted lines represent optional files. \texttt{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}
