From e0c6872cf40896c7be36b11dcc744620f10adf1d Mon Sep 17 00:00:00 2001
From: Norbert Preining <norbert@preining.info>
Date: Mon, 2 Sep 2019 13:46:59 +0900
Subject: Initial commit

---
 .../latexindent/documentation/sec-how-to-use.tex   | 391 +++++++++++++++++++++
 1 file changed, 391 insertions(+)
 create mode 100644 support/latexindent/documentation/sec-how-to-use.tex

(limited to 'support/latexindent/documentation/sec-how-to-use.tex')

diff --git a/support/latexindent/documentation/sec-how-to-use.tex b/support/latexindent/documentation/sec-how-to-use.tex
new file mode 100644
index 0000000000..bdae2b428e
--- /dev/null
+++ b/support/latexindent/documentation/sec-how-to-use.tex
@@ -0,0 +1,391 @@
+% 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}
+	\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}
+
+	\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} 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}
+	\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}.%
+	\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}
+	\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}
+	\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>}
+	\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=<name of log file>}
+	\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{-sl, --screenlog}
+	\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}
+	\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
+\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}
+
+	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}
+	\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}.
+
+\flagbox{-rv, --replacementrespectverb}
+	\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}
+	\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}.
-- 
cgit v1.2.3

