3. How to use the script
latexindent.pl
ships as part of the TeXLive distribution for Linux and Mac users; latexindent.exe
ships as part of the TeXLive for Windows users. These files are also available from github (“Home of Latexindent.pl” n.d.) should you wish to use them without a TeX distribution; in this case, you may like to read Section 12.2 which details how the path
variable can be updated.
In what follows, we will always refer to latexindent.pl
, but depending on your operating system and preference, you might substitute latexindent.exe
or simply latexindent
.
There are two ways to use latexindent.pl
: from the command line, and using arara
; we discuss these in Section 3.2 and Section 3.3 respectively. We will discuss how to change the settings and behaviour of the script in Section 5.
3.1. Requirements
3.1.1. Perl users
Perl users will need a few standard Perl modules – see Section 12.1 for details; in particular, note that a module installer helper script is shipped with latexindent.pl
.
3.1.2. Windows users without perl
latexindent.pl
ships with latexindent.exe
for Windows users, so that you can use the script with or without a Perl distribution.
latexindent.exe
is available from (“Home of Latexindent.pl” n.d.).
MiKTeX users on Windows may like to see (“How to Use Latexindent on Windows?” n.d.) for details of how to use latexindent.exe
without a Perl installation.
3.1.3. Ubuntu Linux users without perl
latexindent.pl
ships with latexindent-linux
for Ubuntu Linux users, so that you can use the script with or without a Perl distribution.
latexindent-linux
is available from (“Home of Latexindent.pl” n.d.).
3.1.4. macOS users without perl
latexindent.pl
ships with latexindent-macos
for macOS users, so that you can use the script with or without a Perl distribution.
latexindent-macOS
is available from (“Home of Latexindent.pl” n.d.).
3.1.5. conda users
Users of conda
should see the details given in Section 12.5.
3.1.6. docker users
Users of docker
should see the details given in Section 12.6.
3.2. From the command line
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. latexindent.pl
produces a .log
file, 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 indent.log
throughout this document. There is a base of information that is written to indent.log
, but other additional information will be written depending on
which of the following options are used.
When using latexindent.pl
in different ways on different systems, the range of characters supported by its switches/flags/options may vary. We discuss these in Section Section 12.11.
- -v, –version
latexindent.pl -v
latexindent.pl --version
This will output only the version number to the terminal.
- -vv, –vversion
latexindent.pl -vv
latexindent.pl --vversion
This will output verbose version details to the terminal, including the location of latexindent.pl
and defaultSettings.yaml
.
- -h, –help
latexindent.pl -h
latexindent.pl --help
As above this will output a welcome message to the terminal, including the version number and available options.
latexindent.pl myfile.tex
This will operate on myfile.tex
, but will simply output to your terminal; myfile.tex
will not be changed by latexindent.pl
in any way using this command.
You can instruct latexindent.pl
to operate on multiple (batches) of files, for example
latexindent.pl myfile1.tex myfile2.tex
Full details are given in Section 12.3.
- -w, –overwrite
latexindent.pl -w myfile.tex
latexindent.pl --overwrite myfile.tex
latexindent.pl myfile.tex --overwrite
This will overwrite myfile.tex
, but it will make a copy of myfile.tex
first. You can control the name of the extension (default is .bak
), and how many different backups are made – more on this in Section 5, and in particular see backupExtension
and onlyOneBackUp
.
Note that if 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.
- -wd, –overwriteIfDifferent
latexindent.pl -wd myfile.tex
latexindent.pl --overwriteIfDifferent myfile.tex
latexindent.pl myfile.tex --overwriteIfDifferent
This will overwrite myfile.tex
but only if the indented text is different from the original. If the indented text is not different from the original, then myfile.tex
will not be overwritten.
All other details from the -w
switch are relevant here. If you call latexindent.pl
with both the -wd
and the -w
switch, then the -w
switch will be deactivated and the -wd
switch takes priority.
- -o=output.tex,–outputfile=output.tex
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
This will indent myfile.tex
and output it to output.tex
, overwriting it (output.tex
) if it already exists 1.
Note that if latexindent.pl
is called with both the -w
and -o
switches, then -w
will be ignored and -o
will take priority (this seems safer than the other way round). The same is true for the -wd
switch, and the -o
switch takes priority over it.
Note that using -o
as above is equivalent to using
latexindent.pl myfile.tex > output.tex
You can call the -o
switch with the name of the output file without an extension; in this case, latexindent.pl
will use the extension from the original file. For example, the following two calls to latexindent.pl
are equivalent:
latexindent.pl myfile.tex -o=output
latexindent.pl myfile.tex -o=output.tex
You can call the -o
switch using a +
symbol at the beginning; this will concatenate the name of the input file and the text given to the -o
switch. For example, the following two calls to latexindent.pl
are equivalent:
latexindent.pl myfile.tex -o=+new
latexindent.pl myfile.tex -o=myfilenew.tex
You can call the -o
switch using a ++
symbol at the end of the name of your output file; this tells 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,
latexindent.pl myfile.tex -o=output++
tells latexindent.pl
to output to output0.tex
, but if it exists then output to output1.tex
, and so on.
Calling latexindent.pl
with simply
latexindent.pl myfile.tex -o=++
tells it to output to myfile0.tex
, but if it exists then output to myfile1.tex
and so on.
The +
and ++
feature of the -o
switch can be combined; for example, calling
latexindent.pl myfile.tex -o=+out++
tells latexindent.pl
to output to myfileout0.tex
, but if it exists, then try myfileout1.tex
, and so on.
There is no need to specify a file extension when using the ++
feature, but if you wish to, then you should include it after the ++
symbols, for example
latexindent.pl myfile.tex -o=+out++.tex
See Section 12.13 for details of how the interface has changed from Version 2.2 to Version 3.0 for this flag. .. describe:: -s, –silent
latexindent.pl -s myfile.tex
latexindent.pl myfile.tex -s
Silent mode: no output will be given to the terminal.
- -t, –trace
latexindent.pl -t myfile.tex
latexindent.pl myfile.tex -t
Tracing mode: verbose output will be given to indent.log
. This is useful if latexindent.pl
has made a mistake and you’re trying to find out where and why. You might also be interested in learning about 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.
- -tt, –ttrace
latexindent.pl -tt myfile.tex
latexindent.pl myfile.tex -tt
More detailed tracing mode: this option gives more details to indent.log
than the standard trace
option (note that, even more so than with -t
, especially for large files, performance of the script will be affected).
- -l, –local[=myyaml.yaml,other.yaml,...]
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
latexindent.pl
will always load defaultSettings.yaml
(rhymes with camel) and if it is called with the -l
switch and it finds localSettings.yaml
in the same directory as myfile.tex
, then, if not found, it looks for localSettings.yaml
(and friends, see Section 4.2) in the current working directory, then these settings will be added to the indentation scheme. Information will be given in indent.log
on the success or failure of loading
localSettings.yaml
.
The -l
flag can take an optional parameter which details the name (or names separated by commas) of a YAML file(s) that resides in the same directory as myfile.tex
; you can use this option if you would like to load a settings file in the current working directory that is not called localSettings.yaml
. In fact, you can specify both relative and absolute paths for your YAML files; for example
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
You will find a lot of other explicit demonstrations of how to use the -l
switch throughout this documentation,
You can call the -l
switch with a ‘+’ symbol either before or after another YAML file; for example:
latexindent.pl -l=+myyaml.yaml myfile.tex
latexindent.pl -l "+ myyaml.yaml" myfile.tex
latexindent.pl -l=myyaml.yaml+ myfile.tex
which translate, respectively, to
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
Note that the following is not allowed:
latexindent.pl -l+myyaml.yaml myfile.tex
and
latexindent.pl -l + myyaml.yaml myfile.tex
will only load localSettings.yaml
, and 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 yaml
extension, such as
latexindent.pl -l=localSettings,myyaml myfile.tex
- -y, –yaml=yaml settings
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
You can specify YAML settings from the command line using the -y
or –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 ;
to separate fields, which is demonstrated in Section 4.3.
Any settings specified via this switch will be loaded after any specified using the -l
switch. This is discussed further in Section 4.4. .. describe:: -d, –onlydefault
latexindent.pl -d myfile.tex
Only defaultSettings.yaml
: you might like to read Section 5 before using this switch. By default, latexindent.pl
will always search for indentconfig.yaml
or .indentconfig.yaml
in your home directory. If you would prefer it not to do so then (instead of deleting or renaming indentconfig.yaml
or .indentconfig.yaml
) you can simply call the script with the -d
switch; note that this will also tell the script to ignore localSettings.yaml
even if it has
been called with the -l
switch; latexindent.pl
will also ignore any settings specified from the -y
switch.
- -c, –cruft=<directory>
latexindent.pl -c=/path/to/directory/ myfile.tex
If you wish to have backup files and 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.
If the cruft directory does not exist, latexindent.pl
will attempt to create it.
- -g, –logfile=<name of log file>
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
By default, latexindent.pl
reports information to indent.log
, but if you wish to change the name of this file, simply call the script with your chosen name after the -g
switch as demonstrated above.
If 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
latexindent.pl -g /dev/null myfile.tex
- -sl, –screenlog
latexindent.pl -sl myfile.tex
latexindent.pl -screenlog myfile.tex
Using this option tells latexindent.pl
to output the log file to the screen, as well as to your chosen log file.
- -m, –modifylinebreaks
latexindent.pl -m myfile.tex
latexindent.pl -modifylinebreaks myfile.tex
One of the most exciting developments in Version 3.0 is the ability to modify line breaks; for full details see Section 6
latexindent.pl
can also be called on a file without the file extension, for example
latexindent.pl myfile
and in which case, you can specify the order in which extensions are searched for; see Listing 49 for full details. .. describe:: STDIN
cat myfile.tex | latexindent.pl
cat myfile.tex | latexindent.pl -
latexindent.pl
will 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 myfile.tex
, then the above command will output the results of operating upon myfile.tex
.
If you wish to use this feature with your own local settings, via the -l
switch, then you should finish your call to latexindent.pl
with a -
sign:
cat myfile.tex | latexindent.pl -l=mysettings.yaml -
Similarly, if you simply type latexindent.pl
at the command line, then it will expect (STDIN) input from the command line.
latexindent.pl
Once you have finished typing your input, you can press
CTRL+D
on LinuxCTRL+Z
followed byENTER
on Windows
to signify that your input has finished. Thanks to ((xu-cheng) 2018) for an update to this feature. .. describe:: -r, –replacement
latexindent.pl -r myfile.tex
latexindent.pl -replacement myfile.tex
You can call latexindent.pl
with the -r
switch to instruct it to perform replacements/substitutions on your file; full details and examples are given in Section 7.
- -rv, –replacementrespectverb
latexindent.pl -rv myfile.tex
latexindent.pl -replacementrespectverb myfile.tex
You can instruct latexindent.pl
to perform replacements/substitutions by using the -rv
switch, but will respect verbatim code blocks; full details and examples are given in Section 7.
- -rr, –onlyreplacement
latexindent.pl -rr myfile.tex
latexindent.pl -onlyreplacement myfile.tex
You can instruct latexindent.pl
to skip all of its other indentation operations and only perform replacements/substitutions by using the -rr
switch; full details and examples are given in Section 7.
- -k, –check
latexindent.pl -k myfile.tex
latexindent.pl -check myfile.tex
You can instruct latexindent.pl
to check if the text after indentation matches that given in the original file.
The exit
code
of latexindent.pl
is 0 by default. If you use the -k
switch then
if the text after indentation matches that given in the original file, then the exit code is 0;
if the text after indentation does not match that given in the original file, then the exit code is 1.
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 latexindent.pl
are given in Table 1.
A simple diff
will be given in indent.log
.
- -kv, –checkv
latexindent.pl -kv myfile.tex
latexindent.pl -checkv myfile.tex
The check verbose
switch is exactly the same as the -k
switch, except that it is verbose, and it will output the (simple) diff to the terminal, as well as to indent.log
.
- -n, –lines=MIN-MAX
latexindent.pl -n 5-8 myfile.tex
latexindent.pl -lines 5-8 myfile.tex
The lines
switch instructs latexindent.pl
to operate only on specific line ranges within myfile.tex
.
Complete demonstrations are given in Section 8.
- –GCString
latexindent.pl --GCString myfile.tex
instructs latexindent.pl
to load the Unicode::GCString
module. This should only be necessary if you find that the alignment at ampersand routine (described in Section 5.5) does not work for your language. Further details are given in Section 12.1.6.
3.3. From arara
Using latexindent.pl
from the command line is fine for some folks, but others may find it easier to use from arara
; you can find the arara rule for latexindent.pl
and its associated documentation at (Cereda 2013).
3.4. Summary of exit codes
Assuming that you call latexindent.pl
on myfile.tex
latexindent.pl myfile.tex
then latexindent.pl
can exit with the exit codes given in Table 1.
exit code |
indentation |
status |
---|---|---|
0 |
yes |
success; if |
0 |
no |
success; if |
1 |
yes |
success, and |
2 |
no |
failure, |
3 |
no |
failure, myfile.tex not found |
4 |
no |
failure, myfile.tex exists but cannot be read |
5 |
no |
failure, |
6 |
no |
failure, |
Cereda, Paulo. 2013. “Arara Rule, Indent.yaml.” May 23, 2013. https://github.com/islandoftex/arara/blob/master/rules/arara-rule-indent.yaml.
“Home of Latexindent.pl.” n.d. Accessed January 23, 2017. https://github.com/cmhughes/latexindent.pl.
“How to Use Latexindent on Windows?” n.d. Accessed January 8, 2022. https://tex.stackexchange.com/questions/577250/how-to-use-latexindent-on-windows.
(xu-cheng), Cheng Xu. 2018. “Always Output Log/Help Text to Stderr.” July 13, 2018. https://github.com/cmhughes/latexindent.pl/pull/121.
- 1
Users of version 2.* should note the subtle change in syntax