diff options
Diffstat (limited to 'support/latexindent/documentation/sec-how-to-use.tex')
-rw-r--r-- | support/latexindent/documentation/sec-how-to-use.tex | 230 |
1 files changed, 111 insertions, 119 deletions
diff --git a/support/latexindent/documentation/sec-how-to-use.tex b/support/latexindent/documentation/sec-how-to-use.tex index ba35a04328..42553e037a 100644 --- a/support/latexindent/documentation/sec-how-to-use.tex +++ b/support/latexindent/documentation/sec-how-to-use.tex @@ -2,36 +2,36 @@ \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. + 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{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}. + 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. + \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} @@ -55,8 +55,8 @@ 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. + \texttt{myfile.tex} will not be changed by \texttt{latexindent.pl} in any way using this + command. \flagbox{-w, --overwrite} \index{switches!-w, --overwrite definition and details} @@ -86,44 +86,43 @@ 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). 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: + 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% + 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: + 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% + 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, + 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} @@ -137,17 +136,16 @@ latexindent.pl myfile.tex -o=++ 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 + 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 + 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} @@ -186,9 +184,8 @@ latexindent.pl myfile.tex -tt \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). + 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} @@ -202,29 +199,31 @@ 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{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 + 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: @@ -247,11 +246,12 @@ latexindent.pl -l+myyaml.yaml myfile.tex \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 + 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 @@ -268,31 +268,29 @@ latexindent.pl myfile.tex -y='modifyLineBreaks:environments:EndStartsOnOwnLine:3 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}. + \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} @@ -313,13 +311,13 @@ 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 + 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 + \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} @@ -331,9 +329,8 @@ 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. + \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} @@ -358,22 +355,20 @@ 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}. + \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: + 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. + \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} @@ -383,8 +378,8 @@ latexindent.pl \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. + 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} @@ -392,8 +387,8 @@ 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 + \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} @@ -405,10 +400,9 @@ 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}. + \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} @@ -417,11 +411,9 @@ 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}. + \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 |