1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
|
% arara: pdflatex: {shell: yes, files: [latexindent]}
\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.
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{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.
As you read through this documentation, you'll occasionally see dates shown in the margin
(for example, next to this paragraph!)
\announce{2017-06-25} which detail the date of the version in which the feature was implemented;
the `N' stands for `new as of the date shown'. If you see a $\color{cmhgold}\bigstar$, it
means that the feature is new as of the release of the current version.
\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.
\begin{commandshell}
latexindent.pl
\end{commandshell}
This will output a welcome message to the terminal, including the version number
and available options.
\flagbox{-v, --version}
\announce{2017-06-25}
\begin{commandshell}
latexindent.pl -v
\end{commandshell}
This will output only the version number to the terminal.
\flagbox{-h, --help}
\begin{commandshell}
latexindent.pl -h
\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}
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.
\flagbox{-w, --overwrite}
\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}.
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{-o=output.tex,--outputfile=output.tex}
\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).
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}
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}
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}
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.
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.
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.
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}
\begin{commandshell}
latexindent.pl -s myfile.tex
latexindent.pl myfile.tex -s
\end{commandshell}
Silent mode: no output will be given to the terminal.
\flagbox{-t, --trace}
\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.
\flagbox{-tt, --ttrace}
\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).
\flagbox{-l, --local[=myyaml.yaml,other.yaml,...]}
\begin{commandshell}
latexindent.pl -l myfile.tex
latexindent.pl -l=myyaml.yaml myfile.tex
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}
\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 these 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}.
In fact, you can specify \emph{relative} path names to the current directory, but \emph{not}
absolute paths -- for absolute paths, see \vref{sec:indentconfig}.
Explicit demonstrations of how to use the \texttt{-l} switch are given throughout this documentation.
You can call the \texttt{-l} switch with a `+' symbol either before or after
\announce{2017-06-25}
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}
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}
latexindent.pl -l+myyaml.yaml myfile.tex
\end{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.
You may also choose to omit the \texttt{yaml} extension, such as
\announce{2017-06-25}
\begin{commandshell}
latexindent.pl -l=localSettings,myyaml myfile.tex
\end{commandshell}
\flagbox{-d, --onlydefault}
\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}/\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.
\flagbox{-c, --cruft=<directory>}
\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.
% 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}
\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.
\flagbox{-m, --modifylinebreaks}
\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}
\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.
\subsection{From \texttt{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 at \cite{paulo}.
You can use the rule in any of the ways described in \cref{lst:arara} (or combinations thereof).
In fact, \texttt{arara} allows yet greater flexibility -- you can use \texttt{yes/no}, \texttt{true/false}, or \texttt{on/off} to toggle the various options.
\begin{cmhlistings}[style=demo,escapeinside={(*@}{@*)}]{\texttt{arara} sample usage}{lst:arara}
%(*@@*) arara: indent
%(*@@*) arara: indent: {overwrite: yes}
%(*@@*) arara: indent: {output: myfile.tex}
%(*@@*) arara: indent: {silent: yes}
%(*@@*) arara: indent: {trace: yes}
%(*@@*) arara: indent: {localSettings: yes}
%(*@@*) arara: indent: {onlyDefault: on}
%(*@@*) arara: indent: { cruft: /home/cmhughes/Desktop }
\documentclass{article}
...
\end{cmhlistings}
%(*@@*) arara: indent: { modifylinebreaks: yes }
Hopefully the use of these rules is fairly self-explanatory, but for completeness
\cref{tab:orbsandswitches} shows the relationship between \texttt{arara} directive arguments and the
switches given in \cref{sec:commandline}.
\begin{table}[!ht]
\centering
\caption{\texttt{arara} directive arguments and corresponding switches}
\label{tab:orbsandswitches}
\begin{tabular}{lc}
\toprule
\texttt{arara} directive argument & switch \\
\midrule
\texttt{overwrite} & \texttt{-w} \\
\texttt{output} & \texttt{-o} \\
\texttt{silent} & \texttt{-s} \\
\texttt{trace} & \texttt{-t} \\
\texttt{localSettings} & \texttt{-l} \\
\texttt{onlyDefault} & \texttt{-d} \\
\texttt{cruft} & \texttt{-c} \\
%\texttt{modifylinebreaks} & \texttt{-m} \\
\bottomrule
\end{tabular}
\end{table}
The \texttt{cruft} directive does not work well when used with
directories that contain spaces.
|