summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/doc/support/latexindent/documentation/latexindent.tex
diff options
context:
space:
mode:
Diffstat (limited to 'Master/texmf-dist/doc/support/latexindent/documentation/latexindent.tex')
-rw-r--r--Master/texmf-dist/doc/support/latexindent/documentation/latexindent.tex1512
1 files changed, 1512 insertions, 0 deletions
diff --git a/Master/texmf-dist/doc/support/latexindent/documentation/latexindent.tex b/Master/texmf-dist/doc/support/latexindent/documentation/latexindent.tex
new file mode 100644
index 00000000000..c39b89e627e
--- /dev/null
+++ b/Master/texmf-dist/doc/support/latexindent/documentation/latexindent.tex
@@ -0,0 +1,1512 @@
+% arara: pdflatex
+% arara: bibtex
+% arara: pdflatex
+% arara: pdflatex
+% !arara: pdflatex
+% !arara: indent: {overwrite: yes, trace: yes, localSettings: yes, silent: yes}
+\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{tcolorbox} % framed environments
+\usepackage[charter]{mathdesign} % changes font
+\usepackage[expansion=false,kerning=true]{microtype} % better kerning
+\usepackage{enumitem} % custom lists
+% setup gitinfo2, as in the manual, details just above begin{document}
+\usepackage[mark,grumpy]{gitinfo2}
+\usepackage{examplep}
+% tcolorbox libraries
+\tcbuselibrary{breakable,skins,listings}
+% tikz libraries
+\usetikzlibrary{positioning}
+\usetikzlibrary{decorations.pathmorphing}
+\usetikzlibrary{decorations,shapes}
+\usepackage{varioref} % clever referencing
+\usepackage{hyperref}
+\hypersetup{
+ pdfauthor={Chris Hughes},
+ pdftitle={latexindent.pl package},
+ pdfkeywords={perl;beautify;indentation},
+ bookmarksnumbered,
+ bookmarksopen,
+ linktocpage,
+ colorlinks=true,
+ linkcolor=blue,
+ citecolor=black,
+}
+\usepackage{cleveref}
+
+\addbibresource{latex-indent}
+\addbibresource{contributors}
+
+
+% http://tex.stackexchange.com/questions/122135/how-to-add-a-png-icon-on-the-right-side-of-a-tcolorbox-title
+\newtcolorbox{warning}{parbox=false,breakable,enhanced,arc=0mm,colback=red!5,colframe=red,leftrule=12mm,%
+ overlay={\node[anchor=north west,outer sep=2pt] at (frame.north west) {\includegraphics[width=8mm]{warning}}; }}
+
+\makeatletter
+\tcbset{
+ addtolol/.style={list entry={\kvtcb@title},add to list={lol}{lstlisting}},
+}
+
+\newtcblisting[use counter=lstlisting]{cmhlistings}[3][]{%
+ width=\linewidth,
+ breakable,
+ colback=blue!5!white,
+ colframe=white!85!black,
+ top=0cm,
+ bottom=0cm,
+ left=6mm,
+ listing only,
+ listing options={#1},
+ center title,
+ title={\color{black}{\scshape Listing \thetcbcounter}: ~#2},label={#3},
+ addtolol,
+}
+
+\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,
+ %xleftmargin=1.5em,
+}%
+\lstdefinestyle{yaml}{%
+ numbers=left,
+ numberstyle=\color{black},}
+\lstdefinestyle{demo}{
+ numbers=none,
+ linewidth=1.25\textwidth,
+ columns=fullflexible,
+}
+
+% stars around contributors
+\pgfdeclaredecoration{stars}{initial}{
+ \state{initial}[width=15pt]
+ {
+ \pgfmathparse{round(rnd*100)}
+ \pgfsetfillcolor{yellow!\pgfmathresult!orange}
+ \pgfsetstrokecolor{yellow!\pgfmathresult!red}
+ \pgfnode{star}{center}{}{}{\pgfusepath{stroke,fill}}
+ }
+ \state{final}
+ {
+ \pgfpathmoveto{\pgfpointdecoratedpathlast}
+ }
+}
+
+\newtcolorbox{stars}{%
+ enhanced jigsaw,
+ breakable, % allow page breaks
+ left=0cm,
+ top=0cm,
+ before skip=0.2cm,
+ boxsep=0cm,
+ frame style={draw=none,fill=none}, % hide the default frame
+ colback=white,
+ overlay={
+ \draw[inner sep=0,minimum size=rnd*15pt+2pt]
+ decorate[decoration={stars,segment length=2cm}] {
+ decorate[decoration={zigzag,segment length=2cm,amplitude=0.3cm}] {
+ ([xshift=-.5cm,yshift=0.1cm]frame.south west) -- ([xshift=-.5cm,yshift=0.4cm]frame.north west)
+ }};
+ \draw[inner sep=0,minimum size=rnd*15pt+2pt]
+ decorate[decoration={stars,segment length=2cm}] {
+ decorate[decoration={zigzag,segment length=2cm,amplitude=0.3cm}] {
+ ([xshift=.75cm,yshift=0.1cm]frame.south east) -- ([xshift=.75cm,yshift=0.6cm]frame.north east)
+ }};
+ },
+ % paragraph skips obeyed within tcolorbox
+ parbox=false,
+}
+
+% copied from /usr/local/texlive/2013/texmf-dist/tex/latex/biblatex/bbx/numeric.bbx
+% the only modification is the \stars and \endstars
+\defbibenvironment{specialbib}
+{\stars\list
+ {\printtext[labelnumberwidth]{%
+ \printfield{prefixnumber}%
+ \printfield{labelnumber}}}
+ {\setlength{\labelwidth}{\labelnumberwidth}%
+ \setlength{\leftmargin}{\labelwidth}%
+ \setlength{\labelsep}{\biblabelsep}%
+ \addtolength{\leftmargin}{\labelsep}%
+ \setlength{\itemsep}{\bibitemsep}%
+ \setlength{\parsep}{\bibparsep}}%
+ \renewcommand*{\makelabel}[1]{\hss##1}}
+{\endlist\endstars}
+{\item}
+
+% see: http://tex.stackexchange.com/questions/2245/verbatim-description-list-item
+\newcommand{\verbitem}[1]{\small\PVerb{#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{listing}{Listing}{Listings}
+\Crefname{listing}{Listing}{Listings}
+
+% headers and footers
+\fancyhf{} % delete current header and footer
+\fancyhead[R]{\bfseries\thepage}
+\fancyheadoffset[L]{3cm}
+\pagestyle{fancy}
+
+% renew plain style
+\fancypagestyle{plain}{%
+\fancyhf{} % clear all header and footer fields
+\renewcommand{\headrulewidth}{0pt}
+\renewcommand{\footrulewidth}{0pt}}
+
+% sidebyside environment
+\newenvironment{sidebyside}{\begin{adjustwidth}{-3cm}{1cm}}{\end{adjustwidth}}
+
+% gitinfo2 settings
+\renewcommand{\gitMark}{\gitBranch\,@\,\gitAbbrevHash{}\,\textbullet{}\,\gitAuthorDate }
+
+% setting up gitinfo2:
+% copy the file post-xxx-sample.txt from https://www.ctan.org/tex-archive/macros/latex/contrib/gitinfo2
+% and put it in .git/hooks/post-checkout
+% then
+% cd .git/hooks
+% chmod g+x post-checkout
+% chmod +x post-checkout
+% cp post-checkout post-commit
+% cp post-checkout post-merge
+% cd ../..
+% git checkout master
+% git checkout develop
+% ls .git
+% and you should see gitHeadInfo.gin
+\begin{document}
+% \begin{noindent}
+ \title{\lstinline[basicstyle=\huge\ttfamily]!latexindent.pl!\\[1cm]
+ Version 2.2}
+% \end{noindent}
+\author{Chris Hughes \footnote{and contributors! (See \vref{sec:contributors}.)}}
+\maketitle
+\begin{abstract}
+ \lstinline!latexindent.pl! is a \lstinline!Perl! script that indents \lstinline!.tex! (and other)
+ 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.
+
+There have been several contributors to the project so far (and hopefully more in
+the future!); thank you very much to the people detailed in \vref{sec:contributors}
+for their valued contributions.
+
+\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{sidebyside}
+ \noindent
+ \begin{minipage}{.6\textwidth}
+ \begin{cmhlistings}[style=demo]{\lstinline!filecontents! before}{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{cmhlistings}
+ \end{minipage}%
+ \noindent
+ \begin{minipage}{.6\textwidth}
+ \begin{cmhlistings}[style=demo]{\lstinline!filecontents! after}{lst:filecontentsafter}
+\begin{filecontents}{mybib.bib}
+ @online{strawberryperl,
+ title="Strawberry Perl",
+ url="http://strawberryperl.com/"}
+ @online{cmhblog,
+ title="A Perl script for ...
+ url="...
+\end{filecontents}
+ \end{cmhlistings}
+ \end{minipage}
+ \begin{minipage}{.6\textwidth}
+ \begin{cmhlistings}[style=demo]{\lstinline!tikzset! before}{lst:tikzsetbefore}
+\tikzset{
+shrink inner sep/.code={
+\pgfkeysgetvalue...
+\pgfkeysgetvalue...
+}
+}
+ \end{cmhlistings}
+ \end{minipage}%
+ \begin{minipage}{.6\textwidth}
+ \begin{cmhlistings}[style=demo]{\lstinline!tikzset! after}{lst:tikzsetafter}
+\tikzset{
+ shrink inner sep/.code={
+ \pgfkeysgetvalue...
+ \pgfkeysgetvalue...
+ }
+}
+ \end{cmhlistings}
+ \end{minipage}
+ \begin{minipage}{.6\textwidth}
+ \begin{cmhlistings}[style=demo]{\lstinline!pstricks! before}{lst:pstricksbefore}
+\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{cmhlistings}
+ \end{minipage}%
+ \begin{minipage}{.6\textwidth}
+ \begin{cmhlistings}[style=demo]{\lstinline!pstricks! after}{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{cmhlistings}
+ \end{minipage}
+ \end{sidebyside}
+
+\section{How to use the script}
+\lstinline!latexindent.pl! ships as part of the \TeX Live distribution for
+Linux and Mac users; \lstinline!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 \lstinline!path! variable can be updated.
+
+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!.
+
+There are two ways to use \lstinline!latexindent.pl!: from the command line,
+and using \lstinline!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}.
+
+\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.
+
+\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, either in short or long form as detailed below.
+\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=.25cm]
+ \item[] \lstinline!latexindent.pl!
+
+ This will output a welcome message to the terminal, including the version number
+ and available options.
+ \item[\verbitem{-h, --help}] \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, --overwrite}] \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,--outputfile}] \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, --silent}] \lstinline!latexindent.pl -s myfile.tex!
+
+ Silent mode: no output will be given to the terminal.
+ \item[\verbitem{-t, --trace}] \lstinline!latexindent.pl -t myfile.tex!
+
+ \label{page:traceswitch}
+ 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{-tt, --ttrace}] \lstinline!latexindent.pl -tt myfile.tex!
+
+ \emph{More detailed} tracing mode: this option gives more details to \lstinline!indent.log!
+ than the standard \lstinline!trace! option.
+ \item[\verbitem{-l, --local[=myyaml.yaml]}] \lstinline!latexindent.pl -l myfile.tex!
+
+\lstinline!latexindent.pl -l=myyaml.yaml myfile.tex!
+
+\lstinline!latexindent.pl -l myyaml.yaml 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!.
+
+The \lstinline!-l! flag can take an \emph{optional} parameter which details the name of a \lstinline!yaml! file
+that resides in the same directory as \lstinline!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 \lstinline!localSettings.yaml!.
+
+ \item[\verbitem{-d, --onlydefault}] \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! or \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!/\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, --cruft=<directory>}]\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}
+
+\lstinline!latexindent.pl! can also be called on a file without the file extension, for
+example \lstinline[breaklines=true,breakatwhitespace=true,]!latexindent.pl myfile! and in which case, you can specify
+the order in which extensions are searched for; see \vref{lst:fileExtensionPreference}
+for full details.
+
+\subsection{From \lstinline!arara!}\label{sec: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{cmhlistings}[style=demo,escapeinside={(*@}{@*)}]{\lstinline!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}
+
+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 \TeX{} 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 backup 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{cycleThroughBackUps}]\lstinline!0!
+
+ Some users may wish to cycle through backup files, by deleting the
+ oldest backup file and keeping only the most recent; for example,
+ with \lstinline!maxNumberOfBackUps: 4!, and \lstinline!cycleThroughBackUps!
+ set to \lstinline!1! then the \lstinline!copy! procedure given in \cref{lst:cycleThroughBackUps}
+ would be obeyed.
+
+ \begin{cmhlistings}[language=Perl]{\lstinline!cycleThroughBackUps!}{lst:cycleThroughBackUps}
+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{cmhlistings}
+
+ \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 on \cpageref{lst:checkunmatched}}.
+ \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 on
+ \cpageref{lst:checkunmatched}}.
+
+ \item[\verbitem{removeTrailingWhitespace}] \lstinline!0!
+
+ By default \lstinline!latexindent.pl! indents every line (including empty lines)
+ which creates `trailing white space' feared by most version control systems. If
+ this option is set to \lstinline!1!, trailing white space 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. Thanks to \cite{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:basic}
+ shows more details. In fact, the fields in \verbitem{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{cmhlistings}[style=yaml]{\lstinline!lookForAlignDelims! (basic)}{lst:aligndelims:basic}
+lookForAlignDelims:
+ tabular: 1
+ tabularx: 1
+ longtable: 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{cmhlistings}
+
+ 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:basic,lst:tabularafter:basic}.
+
+ \begin{minipage}{.5\textwidth}
+ \begin{cmhlistings}[style=demo,columns=fixed]{\lstinline!tabular! before}{lst:tabularbefore:basic}
+\begin{tabular}{cccc}
+1& 2 &3 &4\\
+5& &6 &\\
+\end{tabular}
+ \end{cmhlistings}
+ \end{minipage}%
+ \begin{minipage}{.5\textwidth}
+ \begin{cmhlistings}[style=demo,columns=fixed]{\lstinline!tabular! after (basic)}{lst:tabularafter:basic}
+\begin{tabular}{cccc}
+ 1 & 2 & 3 & 4 \\
+ 5 & & 6 & \\
+\end{tabular}
+ \end{cmhlistings}
+ \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}).
+
+ If you wish to remove the alignment of the \lstinline!\\! within a delimiter-aligned block, then the
+ advanced form of \lstinline!lookForAlignDelims! shown in \cref{lst:aligndelims:advanced} is for you.
+ \begin{cmhlistings}[style=yaml]{\lstinline!lookForAlignDelims! (advanced)}{lst:aligndelims:advanced}
+lookForAlignDelims:
+ tabular:
+ delims: 1
+ alignDoubleBackSlash: 0
+ spacesBeforeDoubleBackSlash: 0
+ tabularx:
+ delims: 1
+ longtable: 1
+ \end{cmhlistings}
+
+ Note that you can use a mixture of the basic and advanced form: in \cref{lst:aligndelims:advanced} \lstinline!tabular! and \lstinline!tabularx!
+ are advanced and \lstinline!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 up to 3 fields:
+ \begin{itemize}
+ \item \lstinline!delims!: switch equivalent to simply specifying, for example, \lstinline!tabular: 1! in
+ the basic version shown in \cref{lst:aligndelims:basic} (default: 1);
+ \item \lstinline!alignDoubleBackSlash!: switch to determine if \lstinline!\\! should be aligned (default: 1);
+ \item \lstinline!spacesBeforeDoubleBackSlash!: optionally, specifies the number of spaces to be inserted
+ before (non-aligned) \lstinline!\\!. In order to use this field, \lstinline!alignDoubleBackSlash! needs
+ to be set to 0 (default: 0).
+ \end{itemize}
+
+ With the settings shown in \cref{lst:aligndelims:advanced} we receive the before-and-after results shown in
+ \cref{lst:tabularbefore:advanced,lst:tabularafter:advanced}; note that the ampersands have been aligned, but
+ the \lstinline!\\! have not (compare the alignment of \lstinline!\\! in \cref{lst:tabularafter:basic,lst:tabularafter:advanced}).
+
+ \begin{minipage}{.5\textwidth}
+ \begin{cmhlistings}[style=demo,columns=fixed]{\lstinline!tabular! before }{lst:tabularbefore:advanced}
+\begin{tabular}{cccc}
+1& 2 &3 &4\\
+5& &6 &\\
+\end{tabular}
+ \end{cmhlistings}
+ \end{minipage}%
+ \begin{minipage}{.5\textwidth}
+ \begin{cmhlistings}[style=demo,columns=fixed]{\lstinline!tabular! after (advanced)}{lst:tabularafter:advanced}
+\begin{tabular}{cccc}
+ 1 & 2 & 3 & 4\\
+ 5 & & 6 &\\
+\end{tabular}
+ \end{cmhlistings}
+ \end{minipage}
+
+ Using \lstinline!spacesBeforeDoubleBackSlash: 3! gives \cref{lst:tabularbefore:spacing,lst:tabularafter:spacing},
+ note the spacing before the \lstinline!\\! in \cref{lst:tabularafter:spacing}.
+
+ \begin{minipage}{.5\textwidth}
+ \begin{cmhlistings}[style=demo,columns=fixed]{\lstinline!tabular! before}{lst:tabularbefore:spacing}
+\begin{tabular}{cccc}
+1& 2 &3 &4\\
+5& &6 &\\
+\end{tabular}
+ \end{cmhlistings}
+ \end{minipage}%
+ \begin{minipage}{.5\textwidth}
+ \begin{cmhlistings}[style=demo,columns=fixed]{\lstinline!tabular! after (spacing)}{lst:tabularafter:spacing}
+\begin{tabular}{cccc}
+ 1 & 2 & 3 & 4 \\
+ 5 & & 6 & \\
+\end{tabular}
+ \end{cmhlistings}
+ \end{minipage}
+
+
+
+
+ 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}...\end{tabular}!, then you use the mark up
+ illustrated in \cref{lst:alignmentmarkup}. 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 \lstinline!lookForAlignDelims!.
+ \begin{cmhlistings}[style=demo,columns=fixed]{Mark up for aligning delimiters outside of environments}{lst:alignmentmarkup}
+\matrix{%
+%* \begin{tabular}
+ 1 & 2 & 3 & 4 \\
+ 5 & & 6 & \\
+%* \end{tabular}
+}
+ \end{cmhlistings}
+
+ \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{cmhlistings}[style=yaml]{\lstinline!verbatimEnvironments!}{lst:verbatimEnvironments}
+verbatimEnvironments:
+ verbatim: 1
+ lstlisting: 1
+ \end{cmhlistings}
+ 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{cmhlistings}[style=yaml]{\lstinline!noIndentBlock!}{lst:noIndentBlock}
+noIndentBlock:
+ noindent: 1
+ cmhtest: 1
+ \end{cmhlistings}
+
+ 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={(*@}{@*)}]{\lstinline!noIndentBlock! demonstration}{lst:noIndentBlockdemo}
+%(*@@*) \begin{noindent}
+ this code
+ won't
+ be touched
+ by
+ latexindent.pl!
+%(*@@*)\end{noindent}
+ \end{cmhlistings}
+
+ \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{cmhlistings}[style=yaml]{\lstinline!noAdditionalIndent!}{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{cmhlistings}
+ Note in particular from \cref{lst:noAdditionalIndent} that if you wish content within
+ \lstinline!\[! and \lstinline!\]! to receive no additional indentation 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{cmhlistings}[style=yaml]{\lstinline!indentRules!}{lst:indentRules}
+indentRules:
+ myenvironment: "\t\t"
+ anotherenvironment: "\t\t\t\t"
+ \[: "\t"
+ \end{cmhlistings} %%%%%\] 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 most
+ of the fields that we have considered previously, because each element is
+ itself a field which has two elements: \lstinline!indent! and \lstinline!level!. (Similar
+ in structure to the advanced form of \lstinline!lookForAlignDelims! in \cref{lst:aligndelims:advanced}.)
+ \begin{cmhlistings}[style=yaml]{\lstinline!indentAfterHeadings!}{lst:indentAfterHeadings}
+indentAfterHeadings:
+ part:
+ indent: 0
+ level: 1
+ chapter:
+ indent: 0
+ level: 2
+ section:
+ indent: 0
+ level: 3
+ ...
+ \end{cmhlistings}
+ 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!).
+
+ \item[\verbitem{indentAfterItems}] The environments specified in \lstinline!indentAfterItems! tell
+ \lstinline!latexindent.pl! to look for \lstinline!\item! commands; if these switches are set to \lstinline!1!
+ then indentation will be performed so as indent the code after each \lstinline!item!.
+ \begin{cmhlistings}{\lstinline!indentAfterItems!}{lst:indentafteritems}
+indentAfterItems:
+ itemize: 1
+ enumerate: 1
+ \end{cmhlistings}
+ A demonstration is given in \cref{lst:itemsbefore,lst:itemsafter}
+
+ \begin{minipage}{.5\textwidth}
+ \begin{cmhlistings}[style=demo,xleftmargin=-3mm,columns=fixed]{\lstinline!items! before}{lst:itemsbefore}
+\begin{itemize}
+\item some text here
+some more text here
+some more text here
+\item another item
+\end{itemize}
+ \end{cmhlistings}
+ \end{minipage}%
+ \begin{minipage}{.5\textwidth}
+ \begin{cmhlistings}[style=demo,xleftmargin=-3mm,columns=fixed]{\lstinline!items! after}{lst:itemsafter}
+\begin{itemize}
+ \item some text here
+ some more text here
+ some more text here
+ \item another item
+\end{itemize}
+ \end{cmhlistings}
+ \end{minipage}
+
+ \item[\verbitem{itemNames}] If you have your own \lstinline!item! commands (perhaps you
+ prefer to use \lstinline!myitem!, for example)
+ then you can put populate them in \lstinline!itemNames!.
+ For example, users of the \lstinline!exam! document class might like to add
+ \lstinline!parts! to \lstinline!indentAfterItems! and \lstinline!part! to \lstinline!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}
+
+ \item[\verbitem{constructIfElseFi}] The commands specified in this field
+ will tell \lstinline!latexindent.pl! to look for constructs that
+ have the form \lstinline!\if...! \lstinline!\else...! \lstinline!\fi!, such as,
+ for example, \lstinline!\ifnum!; see \cref{lst:iffibefore,lst:iffiafter} for
+ a before-and-after demonstration.
+
+ \begin{minipage}{.5\textwidth}
+ \begin{cmhlistings}[style=demo,xleftmargin=-3mm,columns=fixed]{\lstinline!if-else-fi! construct before}{lst:iffibefore}
+\ifnum\radius>5
+\ifnum\radius<16
+\draw[decorate,...
+\fi
+\fi
+ \end{cmhlistings}
+ \end{minipage}%
+ \begin{minipage}{.5\textwidth}
+ \begin{cmhlistings}[style=demo,xleftmargin=-3mm,columns=fixed]{\lstinline!if-else-fi! construct after}{lst:iffiafter}
+\ifnum\radius>5
+ \ifnum\radius<16
+ \draw[decorate,...
+ \fi
+\fi
+ \end{cmhlistings}
+ \end{minipage}
+
+ \item[\verbitem{fileExtensionPreference}] \lstinline!latexindent.pl! can be called to
+ act on a file without
+ specifying the file extension. For example we can call \lstinline!latexindent.pl myfile!
+ in which case the script will look for \lstinline!myfile! with the extensions
+ specified in \lstinline!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.
+ \begin{cmhlistings}[style=yaml]{\lstinline!fileExtensionPreference!}{lst:fileExtensionPreference}
+fileExtensionPreference:
+ .tex: 1
+ .sty: 2
+ .cls: 3
+ .bib: 4
+ \end{cmhlistings}
+ Calling \lstinline!latexindent.pl myfile! with the details specified in \cref{lst:fileExtensionPreference}
+ means that the script will first look for \lstinline!myfile.tex!, then \lstinline!myfile.sty!, \lstinline!myfile.cls!,
+ and finally \lstinline!myfile.bib! in order.
+\item[\verbitem{logFilePreferences}]
+ \lstinline!latexindent.pl! writes information to \lstinline!indent.log!, some
+ of which can be customised by changing \lstinline!logFilePreferences!; see \cref{lst:logFilePreferences}.
+\begin{cmhlistings}[style=yaml]{\lstinline!logFilePreferences!}{lst:logFilePreferences}
+logFilePreferences:
+ showEveryYamlRead: 1
+ showAlmagamatedSettings: 0
+ endLogFileWith: '--------------'
+ traceModeIncreaseIndent: '>>'
+ traceModeAddCurrentIndent: '||'
+ traceModeDecreaseIndent: '<<'
+ traceModeBetweenLines: "\n"
+ \end{cmhlistings}
+If you load your own user settings (see \vref{sec:indentconfig}) then \lstinline!latexindent.pl! will
+detail them in \lstinline!indent.log!; you can choose not to have the details logged by switching
+\lstinline!showEveryYamlRead! to \lstinline!0!. Once all of your settings have
+been loaded, you can see the amalgamated settings by switching \lstinline!showAlmagamatedSettings!
+to \lstinline!1!, if you wish. The log file will end with the characters
+given in \lstinline!endLogFileWith!.
+
+When \lstinline!trace! mode is active (see \cpageref{page:traceswitch}) verbose information is written
+to \lstinline!indent.log!. The decoration of this information can be customised through the remaining
+fields given in \cref{lst:logFilePreferences}; note, in particular, the use of \lstinline!"\n"! for
+escaped characters (using single quotes will not produce the same results).
+
+\item[\verbitem{fileContentsEnvironments}]
+ \lstinline!latexindent.pl! determines when the main document begins by looking for \lstinline!\begin{document}!;
+ it will not do so when inside any of the environments specified in \lstinline!fileContentsEnvironments!, see
+ \cref{lst:fileContentsEnvironments}.
+\begin{cmhlistings}[style=yaml]{\lstinline!fileContentsEnvironments!}{lst:fileContentsEnvironments}
+fileContentsEnvironments:
+ filecontents: 1
+ filecontents*: 1
+ \end{cmhlistings}
+
+ \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{cmhlistings}[style=yaml]{\lstinline!checkunmatched!}{lst:checkunmatched}
+checkunmatched:
+ parbox: 1
+ vbox: 1
+ \end{cmhlistings}
+ \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{cmhlistings}[style=yaml]{\lstinline!checkunmatchedELSE!}{lst:checkunmatchedELSE}
+checkunmatchedELSE:
+ pgfkeysifdefined: 1
+ DTLforeach: 1
+ ifthenelse: 1
+ \end{cmhlistings}
+ \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{cmhlistings}[style=yaml]{\lstinline!checkunmatchedbracket!}{lst:checkunmatchedbracket}
+checkunmatchedbracket:
+ psSolid: 1
+ pgfplotstablecreatecol: 1
+ pgfplotstablesave: 1
+ pgfplotstabletypeset: 1
+ mycommand: 1
+ \end{cmhlistings}
+\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 (after reading \cref{sec:indentconfig}) you put the fields in \cref{lst:conflict} into
+one of your settings files.
+\begin{cmhlistings}[style=yaml]{Conflicting ideas}{lst:conflict}
+indentRules:
+ myenvironment: "\t\t"
+noAdditionalIndent:
+ myenvironment: 1
+\end{cmhlistings}
+
+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 will not have to be addressed.
+
+Let's consider another conflicting example in \cref{lst:bigconflict}
+\begin{cmhlistings}[style=yaml]{More conflicting ideas}{lst:bigconflict}
+lookForAlignDelims:
+ myenvironment: 1
+verbatimEnvironments:
+ myenvironment: 1
+\end{cmhlistings}
+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! and \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!
+and \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. There is no difference
+between \lstinline!indentconfig.yaml! and \lstinline!.indentconfig.yaml!, other than the
+fact that \lstinline!.indentconfig.yaml! is a `hidden' file; thank you to \cite{jacobo-diaz-hidden-config}
+for providing this feature. In what follows, we will use \lstinline!indentconfig.yaml!, but it
+is understood that this equally represents \lstinline!.indentconfig.yaml! as well. If you
+have both files in existence, \lstinline!indentconfig.yaml! takes priority.
+
+For Mac and Linux users, their 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{cmhlistings}[style=yaml]{\lstinline!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{cmhlistings}
+
+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, adds the \lstinline!tabbing!
+environment to the list of environments that contains alignment delimiters,
+and adds the changes we described on \cpageref{page:examsettings}.
+
+\begin{cmhlistings}[style=yaml]{\lstinline!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
+
+# If you use the exam documentclass, you might
+# like the following settings
+# environments that have \item commands
+indentAfterItems:
+ parts: 1
+
+# commands to be treated like \item
+itemNames:
+ part: 1
+\end{cmhlistings}
+
+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!}\label{sec:localsettings}
+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.
+
+The \emph{local} settings file may be called \lstinline!localSettings.yaml!, and
+it can contain any switches that you'd
+like to change--a sample is shown in \cref{lst:localSettings}.
+
+\begin{cmhlistings}[style=yaml]{\lstinline!localSettings.yaml! (example)}{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{cmhlistings}
+
+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!.
+
+If you'd prefer to name your \lstinline!localSettings.yaml! file something different, (say, \lstinline!myyaml.yaml!) then
+you can call \lstinline!latexindent.pl! using, for example, \lstinline[breaklines=true]!latexindent.pl -l=myyaml.yaml myfile.tex!.
+
+\subsection{Settings load order}\label{sec:loadorder}
+\lstinline!latexindent.pl! loads the settings files in the following order:
+\begin{enumerate}
+ \item \lstinline!defaultSettings.yaml! is always loaded, and can not be renamed;
+ \item \lstinline!anyUserSettings.yaml! and any other arbitrarily-named files specified in \lstinline!indentconfig.yaml!;
+ \item \lstinline!localSettings.yaml! but only if found in the same directory as \lstinline!myfile.tex! and called
+ with \lstinline!-l! switch; this file can be renamed, provided that the call to \lstinline!latexindent.pl! is adjusted
+ accordingly (see \cref{sec:localsettings}).
+\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{cmhlistings}[style=demo,escapeinside={(*@}{@*)}]{When to set \lstinline!alwaysLookforSplitBrackets=0!}{lst:casestudy}
+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{cmhlistings}
+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 lines 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}).
+
+You can run \lstinline!latexindent! on \lstinline!.sty!, \lstinline!.cls! and any filetypes
+that you specify in \lstinline[breaklines=true]!fileExtensionPreference! (see \vref{lst:fileExtensionPreference});
+if you find a case in which the script struggles, please feel free
+to report it at \cite{latexindent-home}, and
+in the meantime, consider using 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, the best way to contact me is to
+report an issue on \cite{latexindent-home}; otherwise, feel free to find me on
+the \url{http://tex.stackexchange.com} site; I'm often around
+and in the chat room.
+
+\nocite{*}
+\section{References}
+\printbibliography[heading=subbibnumbered,title={External links},notkeyword=contributor]
+\printbibliography[env=specialbib,heading=subbibnumbered,title={Contributors\label{sec:contributors}},keyword=contributor]
+
+\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{cmhlistings}[language=Perl]{\lstinline!helloworld.pl!}{lst:helloworld}
+#!/usr/bin/perl
+
+use strict;
+use warnings;
+use FindBin;
+use YAML::Tiny;
+use File::Copy;
+use File::Basename;
+use Getopt::Long;
+use File::HomeDir;
+
+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 \lstinline!Perl! distribution. For example, Ubuntu users
+might visit the software center, or else run
+\begin{lstlisting}[numbers=none]
+sudo perl -MCPAN -e 'install "File::HomeDir"'
+\end{lstlisting}
+
+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{lstlisting}[numbers=none]
+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{lstlisting}
+
+Strawberry Perl users on Windows might use
+\lstinline!CPAN client!. All of the modules are readily available on CPAN \cite{cpan}.
+
+As of Version 2.1, \lstinline!indent.log! will contain details of the location
+of the Perl modules on your system. \lstinline!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 \lstinline!trace! option, e.g \lstinline!latexindent.exe -t myfile.tex!.
+
+\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{cmhlistings}[style=yaml,numbers=none]{The \lstinline!arara! rule}{lst:arararule}
+...
+arguments:
+- identifier: trace
+ flag: <arara> @{ isTrue( parameters.trace, "-t" ) }
+...
+\end{cmhlistings}
+
+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{cmhlistings}[style=yaml,numbers=none]{The \lstinline!arara! rule (modified)}{lst:arararulemod}
+...
+arguments:
+- identifier: trace
+ flag: <arara> @{ isTrue( parameters.trace, "-t" ) }
+ default: "-t"
+...
+\end{cmhlistings}
+
+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!.
+
+\section{Updating the \lstinline!path! variable}\label{sec:updating-path}
+\lstinline!latexindent.pl! ships with a few scripts that can update the \lstinline!path! variables
+\footnote{Thanks to \cite{jasjuang} for this feature!}. If you're
+on a Linux or Mac machine, then you'll want \lstinline!CMakeLists.txt! from \cite{latexindent-home}.
+\subsection{Add to path for Linux}
+To add \lstinline!latexindent.pl! to the path for Linux, follow these steps:
+\begin{enumerate}
+ \item download \lstinline!latexindent.pl!, \lstinline!defaultSettings.yaml!, to your
+ chosen directory from \cite{latexindent-home} ;
+ \item within your directory, create a directory called \lstinline!path-helper-files! and
+ download \lstinline!CMakeLists.txt! and \lstinline!cmake_uninstall.cmake.in!
+ from \cite{latexindent-home}/path-helper-files to this directory;
+ \item run \lstinline!ls /usr/local/bin! to see what is \emph{currently} in there;
+ \item run the commands given in \cref{linux-add-to-path};
+ \item run \lstinline!ls /usr/local/bin! again to check that \lstinline!latexindent.pl! and \lstinline!defaultSettings.yaml!
+ have been added.
+\end{enumerate}
+\begin{cmhlistings}[style=yaml,numbers=none]{Add to path from a Linux terminal}{linux-add-to-path}
+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{cmhlistings}
+To \emph{remove} the files, run \lstinline!sudo make uninstall!.
+\subsection{Add to path for Windows}
+To add \lstinline!latexindent.exe! to the path for Windows, follow these steps:
+\begin{enumerate}
+ \item download \lstinline!latexindent.exe!, \lstinline!defaultSettings.yaml!, \lstinline!add-to-path.bat!
+ from \cite{latexindent-home} to your chosen directory;
+ \item open a command prompt and run \lstinline!echo %path%! to see what is \emph{currently} in your \lstinline!%path%! variable;
+ \item right click on \lstinline!add-to-path.bat! and \emph{Run as administrator};
+ \item log out, and log back in;
+ \item open a command prompt and run \lstinline!echo %path%! 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 \lstinline!remove-from-path.bat! as administrator.
+\end{document}