% 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=} \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.