latexindent.pl

latexindent.pl is a perl script to indent (add horizontal leading space to)code within environments, commands, after headings and within special code blocks.

It has the ability to align delimiters in environments and commands, andcan modify line breaks.

version

latexindent.pl, version 3.12, 2021-09-16

author

Chris Hughes (cmhughes)

example

A simple example follows; there are many more features available, detailed in full within the documentation.

Before:

\begin{one}
latexindent.pl adds leading
space to code blocks. 
\begin{two}
It aims to beautify .tex, .sty
and .cls files. It is customisable
via its YAML interface.
\end{two}
\end{one}

After:

\begin{one}
	latexindent.pl adds leading
	space to code blocks.
	\begin{two}
		It aims to beautify .tex, .sty
		and .cls files. It is customisable
		via its YAML interface.
	\end{two}
\end{one}

documentation

For complete details, please see:

• pdf: http://mirrors.ctan.org/support/latexindent/documentation/latexindent.pdf
• online: http://latexindentpl.readthedocs.io/ (if you find discrepancies between the pdf and readthedocs, defer to the pdf)

build status

I use both travis-ci (Linux) and AppVeyor (Windows) as continuous integration services to test latexindent.pl for a small selection of test cases for every commit (I use git to track changes in the many test cases listed in the test-cases directory); you can see which versions of perl are tested by travis-ci within .travis.yml.Additionally, GitHub actions performs checks on a selectionof test cases on every commit.

Windows executable (does not require perl installation)

latexindent.exe is a standalone executable file which does not require a perl installation.It is available at releases page of this repositoryand also from https://ctan.org/tex-archive/support/latexindent.

If you wish to use latexindent.exe then you will need only two files:

latexindent.exe
defaultSettings.yaml

GitHub Actions

latexindent.exe is created and released by GitHub Actions; thefile that controls this is available within the github/workflows directoryof this repository, and you can track the actions on the actions page of this repository.

usage

You'll need

latexindent.pl
LatexIndent/*.pm
defaultSettings.yaml

in the same directory.

Windows users who do not have a perl installation might prefer to get

latexindent.exe
defaultSettings.yaml

perl modules

You'll need a few readily-available perl modules. Full details are given within the Appendixof the documentation;you might also like to see .travis.yml for Linux/MacOS users,and .appveyor.yml for Strawberry perl users.

testing

A nice way to test the script is to navigate to the test-casesdirectory, and then run the command (on Linux/Mac -- sorry, a Windows test-case version is not available):

./test-cases.sh

important

This script may not work for your style of formatting; I highlyrecommend comparing the outputfile.tex to make sure thatnothing has been changed (or removed) in a way that will damageyour file.

I recommend using each of the following:

• a visual check, at the very least, make sure thateach file has the same number of lines
• a check using latexdiff inputfile.tex outputfile.tex
• git status myfile.tex

feature requests

I'm happy to review feature requests, but I make no promises as to if theywill be implemented; if they can be implemented, I make no promises as tohow long it will take to implement them, and in which order I do so -- somefeatures are more difficult than others! Feel free to post on the issuespage of this repository, but please do use the given issue template!

development model

I follow the development model given here: http://nvie.com/posts/a-successful-git-branching-model/which means that latexindent.pl always has (at least) two branches:

main
develop

The main branch always contains the released version and develop contains thedevelopment version. When developing a new feature or bug fix, I typically use:

git checkout develop
git checkout -b feature/name-of-feature

and then I merge it into the develop branch using

git checkout develop
git merge feature/name-of-feature --no-ff

perl version

I develop latexindent.pl on Ubuntu Linux, using perlbrew; I currently develop on perl version v5.32.1

related projects

You might like to checkout the following related projects on github.

arara:

atom-beautify:

thank you

Thank you to the contributors to the project!

quotes

I find that the following quotes resonate with me with regards to my approach to latexindent.pl:

• I want people to use Perl. I want to be a positive ingredient of the world and make my American history. So, whatever it takes to give away my software and get it used, that's great. Larry Wall
• A common, brute-force approach to parsing documents where newlines are not significant is to read ... the entire file as one string ... and then extract tokens one by one, Christiansen & Torkington, Perl Cookbook, Section 6.16
• Once you understand the power that regular expressions provide, the small amount of work spent learning them will feel trivial indeed Friedl, Mastering Regular Expressions, end of Chapter 1.
• a problem speaks to them, and they have to solve it...and it becomes a hobby. But they keep coming back to it every now and then. They keep tinkering. It will never be finished...that's the point of a hobby, Westwood to Reacher in 'Make Me', Lee Child
• Do the best you can until you know better. Then when you know better, do better. Maya Angelou

changelog

changelog.md provides details of the history of the project.