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.tex230
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