diff options
Diffstat (limited to 'support/latexindent/documentation/sec-how-to-use.tex')
-rw-r--r-- | support/latexindent/documentation/sec-how-to-use.tex | 77 |
1 files changed, 77 insertions, 0 deletions
diff --git a/support/latexindent/documentation/sec-how-to-use.tex b/support/latexindent/documentation/sec-how-to-use.tex index 42553e037a..c297418928 100644 --- a/support/latexindent/documentation/sec-how-to-use.tex +++ b/support/latexindent/documentation/sec-how-to-use.tex @@ -415,7 +415,84 @@ latexindent.pl -onlyreplacement myfile.tex and \emph{only} perform replacements/substitutions by using the \texttt{-rr} switch; full details and examples are given in \vref{sec:replacements}. +\flagbox{-k, --check} + \index{switches!-k, --check definition and details} + \begin{commandshell} +latexindent.pl -k myfile.tex +latexindent.pl -check myfile.tex +\end{commandshell} + You can% + \announce*{2021-09-16}{-k,-check switch} instruct + \texttt{latexindent.pl} to check if the text after indentation matches that given in the + original file. + + The \texttt{exit} code + \index{exit code} of \texttt{latexindent.pl} is 0 by default. If + you use the \texttt{-k} switch then + \begin{itemize} + \item if the text after indentation matches that given in the original file, then the exit code + is 0; + \item if the text after indentation does \emph{not} match that given in the original file, then + the exit code is 1. + \end{itemize} + + The value of the exit code may be important to those wishing to, for example, check the + status of the indentation in continuous integration tools such as GitHub Actions. Full + details of the exit codes of \texttt{latexindent.pl} are given in \cref{tab:exit-codes}. + + A simple \texttt{diff} will be given in \texttt{indent.log}. + +\flagbox{-kv, --checkv} + \index{switches!-kv, --checkv definition and details} + \begin{commandshell} +latexindent.pl -kv myfile.tex +latexindent.pl -checkv myfile.tex +\end{commandshell} + \announce*{2021-09-16}{-kv, -checkv: check verbose switch} The \texttt{check verbose} switch is + exactly the same as the \texttt{-k} switch, except that it is \emph{verbose}, and it will + output the (simple) diff to the terminal, as well as to \texttt{indent.log}. + +\flagbox{-n, --lines=MIN-MAX} + \index{switches!-n, --lines definition and details} + \begin{commandshell} +latexindent.pl -n 5-8 myfile.tex +latexindent.pl -lines 5-8 myfile.tex +\end{commandshell} + \announce*{2021-09-16}{-n, -lines switch} The \texttt{lines} switch instructs + \texttt{latexindent.pl} to operate only on specific line ranges within + \texttt{myfile.tex}. + + Complete demonstrations are given in \cref{sec:line-switch}. + \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}. + +\subsection{Summary of exit codes} + \index{exit code!summary} + Assuming that you call \texttt{latexindent.pl} on \texttt{myfile.tex} + \begin{commandshell} +latexindent.pl myfile.tex +\end{commandshell} + then \texttt{latexindent.pl} can exit with the exit codes given in \cref{tab:exit-codes}. + + \begin{table}[!htb] + \caption{Exit codes for \texttt{latexindent.pl}} + \label{tab:exit-codes} + \begin{tabular}{ccl} + \toprule + exit code & indentation & status \\ + \midrule + 0 & \faCheck & success; if \texttt{-k} or \texttt{-kv} active, indented text matches original \\ + 0 & \faClose & success; if \texttt{-version} or \texttt{-help}, no indentation performed \\ + 1 & \faCheck & success, and \texttt{-k} or \texttt{-kv} active; indented text \emph{different} from original \\ + \midrule + 2 & \faClose & failure, \texttt{defaultSettings.yaml} could not be read \\ + 3 & \faClose & failure, myfile.tex not found \\ + 4 & \faClose & failure, myfile.tex exists but cannot be read \\ + 5 & \faClose & failure, \texttt{-w} active, and back-up file cannot be written \\ + 6 & \faClose & failure, \texttt{-c} active, and cruft directory does not exist \\ + \bottomrule + \end{tabular} + \end{table} |