diff options
Diffstat (limited to 'Master/texmf-dist/doc/support/latexindent/sec-how-to-use.tex')
-rw-r--r-- | Master/texmf-dist/doc/support/latexindent/sec-how-to-use.tex | 587 |
1 files changed, 312 insertions, 275 deletions
diff --git a/Master/texmf-dist/doc/support/latexindent/sec-how-to-use.tex b/Master/texmf-dist/doc/support/latexindent/sec-how-to-use.tex index 944a38292c1..9faa4112654 100644 --- a/Master/texmf-dist/doc/support/latexindent/sec-how-to-use.tex +++ b/Master/texmf-dist/doc/support/latexindent/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 @@ -29,178 +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} +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} - \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. + +\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} - 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. + 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} + \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}. 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). + 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 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 @@ -209,291 +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} +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 - \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} |