summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/doc/support/latexindent/sec-how-to-use.tex
diff options
context:
space:
mode:
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.tex110
1 files changed, 71 insertions, 39 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 6a5aa290ca0..bdae2b428e4 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
@@ -27,42 +27,41 @@
\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 customized,
- 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}
\announce{2017-06-25}{version}
\begin{commandshell}
latexindent.pl -v
- \end{commandshell}
+\end{commandshell}
This will output only the version number to the terminal.
\flagbox{-h, --help}
\begin{commandshell}
latexindent.pl -h
- \end{commandshell}
+\end{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}
+\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}
\begin{commandshell}
latexindent.pl -w myfile.tex
latexindent.pl --overwrite myfile.tex
latexindent.pl myfile.tex --overwrite
- \end{commandshell}
+\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
@@ -80,7 +79,7 @@ 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}
+\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
@@ -105,7 +104,7 @@ 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%%%
+ 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:
@@ -115,7 +114,7 @@ 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%%%
+ 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
@@ -154,7 +153,7 @@ latexindent.pl myfile.tex -o=+out++.tex
\begin{commandshell}
latexindent.pl -s myfile.tex
latexindent.pl myfile.tex -s
- \end{commandshell}
+\end{commandshell}
Silent mode: no output will be given to the terminal.
@@ -162,7 +161,7 @@ latexindent.pl myfile.tex -s
\begin{commandshell}
latexindent.pl -t myfile.tex
latexindent.pl myfile.tex -t
- \end{commandshell}
+\end{commandshell}
\label{page:traceswitch}
Tracing mode: verbose output will be given to \texttt{indent.log}. This is useful if
@@ -175,7 +174,7 @@ latexindent.pl myfile.tex -t
\begin{commandshell}
latexindent.pl -tt myfile.tex
latexindent.pl myfile.tex -tt
- \end{commandshell}
+\end{commandshell}
\emph{More detailed} tracing mode: this option gives more details to
\texttt{indent.log}
@@ -191,7 +190,7 @@ latexindent.pl -l myyaml.yaml myfile.tex
latexindent.pl -l first.yaml,second.yaml,third.yaml myfile.tex
latexindent.pl -l=first.yaml,second.yaml,third.yaml myfile.tex
latexindent.pl myfile.tex -l=first.yaml,second.yaml,third.yaml
- \end{commandshell}
+\end{commandshell}
\label{page:localswitch}
\texttt{latexindent.pl} will always load \texttt{defaultSettings.yaml} (rhymes with camel)
@@ -204,7 +203,7 @@ latexindent.pl myfile.tex -l=first.yaml,second.yaml,third.yaml
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}.%%%
+ 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
@@ -212,31 +211,31 @@ latexindent.pl myfile.tex -l=first.yaml,second.yaml,third.yaml
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}
+\end{commandshell}
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}
-latexindent.pl -l=+myyaml.yaml myfile.tex
+latexindent.pl -l=+myyaml.yaml myfile.tex
latexindent.pl -l "+ myyaml.yaml" myfile.tex
latexindent.pl -l=myyaml.yaml+ myfile.tex
- \end{commandshell}
+\end{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}
+\end{commandshell}
Note that the following is \emph{not} allowed:
\begin{commandshell}
latexindent.pl -l+myyaml.yaml myfile.tex
- \end{commandshell}
+\end{commandshell}
and
\begin{commandshell}
latexindent.pl -l + myyaml.yaml myfile.tex
- \end{commandshell}
+\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.
@@ -245,7 +244,7 @@ latexindent.pl -l + myyaml.yaml myfile.tex
\announce{2017-06-25}{no extension for -l switch}
\begin{commandshell}
latexindent.pl -l=localSettings,myyaml myfile.tex
- \end{commandshell}
+\end{commandshell}
\flagbox{-y, --yaml=yaml settings}
\begin{commandshell}
latexindent.pl myfile.tex -y="defaultIndent: ' '"
@@ -253,7 +252,7 @@ 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}
+\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;
@@ -268,11 +267,11 @@ latexindent.pl myfile.tex -y='modifyLineBreaks:environments:one:EndStartsOnOwnLi
\flagbox{-d, --onlydefault}
\begin{commandshell}
latexindent.pl -d myfile.tex
- \end{commandshell}
+\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
+ \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
@@ -283,7 +282,7 @@ latexindent.pl -d myfile.tex
\flagbox{-c, --cruft=<directory>}
\begin{commandshell}
latexindent.pl -c=/path/to/directory/ myfile.tex
- \end{commandshell}
+\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
@@ -295,7 +294,7 @@ 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}
+\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
@@ -305,8 +304,8 @@ latexindent.pl myfile.tex -g other.log
\begin{commandshell}
latexindent.pl -sl myfile.tex
latexindent.pl -screenlog myfile.tex
- \end{commandshell}
- Using this%%%%
+\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.
@@ -315,7 +314,7 @@ latexindent.pl -screenlog myfile.tex
\begin{commandshell}
latexindent.pl -m myfile.tex
latexindent.pl -modifylinebreaks myfile.tex
- \end{commandshell}
+\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}
@@ -324,26 +323,26 @@ latexindent.pl -modifylinebreaks myfile.tex
example
\begin{commandshell}
latexindent.pl myfile
- \end{commandshell}
+\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}
cat myfile.tex | latexindent.pl
- \end{commandshell}
+\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}
- Similarly, if you%%%%
+ 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}
+\end{commandshell}
Once you have finished typing your input, you can press
\begin{itemize}
@@ -352,6 +351,39 @@ latexindent.pl
\end{itemize}
to signify that your input has finished. Thanks to \cite{xu-cheng} for an update
to this feature.
+\flagbox{-r, --replacement}
+ \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}.
+
+\flagbox{-rv, --replacementrespectverb}
+ \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}.
+
+\flagbox{-rr, --onlyreplacement}
+ \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}.
\subsection{From arara}\label{sec:arara}
Using \texttt{latexindent.pl} from the command line is fine for some folks, but others