summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/doc/support/latexindent/sec-how-to-use.tex
blob: c8db5d20d1c51fe08ac622bbbe1e8caae787a945 (plain)
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
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
% arara: pdflatex: { files: [latexindent]}
\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
 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.
 \index{TeXLive}

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

\subsection{Requirements}
\subsubsection{Perl users}
 Perl users 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}.%

\subsubsection{Windows users without perl}\label{subsubsec:latexindent:exe}
 \texttt{latexindent.pl} ships with \texttt{latexindent.exe} for Windows
 users, so that you can use the script with or without a Perl distribution.

 Users of \texttt{latexindent.exe} need only two files: \texttt{latexindent.exe} and
 \texttt{defaultSettings.yaml}, both of which are available from \cite{latexindent-home}.

 MiKTeX users on Windows may like to see \cite{miktex-guide} for details of how to use
 \texttt{latexindent.exe} without a Perl installation. \index{MiKTeX}
 \index{latexindent.exe} \index{Windows}

\subsubsection{conda users}
 Users of \texttt{conda} should see the details given in \cref{sec:app:conda}.

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

\flagbox{-v, --version}
 \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.

\flagbox{-vv, --vversion}
 \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}.

\flagbox{-h, --help}
 \index{switches!-h, --help definition and details}

 \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}
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.

 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}
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{-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}

 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} 
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). 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}
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}
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}
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}
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} \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.

\flagbox{-t, --trace}
 \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.

\flagbox{-tt, --ttrace}
 \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).

\flagbox{-l, --local[=myyaml.yaml,other.yaml,...]}
 \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
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, 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 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}
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. 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}
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}
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}
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.%

\flagbox{-c, --cruft=<directory>}
 \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

\flagbox{-g, --logfile=<name of log file>}
 \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.

 \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}
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.%

\flagbox{-m, --modifylinebreaks}
 \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}

 \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}
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}.

 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}
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}
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}%

\flagbox{-rv, --replacementrespectverb}
 \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}.%

\flagbox{-rr, --onlyreplacement}
 \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}.%

\flagbox{-k, --check}
 \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.%

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

 A simple \texttt{diff} will be given in \texttt{indent.log}.

\flagbox{-kv, --checkv}
 \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}.

\flagbox{-n, --lines=MIN-MAX}
 \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}.

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

\subsection{Summary of exit codes}
 \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}