1. Introduction

1.1. License

latexindent.pl is free and open source, and it always will be; it is released under the GNU General Public License v3.0.

Before you start using it on any important files, bear in mind that latexindent.pl has the option to overwrite your .tex files. It will always make at least one backup (you can choose how many it makes, see page page:onlyonebackup) but you should still be careful when using it. The script has been tested on many files, but there are some known limitations (see Section 8). You, the user, are responsible for ensuring that you maintain backups of your files before running latexindent.pl on them. I think it is important at this stage to restate an important part of the license here:

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

There is certainly no malicious intent in releasing this script, and I do hope that it works as you expect it to; if it does not, please first of all make sure that you have the correct settings, and then feel free to let me know at (“Home of Latexindent.pl” n.d.) with a complete minimum working example as I would like to improve the code as much as possible.

Warning

Before you try the script on anything important (like your thesis), test it out on the sample files in the test-case directory (“Home of Latexindent.pl” n.d.).

1.2. Quick start

When latexindent.pl reads and writes files, the files are read and written in UTF-8 format by default. That is to say, the encoding format for tex and yaml files needs to be in UTF-8 format.

If you’d like to get started with latexindent.pl then simply type

latexindent.pl myfile.tex

from the command line.

We give an introduction to latexindent.pl using Listing 1; there is no explanation in this section, which is deliberate for a quick start. The rest of the manual is more verbose.

Listing 1 quick-start.tex
\documentclass{article}
\usepackage[
inner=2.5cm,
]{geometry}
\begin{document}
A quick start 
    demonstration for latexindent.pl.
    \begin{myenv}
      The body of environments and 
      other code blocks
        receive indentation.
    \end{myenv}
\end{document}

Running

latexindent.pl quick-start.tex

gives Listing 2.

Listing 2 quick-start-default.tex
\documentclass{article}
\usepackage[
inner=2.5cm,
]{geometry}
\begin{document}
A quick start
demonstration for latexindent.pl.
\begin{myenv}
	The body of environments and
	other code blocks
	receive indentation.
\end{myenv}
\end{document}
Example 1

Running

latexindent.pl -l quick-start1.yaml quick-start.tex

gives Listing 3.

Listing 3 quick-start-mod1.tex
\documentclass{article}
\usepackage[
inner=2.5cm,
]{geometry}
\begin{document}
A quick start
demonstration for latexindent.pl.
\begin{myenv}
 The body of environments and
 other code blocks
 receive indentation.
\end{myenv}
\end{document}
Listing 4 quick-start1.yaml
defaultIndent: " "

See Section 3.4.

Example 2

Running

latexindent.pl -l quick-start2.yaml quick-start.tex

gives Listing 5.

Listing 5 quick-start-mod2.tex
\documentclass{article}
\usepackage[
inner=2.5cm,
]{geometry}
\begin{document}
A quick start
demonstration for latexindent.pl.
\begin{myenv}
   The body of environments and
   other code blocks
   receive indentation.
\end{myenv}
\end{document}
Listing 6 quick-start2.yaml
indentRules:
  myenv: "   "

See Section 3.9.

Example 3

Running

latexindent.pl -l quick-start3.yaml quick-start.tex

gives Listing 7.

Listing 7 quick-start-mod3.tex
\documentclass{article}
\usepackage[
inner=2.5cm,
]{geometry}
\begin{document}
A quick start
demonstration for latexindent.pl.
\begin{myenv}
The body of environments and
other code blocks
receive indentation.
\end{myenv}
\end{document}
Listing 8 quick-start3.yaml
noAdditionalIndent:
  myenv: 1

See Section 3.9.

Example 4

Running

latexindent.pl -m -l quick-start4.yaml quick-start.tex

gives Listing 9.

Listing 9 quick-start-mod4.tex
\documentclass{article}
\usepackage[
inner=2.5cm,
]{geometry}
\begin{document}
A quick start
demonstration for latexindent.pl.
\begin{myenv}
	The body of environments and
	other code blocks
	receive indentation.
\end{myenv}
\end{document}
Listing 10 quick-start4.yaml
modifyLineBreaks:
    textWrapOptions:
        columns: 20

Full details of text wrapping in Section 4.1.

Example 5

Running

latexindent.pl -m -l quick-start5.yaml quick-start.tex

gives Listing 11.

Listing 11 quick-start-mod5.tex
\documentclass{article}
\usepackage[
inner=2.5cm,
]{geometry}
\begin{document}
A quick start
demonstration for latexindent.pl.
\begin{myenv}
	The body of
	environments and
	other code blocks
	receive
	indentation.
\end{myenv}
\end{document}
Listing 12 quick-start5.yaml
modifyLineBreaks:
    textWrapOptions:
        columns: 20
        blocksFollow:
           other: '\\begin\{myenv\}'

Full details of text wrapping in Section 4.1.

Example 6

Running

latexindent.pl -m -l quick-start6.yaml quick-start.tex

gives Listing 13.

Listing 13 quick-start-mod6.tex
\documentclass{article}
\usepackage[
inner=2.5cm,
]{geometry}\begin{document}
A quick start
demonstration for latexindent.pl.\begin{myenv}
	The body of environments and
	other code blocks
	receive indentation.
\end{myenv}
\end{document}
Listing 14 quick-start6.yaml
modifyLineBreaks:
    environments:
        BeginStartsOnOwnLine: -1

This is an example of a poly-switch; full details of poly-switches are covered in Section 4.3.

Example 7

Running

latexindent.pl -m -l quick-start7.yaml quick-start.tex

gives Listing 15.

Listing 15 quick-start-mod7.tex
\documentclass{article}
\usepackage[
inner=2.5cm,
]{geometry}
\begin{document}
A quick start
demonstration for latexindent.pl.
\begin{myenv}
	The body of environments and
	other code blocks
	receive indentation.\end{myenv}\end{document}
Listing 16 quick-start7.yaml
modifyLineBreaks:
    environments:
        EndStartsOnOwnLine: -1

Full details of poly-switches are covered in Section 4.3.

Example 8

Running

latexindent.pl -l quick-start8.yaml quick-start.tex

gives Listing 17; note that the preamble has been indented.

Listing 17 quick-start-mod8.tex
\documentclass{article}
\usepackage[
	inner=2.5cm,
]{geometry}
\begin{document}
A quick start
demonstration for latexindent.pl.
\begin{myenv}
	The body of environments and
	other code blocks
	receive indentation.
\end{myenv}
\end{document}
Listing 18 quick-start8.yaml
indentPreamble: 1

See Section 3.3.

Example 9

Running

latexindent.pl -l quick-start9.yaml quick-start.tex

gives Listing 19.

Listing 19 quick-start-mod9.tex
\documentclass{article}
\usepackage[
inner=2.5cm,
]{geometry}
\begin{document}
	A quick start
	demonstration for latexindent.pl.
	\begin{myenv}
		The body of environments and
		other code blocks
		receive indentation.
	\end{myenv}
\end{document}
Listing 20 quick-start9.yaml
noAdditionalIndent:
  document: 0

See Section 3.9.

1.3. Requirements

1.3.1. Perl users

Perl users will need a few standard Perl modules – see Section 10.1 for details; in particular, note that a module installer helper script is shipped with latexindent.pl. You might also like to see https://stackoverflow.com/questions/19590042/error-cant-locate-file-homedir-pm-in-inc.

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

1.3.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.).

1.3.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.).

1.3.5. conda users

Users of conda should see the details given in Section 10.5.

1.3.6. docker users

Users of docker should see the details given in Section 10.6.

1.4. About this documentation

As you read through this documentation, you will see many listings; in this version of the documentation, there are a total of 596. This may seem a lot, but I deem it necessary in presenting the various different options of latexindent.pl and the associated output that they are capable of producing.

The different listings are presented using different styles:

Listing 21 demo-tex.tex
demonstration .tex file

This type of listing is a .tex file.

Listing 22 fileExtensionPreference
31fileExtensionPreference:
32  .tex: 1
33  .sty: 2
34  .cls: 3
35  .bib: 4

This type of listing is a .yaml file; when you see line numbers given (as here) it means that the snippet is taken directly from defaultSettings.yaml, discussed in detail in Section 3.

Listing 23 modifyLineBreaks
289modifyLineBreaks:
290  preserveBlankLines: 1                 # 0/1
291  condenseMultipleBlankLinesInto: 1     # 0/1

This type of listing is a .yaml file, but it will only be relevant when the -m switch is active; see Section 4 for more details.

Listing 24 replacements
419replacements:
420  - amalgamate: 1
421  - this: latexindent.pl
422    that: pl.latexindent
423    lookForThis: 0
424    when: before

This type of listing is a .yaml file, but it will only be relevant when the -r switch is active; see Section 5 for more details.

1.5. A word about regular expressions

As you read this documentation, you may encounter the term regular expressions. I’ve tried to write this documentation in such a way so as to allow you to engage with them or not, as you prefer. This documentation is not designed to be a guide to regular expressions, and if you’d like to read about them, I recommend (Friedl, n.d.).

Friedl, Jeffrey E. F. n.d. Mastering Regular Expressions.

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