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.tex591
1 files changed, 295 insertions, 296 deletions
diff --git a/support/latexindent/documentation/sec-how-to-use.tex b/support/latexindent/documentation/sec-how-to-use.tex
index 2ff75c8b1f..9faa411265 100644
--- a/support/latexindent/documentation/sec-how-to-use.tex
+++ b/support/latexindent/documentation/sec-how-to-use.tex
@@ -29,206 +29,206 @@
\index{latexindent.exe}
\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.
+ \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}
+ \index{switches!-v, --version definition and details}
+ \announce{2017-06-25}{version}
+ \begin{commandshell}
latexindent.pl -v
latexindent.pl --version
\end{commandshell}
- This will output only the version number to the terminal.
+ This will output only the version number to the terminal.
\flagbox{-vv, --vversion}
- \index{switches!-vv, --vversion definition and details}
- \announce{2022-01-08}{vversion switch}
- \begin{commandshell}
+ \index{switches!-vv, --vversion definition and details}
+ \announce{2022-01-08}{vversion switch}
+ \begin{commandshell}
latexindent.pl -vv
latexindent.pl --vversion
\end{commandshell}
- This will output \emph{verbose} version details to the terminal, including the location
- of \texttt{latexindent.pl} and \texttt{defaultSettings.yaml}.
+ This will output \emph{verbose} version details to the terminal, including the location
+ of \texttt{latexindent.pl} and \texttt{defaultSettings.yaml}.
\flagbox{-h, --help}
- \index{switches!-h, --help definition and details}
+ \index{switches!-h, --help definition and details}
- \begin{commandshell}
+ \begin{commandshell}
latexindent.pl -h
latexindent.pl --help
\end{commandshell}
- As above this will output a welcome message to the terminal, including the version number
- and available options.
- \begin{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.
+ 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.
- 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}
+ 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}.
+ Full details are given in \vref{sec:batches}.
\flagbox{-w, --overwrite}
- \index{switches!-w, --overwrite definition and details}
- \index{backup files!overwrite switch, -w}
- \begin{commandshell}
+ \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}.
+ 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.
+ 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{-wd, --overwriteIfDifferent}
- \index{switches!-wd, --overwriteIfDifferent definition and details}
- \index{backup files!overwriteIfDifferent switch, -wd}
- \announce*{2022-03-25}{overwriteIfDifferent switch}
- \begin{commandshell}
+ \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.
+ 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.
+ 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}
+ \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}.
+ 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). The same is true for the \texttt{-wd} switch, and the
- \texttt{-o} switch takes priority over it.
+ 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}
+ 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}
+ 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}
+ 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}
+ 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.
+ 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}
+ 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.
+ 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}
+ 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.
+ 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}
+ 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}
+ 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.
+ Silent mode: no output will be given to the terminal.
\flagbox{-t, --trace}
- \index{switches!-t, --trace definition and details}
- \begin{commandshell}
+ \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.
+ \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}
+ \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).
+ \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}
+ \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
@@ -237,301 +237,300 @@ 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}
+ \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 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}
+ 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}
+ 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}
+ Note that the following is \emph{not} allowed:
+ \begin{commandshell}
latexindent.pl -l+myyaml.yaml myfile.tex
\end{commandshell}
- and
- \begin{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.
+ 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}
+ 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}
+ \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}
+ \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.%
+ 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}
+ \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
+ 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}
+ \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.
+ 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}
+ \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}
+ \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.%
+ 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}
+ \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}
+ 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}
+ \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}
+ 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}.
+ \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}
+ 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}
+ 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}
+ 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}%
+ 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}
+ \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}.%
+ 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}
+ \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}.%
+ 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}.%
\flagbox{-k, --check}
- \index{switches!-k, --check definition and details}
- \begin{commandshell}
+ \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.%
+ 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 \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}.
+ 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}.
+ A simple \texttt{diff} will be given in \texttt{indent.log}.
\flagbox{-kv, --checkv}
- \index{switches!-kv, --checkv definition and details}
- \begin{commandshell}
+ \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}.
+ \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}
+ \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}.
+ \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}.
+ Complete demonstrations are given in \cref{sec:line-switch}.
\flagbox{--GCString}
- \index{switches!--GCString}
- \begin{commandshell}
+ \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}.
+ \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
- \texttt{latexindent.pl} and its associated documentation at \cite{paulo}.
+ 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}
+ \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}, \texttt{-vversion} 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}
+ 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}, \texttt{-vversion} 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}