summaryrefslogtreecommitdiff
path: root/support/latexindent/documentation/sec-how-to-use.tex
diff options
context:
space:
mode:
Diffstat (limited to 'support/latexindent/documentation/sec-how-to-use.tex')
-rw-r--r--support/latexindent/documentation/sec-how-to-use.tex48
1 files changed, 43 insertions, 5 deletions
diff --git a/support/latexindent/documentation/sec-how-to-use.tex b/support/latexindent/documentation/sec-how-to-use.tex
index 944a38292c..2ff75c8b1f 100644
--- a/support/latexindent/documentation/sec-how-to-use.tex
+++ b/support/latexindent/documentation/sec-how-to-use.tex
@@ -1,5 +1,5 @@
% arara: pdflatex: { files: [latexindent]}
-\section{How to use the script}
+\section{How to use the script}\label{sec:how:to:use}
\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 for Windows
users. These files are also available from github \cite{latexindent-home} should you wish
@@ -48,7 +48,7 @@ latexindent.pl --version
\flagbox{-vv, --vversion}
\index{switches!-vv, --vversion definition and details}
- \announce*{2022-01-08}{vversion switch}
+ \announce{2022-01-08}{vversion switch}
\begin{commandshell}
latexindent.pl -vv
latexindent.pl --vversion
@@ -74,6 +74,13 @@ latexindent.pl myfile.tex
\texttt{myfile.tex} will not be changed by \texttt{latexindent.pl} in any way using this
command.
+ You can \announce*{2022-03-25}{batches of files demonstration} instruct
+ \texttt{latexindent.pl} to operate on multiple (batches) of files, for example
+ \begin{commandshell}
+latexindent.pl myfile1.tex myfile2.tex
+\end{commandshell}
+ Full details are given in \vref{sec:batches}.
+
\flagbox{-w, --overwrite}
\index{switches!-w, --overwrite definition and details}
\index{backup files!overwrite switch, -w}
@@ -93,6 +100,24 @@ latexindent.pl myfile.tex --overwrite
touching your original file; an error message will be given asking you to check the
permissions of the backup file.
+\flagbox{-wd, --overwriteIfDifferent}
+ \index{switches!-wd, --overwriteIfDifferent definition and details}
+ \index{backup files!overwriteIfDifferent switch, -wd}
+ \announce*{2022-03-25}{overwriteIfDifferent switch}
+ \begin{commandshell}
+latexindent.pl -wd myfile.tex
+latexindent.pl --overwriteIfDifferent myfile.tex
+latexindent.pl myfile.tex --overwriteIfDifferent
+\end{commandshell}
+
+ This \emph{will} overwrite \texttt{myfile.tex} but only \emph{if the indented text is
+ different from the original}. If the indented text is \emph{not} different from the
+ original, then \texttt{myfile.tex} will \emph{not} be overwritten.
+
+ All other details from the \texttt{-w} switch are relevant here. If you call
+ \texttt{latexindent.pl} with both the \texttt{-wd} and the \texttt{-w} switch, then the
+ \texttt{-w} switch will be deactivated and the \texttt{-wd} switch takes priority.
+
\flagbox{-o=output.tex,--outputfile=output.tex}
\index{switches!-o, --output definition and details}
\begin{commandshell}
@@ -104,9 +129,12 @@ latexindent.pl --outputfile output.tex myfile.tex
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).
+ 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). The same is true for the \texttt{-wd} switch, and the
+ \texttt{-o} switch takes priority over it.
Note that using \texttt{-o} as above is equivalent to using
\begin{commandshell}
@@ -465,6 +493,16 @@ latexindent.pl -lines 5-8 myfile.tex
Complete demonstrations are given in \cref{sec:line-switch}.
+\flagbox{--GCString}
+ \index{switches!--GCString}
+ \begin{commandshell}
+latexindent.pl --GCString myfile.tex
+\end{commandshell}
+ \announce*{2022-03-25}{GCString switch} instructs \texttt{latexindent.pl} to load the
+ \texttt{Unicode::GCString} module. This should only be necessary if you find that the
+ alignment at ampersand routine (described in \cref{subsec:align-at-delimiters}) does not
+ work for your language. Further details are given in \cref{subsec:the-GCString}.
+
\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