path: root/support/latexindent/documentation/sec-how-to-use.tex

% 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;%
 \announce{2018-01-13}{perl module installer helper script} in particular, note that a module installer helper script is
 shipped with \texttt{latexindent.pl}.

\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.

\flagbox{-v, --version}
	\index{switches!-v, --version definition and details}
	\announce{2017-06-25}{version}
	\begin{commandshell}
latexindent.pl -v
\end{commandshell}
	This will output only the version number to the terminal.

\flagbox{-h, --help}
	\index{switches!-h, --help definition and details}

	\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}
	\index{switches!-w, --overwrite definition and details}
	\index{backup files!overwrite switch, -w}
	\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}
	\index{switches!-o, --output definition and details}
	\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} as above is equivalent to using
	\begin{commandshell}
latexindent.pl myfile.tex > output.tex
\end{commandshell}

	You can call the \texttt{-o} switch with the name of the output file
	\emph{without} an extension; in%
	\announce{2017-06-25}{upgrade to -o switch} this case, \texttt{latexindent.pl} will use the extension from the
	original file. For example, the following two calls to \texttt{latexindent.pl} are
	equivalent:
	\begin{commandshell}
latexindent.pl myfile.tex -o=output
latexindent.pl myfile.tex -o=output.tex
\end{commandshell}

	You can call the \texttt{-o} switch using a \texttt{+} symbol at
	the beginning; this will%
	\announce{2017-06-25}{+ sign in o switch}
	concatenate the name of the input file and the text given to the \texttt{-o}
	switch. For example, the following two calls to \texttt{latexindent.pl} are equivalent:
	\begin{commandshell}
latexindent.pl myfile.tex -o=+new
latexindent.pl myfile.tex -o=myfilenew.tex
\end{commandshell}

	You can call the \texttt{-o} switch using a \texttt{++} symbol at
	the end of the name%
	\announce{2017-06-25}{++ in o switch} of your output
	file; this tells \texttt{latexindent.pl} to search successively for the name of your
	output file concatenated with $0, 1, \ldots$ while the name of the output file
	exists.  For example,
	\begin{commandshell}
latexindent.pl myfile.tex -o=output++
\end{commandshell}
	tells \texttt{latexindent.pl} to output to \texttt{output0.tex}, but if it exists then
	output to \texttt{output1.tex}, and so on.

	Calling \texttt{latexindent.pl} with simply
	\begin{commandshell}
latexindent.pl myfile.tex -o=++
\end{commandshell}
	tells it to output to \texttt{myfile0.tex}, but if it exists then output to
	\texttt{myfile1.tex} and so on.

	The \texttt{+} and \texttt{++} feature of the
	\texttt{-o} switch can be combined; for example, calling
	\begin{commandshell}
latexindent.pl myfile.tex -o=+out++
\end{commandshell}
	tells \texttt{latexindent.pl} to output to \texttt{myfileout0.tex}, but if it exists, then
	try \texttt{myfileout1.tex}, and so on.

	There is no need to specify a file extension when using the \texttt{++}
	feature, but if you wish to, then you should include it \emph{after} the
	\texttt{++} symbols, for example
	\begin{commandshell}
latexindent.pl myfile.tex -o=+out++.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}
	\index{switches!-s, --silent definition and details}
	\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}
	\index{switches!-t, --trace definition and details}
	\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}
	\index{switches!-tt, --ttrace definition and details}
	\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,...]}
	\index{switches!-l, --local definition and details}
	\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, if not
	found, it looks for \texttt{localSettings.yaml} (and friends, see \vref{sec:localsettings}) in the current working directory, then these
	\announce{2021-03-14}*{-l switch: localSettings and friends} 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}.%
	\announce{2017-08-21}*{-l switch absolute paths}
	In fact, you can specify both \emph{relative} and \emph{absolute paths} for
	your YAML files; for example
	\begin{commandshell}
latexindent.pl -l=../../myyaml.yaml myfile.tex
latexindent.pl -l=/home/cmhughes/Desktop/myyaml.yaml myfile.tex
latexindent.pl -l=C:\Users\cmhughes\Desktop\myyaml.yaml myfile.tex
\end{commandshell}
	You will find a lot of other explicit demonstrations of how to use the
	\texttt{-l} switch throughout this documentation,

	You can call the \texttt{-l} switch with a `+' symbol either before or after
	\announce{2017-06-25}{+ sign with -l switch} another YAML file; for example:
	\begin{commandshell}
latexindent.pl -l=+myyaml.yaml myfile.tex
latexindent.pl -l "+ myyaml.yaml" myfile.tex
latexindent.pl -l=myyaml.yaml+  myfile.tex
\end{commandshell}
	which translate, respectively, to
	\begin{commandshell}
latexindent.pl -l=localSettings.yaml,myyaml.yaml myfile.tex
latexindent.pl -l=localSettings.yaml,myyaml.yaml myfile.tex
latexindent.pl -l=myyaml.yaml,localSettings.yaml myfile.tex
\end{commandshell}
	Note that the following is \emph{not} allowed:
	\begin{commandshell}
latexindent.pl -l+myyaml.yaml myfile.tex
\end{commandshell}
	and
	\begin{commandshell}
latexindent.pl -l + myyaml.yaml myfile.tex
\end{commandshell}
	will \emph{only} load \texttt{localSettings.yaml}, and \texttt{myyaml.yaml}
	will be ignored. If you wish to use spaces between any of the YAML settings, then you
	must wrap the entire list of YAML files in quotes, as demonstrated above.

	You may also choose to omit the \texttt{yaml} extension, such as
	\announce{2017-06-25}{no extension for -l switch}
	\begin{commandshell}
latexindent.pl -l=localSettings,myyaml myfile.tex
\end{commandshell}
\flagbox{-y, --yaml=yaml settings}
	\index{switches!-y, --yaml definition and details}
	\index{indentation!default}
	\index{indentation!defaultIndent using -y switch}
	\begin{commandshell}
latexindent.pl myfile.tex -y="defaultIndent: ' '"
latexindent.pl myfile.tex -y="defaultIndent: ' ',maximumIndentation:' '"
latexindent.pl myfile.tex -y="indentRules: one: '\t\t\t\t'"
latexindent.pl myfile.tex -y='modifyLineBreaks:environments:EndStartsOnOwnLine:3' -m
latexindent.pl myfile.tex -y='modifyLineBreaks:environments:one:EndStartsOnOwnLine:3' -m
\end{commandshell}
	\label{page:yamlswitch}You%
	\announce{2017-08-21}{the -y switch} can specify YAML settings from the command line using the
	\texttt{-y} or \texttt{--yaml} switch;
	sample demonstrations are given above.	Note, in particular, that multiple settings can
	be specified by separating them via commas. There is a further option to use a
	\texttt{;} to separate fields, which is demonstrated in
	\vref{sec:yamlswitch}.

	Any settings specified via this switch will be loaded \emph{after} any
	specified using the \texttt{-l} switch. This is discussed further in
	\vref{sec:loadorder}.
\flagbox{-d, --onlydefault}
	\index{switches!-d, --onlydefault definition and details}
	\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} or
	\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; \texttt{latexindent.pl}%
	\announce{2017-08-21}*{updated -d switch} will also ignore any settings specified from the
	\texttt{-y} switch.

\flagbox{-c, --cruft=<directory>}
	\index{switches!-c, --cruft definition and details}
	\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. Note the use of a trailing forward slash. % 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=<name of log file>}
	\index{switches!-g, --logfile definition and details}
	\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.

	\announce{2021-05-07}{log file creation updated} If \texttt{latexindent.pl} can not open the log file that you
	specify, then the script will operate, and no log file will be produced; this might be
	helpful to users who wish to specify the following, for example
	\begin{commandshell}
latexindent.pl -g /dev/null myfile.tex
\end{commandshell}

\flagbox{-sl, --screenlog}
	\index{switches!-sl, --screenlog definition and details}
	\begin{commandshell}
latexindent.pl -sl myfile.tex
latexindent.pl -screenlog myfile.tex
\end{commandshell}
	Using this%
	\announce{2018-01-13}{screenlog switch created} option tells
	\texttt{latexindent.pl} to output the log file to the screen, as well as to your chosen
	log file.

\flagbox{-m, --modifylinebreaks}
	\index{switches!-m, --modifylinebreaks definition and details}
	\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.
\flagbox{STDIN}
	\begin{commandshell}
cat myfile.tex | latexindent.pl
cat myfile.tex | latexindent.pl -
\end{commandshell}
	\texttt{latexindent.pl} will%
	\announce{2018-01-13}{STDIN allowed} allow input from STDIN, which means that you can pipe output from
	other commands directly into the script. For example assuming that you have content in
	\texttt{myfile.tex}, then the above command will output the results of operating upon
	\texttt{myfile.tex}.

	If you wish to use this feature with your own local settings, via the
	\texttt{-l} switch, then you should finish your call to
	\texttt{latexindent.pl} with a \texttt{-} sign:
	\begin{commandshell}
cat myfile.tex | latexindent.pl -l=mysettings.yaml -
\end{commandshell}

	Similarly, if you%
	\announce{2018-01-13}*{no options/filename updated} simply type
	\texttt{latexindent.pl} at the command line, then it will expect (STDIN) input from the
	command line.
	\begin{commandshell}
latexindent.pl
\end{commandshell}

	Once you have finished typing your input, you can press
	\begin{itemize}
		\item \texttt{CTRL+D} on Linux
		\item \texttt{CTRL+Z} followed by \texttt{ENTER} on Windows
	\end{itemize}
	to signify that your input has finished. Thanks to \cite{xu-cheng} for an update
	to this feature.
\flagbox{-r, --replacement}
	\index{switches!-r, --replacement definition and details}
	\begin{commandshell}
latexindent.pl -r myfile.tex
latexindent.pl -replacement myfile.tex
\end{commandshell}
	You can%
	\announce{2019-07-13}{replacement mode switch} call
	\texttt{latexindent.pl} with the \texttt{-r} switch to instruct it to perform
	replacements/substitutions on your file; full details and examples are given in
	\vref{sec:replacements}.
	\index{verbatim!rv, replacementrespectverb switch}

\flagbox{-rv, --replacementrespectverb}
	\index{switches!-rv, --replacementrespectverb definition and details}
	\begin{commandshell}
latexindent.pl -rv myfile.tex
latexindent.pl -replacementrespectverb myfile.tex
\end{commandshell}
	You can%
	\announce{2019-07-13}{replacement mode switch, respecting verbatim} instruct
	\texttt{latexindent.pl} to perform replacements/substitutions by using the
	\texttt{-rv} switch, but will \emph{respect verbatim code blocks}; full details and
	examples are given in \vref{sec:replacements}.

\flagbox{-rr, --onlyreplacement}
	\index{switches!-rr, --onlyreplacement definition and details}
	\begin{commandshell}
latexindent.pl -rr myfile.tex
latexindent.pl -onlyreplacement myfile.tex
\end{commandshell}
	You can%
	\announce{2019-07-13}{replacement (only) mode switch} instruct
	\texttt{latexindent.pl} to skip all of its other indentation operations and
	\emph{only} perform replacements/substitutions by using the
	\texttt{-rr} switch; full details and examples are given in
	\vref{sec:replacements}.

\subsection{From 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}; you can find the arara rule for
	\texttt{latexindent.pl} and its associated documentation at \cite{paulo}.