arara

The cool TeX automation tool

This project is maintained by cereda

Introduction

Welcome to arara! This chapter is a quick introduction to what you can expect from arara. Don't be afraid, it will be easy to digest, I promise.

What is arara?

Good question. I've been asking it myself for a quite long time. Since I have to provide an official definition for arara - I'm the author, the one to blame - I'd go with something along these lines:

arara is a TeX automation tool. But maybe not in the traditional sense, such as existing tools like latexmk and rubber. Think of arara as a personal assistant. It is as powerful as you want it to be. arara doesn't provide solutions out of the box, but it gives you subsidies to enhance your TeX experience.

Well, that was a shot in the dark. I'm sorry for this crude definition, but the truth is: arara is generic enough to rely on different schemes. arara will execute what you tell it to execute. How will arara do this? That's the problem: you are in control, so it depends on you.

First things first. Arara is the Brazilian name of a macaw bird. Have you ever watched Rio: the movie? The protagonist is a blue arara, or as we say in Brazil, a cute ararinha-azul. The word arara comes from the Tupian word a'rara, which means big bird.

The parrot belongs to the same family of the arara. Have you ever talked to a parrot? They are able to learn and reproduce words. Maybe I could establish an analogy between arara - the software - and a parrot. Let's see how it works.

How do you make a parrot talk? You need to teach it. The very same way happens with arara: the software will execute what you tell it to execute. How will arara do this? Easy: you need to teach it. Let's see an example for a better understanding. Consider the following LaTeX code, mydoc.tex:

\documentclass{article}

\begin{document}

Hello world.
\end{document}

How would you compile mydoc.tex in rubber, for instance? It's quite easy, a simple rubber --pdf mydoc would do the trick. Now, if you try arara mydoc, I'm afraid nothing will be generated. Why? Isn't arara supposed to be a TeX automation tool? Well, arara doesn't know what to do with your file. You need to tell it. For now, please understand that you need to provide the batteries for arara to run - bad analogy perhaps, but that's true. Don't worry, we will come back to this example later and see how to make arara produce the desired output.

Long story short: you are in control of your documents. arara won't do anything unless you teach it how to do a task and explicitly tell it to execute the task. Introducing the arara terminology:

That's probably one of the major differences of arara from other automation tools. With latexmk and rubber, for example, you have great features out of the box, ready for you to use and abuse - batteries included. arara takes a minimalist approach and gives you the simplicity of doing exactly what you want it to do. Nothing more, nothing less.

Features

There's nothing so special with arara. It does exactly what you tell it to do. On the other hand, one of the features I like in arara is the ability to write rules in a human-readable format called YAML. YAML is actually a recursive acronym for YAML Ain't Markup Language, and it's known as a human friendly data serialization standard for all programming languages. I think this format is very suitable to write rules - Ruby uses it a lot. You don't need to rely on other formats. Actually, you can write a compiled rule, but I'm almost sure you will never need one.

I like to be in control of my TeX documents - including running commands many times my heart desires and in the order I want. I can create a complex workflow and arara will handle it for me - again, as long as I have the proper rules.

Another feature worth mentioning is the fact that arara is platform independent. I wrote it in Java, so arara runs on top of a Java virtual machine, available on all the major operating systems - in some cases, you might need to install the proper virtual machine. I tried to keep my code and libraries compatible with older virtual machines - currently, Java 5, 6, 7, OpenJDK 6 and 7 are supported. But beware, if you write system-specific rules, you will need to adapt them when porting to a different operating system - actually that's not accurate, we will see later that we can add conditionals to our rule based on the underlying operating system.

You can easily integrate arara with TeXworks, an environment for authoring TeX documents shipped with both TeX Live and MiKTeX. We will cover the integration of arara and TeXworks later on.

arara is an open source project, so you can get the code and study it. Don't worry if you don't know Java, the code is well documented - there are 1642 lines of comments in the source code. The project is hosted on GitHub. You can fork the project, send pull requests or submit issues.

Common cases

arara can be used in complex workflows, like theses and books. You can tell arara to compile the document, generate indices and apply styles, remove temporary files, compile other .tex documents, create glossaries, call pdfcrop, move files, run METAPOST or METAFONT, and much more. It's up to you.

I wrote an article to a contest organized by Stefan Kottwitz and the LaTeX community about how to integrate gnuplot and arara. It might be worth a read.

The next code contains the arara workflow I used for another article I recently wrote. Note that the first call to pdflatex creates the .aux file, then bibtex will extract the cited publications. The next calls to pdflatex will insert and refine the references.

% arara: pdflatex
% arara: bibtex
% arara: pdflatex
% arara: pdflatex
\documentclass[journal]{IEEEtran}
...

The next code contains another arara workflow I used for a manual. I had to use a package that required shell escape, so the calls to pdflatex had to enable it. Also, I had an index with a custom formatting, then makeindex was called with the proper style.

% arara: pdflatex: { shell: yes }
% arara: makeindex: { style: mystyle }
% arara: pdflatex: { shell: yes }
% arara: pdflatex: { shell: yes }
\documentclass{book}
...

And of course, the arara user manual is also compiled with arara. You can take a look in the source code and check the compilation workflow. By the way, note that I had to use a trick to avoid arara to read the example directives in this manual. As we will see later, arara reads directives everywhere.

Other workflows can be easily created. There can be an arbitrary number of instructions for arara to execute, so feel free to come up with your own workflow. arara will handle it for you. My friend Joseph Wright wrote a great article about arara in his personal blog, it's really worth a read.

I really hope you like my humble contribution to the TeX community. Let arara enhance your TeX experience.

Trivia

I explained what the name arara means, but I didn't tell why I chose this name. Well, araras are colorful, noisy, naughty and very funny. Everybody loves araras. So why can't you love a tool with the very same name? And there’s also another motivation of the name arara: the chatroom residents of TeX.sx - including myself - are fans of palindromes, especially palindromic numbers. As you can already tell, arara is a palindrome.

TODO: next chapters