diff options
Diffstat (limited to 'support/latexindent/documentation/sec-how-to-use.tex')
| -rw-r--r-- | support/latexindent/documentation/sec-how-to-use.tex | 391 |
1 files changed, 391 insertions, 0 deletions
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}. |