The cool TEX automation tool

User Manual

Paulo R. M. Cereda
cereda@users.sf.net

Marco Daniel

Brent Longborough

marco.daniel@mada-nada.de

brent@longborough.org

Nicola L. C. Talbot
http://www.dickimaw-books.com/

Version 4.0

You bastard, you broke my rules!

Dear Lord, please grant me the
ability to punch people in the
face over the Internet.
Anonymous

Wait a minute, shouldnt this be a prologue instead? Yes, it should,

but since our new version breaks, to some extend, backwards compatibility, I decided to write this quick tutorial on how to port old rules to
the new format hopefully, the definitive one.
A friendly note
If you are using arara for the very first time, I have good news: you
can safely skip this tutorial, yay!

Let us begin with a very simple rule named foo, as shown in Code 1.
As we can observe, this rule has no arguments and contains only one
command (line 4).
1
2
3
4
5

!config
identifier: foo
name: Foo
command: foo
arguments: []

Code 1: A simple rule named foo which works in version 3.0 of arara.
i

ii
Code 1 is a valid rule for version 3.0 of arara. Sadly, if we try to
invoke this very same rule in the new 4.0 version, we will get a nasty
error, as shown in Code 2. In short, the error tells us (amongst other
things) that we have an invalid property named command (lines 22 and 23
are our main source of information).
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

__ _ _ __ __ _ _ __ __ _
/ _` | '__/ _` | '__/ _` |
| (_| | | | (_| | | | (_| |
\__,_|_| \__,_|_| \__,_|
Processing 'test_foo.tex' (size: 24 bytes, last modified:
12/24/2014 06:40:32), please wait.
I have spotted an error in rule 'foo' located at
'/home/paulo/Projects/Tests/arara/rules'. I could not parse the
rule, something bad happened. Apparently, the provided YAML file
is invalid. I will do my best to help you in any way I can. There
are more details available on this exception:
DETAILS --------------------------------------------------------Cannot create property=command for
JavaBean=com.github.cereda.arara.model.Rule@1471ecf
in 'reader',
line 1, column 1:
!config
^
Unable to find property
'command' on class: com.github.cereda.arara.model.Rule
in
'reader', line 4, column 10:
command: foo
^
Total: 0.08 seconds

Code 2: Error raised by arara 4.0 when a rule written in the old format
is invoked.
As youve probably guessed, arara 4.0 does not recognize command as
a valid rule key anymore. I decided to remove this key in favour of the
generic (and already available) commands list; from now on, we can think

iii
of a rule with one command as a rule with a list of commands with just
one element. Sounds quite straightforward. I took this decision because
its not worth keeping two different keys in order to express the very
same thing in the rule context, so I opted for the more generic one.
Your friendly duck says
Starting from version 4.0, command is no more. It has ceased to be. Its
expired and gone to meet its maker. Its a stiff. Bereft of life, it rests in
peace. Its kicked the bucket, its shuffled off its mortal coil, run down
the curtain and joined the bleedin choir invisibile.

But I am afraid its not a simple substitution. Using the old syntax
for commands doesnt work either because arara 4.0 introduces a couple
of new features in the rule context (discussed later on in Chapter 1); we
actually need to add a command key for each element of this list.
Here is the whole migration path: command is replaced by a commands
list, and each element of this list must contain at least the command key.
I believe it might sound confusing at first, but Code 3 might help us
understand the whole process for rules with a single command.
3.0 format

4.0 format

1
2
3
4
5

1
2
3
4
5
6

!config
identifier: <id>
name: <name>
command: <command>
arguments: <arguments>

!config
identifier: <id>
name: <name>
commands:
- command: <command>
arguments: <arguments>

Code 3: Migration for rules with a single command.

As we can see from Code 3, the migration is pretty simple. The new
format looks a bit verbose at first, but its because each command can
now hold a couple of extra useful properties, as explained later on in
Chapter 1.
Now that weve learned how the new format works, we can rewrite
the foo rule from Code 1 in order to reflect the changes that arara 4.0
requires; the new foo rule is shown in Code 4. Its important to observe
that the new 4.0 format has several improvements in the rule context as
well, but this tutorial aims only at providing the minimal requirements
for an easy migration. For a more complete reference on new keys, please
refer to Chapter 1.

iv
1
2
3
4
5
6

!config
identifier: foo
name: Foo
commands:
- command: foo
arguments: []

Code 4: The foo rule ported to version 4.0 of arara.

Now that weve tackled a rule with only one command, let see how
we should migrate rules with several commands to the new format. The
idea is basically the same, we only need to add a new command line for
each command in our list, as seen in Code 5.
3.0 format

4.0 format

1
2
3
4
5
6
7
8
9

1
2
3
4
5
6
7
8
9

!config
identifier: <id>
name: <name>
commands:
- <command 1>
- <command 2>
...
- <command n>
arguments: <arguments>

!config
identifier: <id>
name: <name>
commands:
- command: <command 1>
- command: <command 2>
...
- command: <command n>
arguments: <arguments>

Code 5: Migration for rules with several commands.

Thats it, old rules will now work with arara 4.0 without any problems. Again, I am deeply sorry for breaking the old format, but it was
something necessary to the survival of this humble tool. Now, with the
new format, we can achieve new things Ive never thought arara would
be able to, so I really hope you will enjoy this new and exciting version
as much as I do!

Prologue
Moral of the story: never read
the documentation, bad things
happen.
David Carlisle

First and foremost, welcome to my humble contribution to the TEX

community: arara, the cool TEX automation tool! It is quite an honour
and a privilege to write such warm words to you, dear reader.

A little story
When I released the very first version of arara on a Friday 13th, April
2012, I never thought the tool would receive so many positive comments
and feedback. To be honest, since arara was written for helping me with
my own personal LATEX projects, I really doubted if the tool could be of
service to anyone else. And, to my surprise, it seems arara did good. To
a lot of people around the TEX world.
Personal stories
I got feeback from friends all around the world. It was and it is a
very touching experience to learn about their own stories with arara
and why they decided to adopt this naughty bird.

I never intended to release the tool to the whole world, since I wasnt
sure if other people could benefit from araras features. After all, theres
already a plethora of tools available to the TEX community in general,
v

vi
although with different approaches. The reason I decided to make arara
publicly available is quite simple: I wanted to somehow contribute to the
TEX community, and I wanted to give my best to make such community
even more awesome.

Acknowledgments
As time goes by, Im quite satisfied with the current state of arara this
is our fourth major release in the wild. We have reached a very mature
code and a great team of developers, translators and testers. Since version 1.0, the code evolved a lot new features, lots of bug fixes, improvements thanks to all the feedback I received. In my humble opinion,
thats how any project should evolve: based on what our users expect
and want to achieve. Im proud to see arara being 100% communitydriven.
First of all, Id like to thank some friends of mine that really made
arara possible: Alan Munn, for providing great ideas and suggestions
to the manual; Andrew Stacey, for heavily testing arara, providing great
user cases, and for suggesting improvements to the program; Brent Longborough, a member of the core team, for providing great suggestions and
ideas to the program logic, writing rules, testing the code and also for
working with the Portuguese and Turkish translations;
That said, I still believe that the warning featured in the first version
of this manual still applies: Hic Sunt Dracones. Though the code really
evolved from the first commit I made, arara is far from being bug-free.
And you will learn that arara gives you enough rope. In other words,
you will be responsible for how arara behaves and all the consequences
from your actions. Sorry to sound scary, but I really needed to tell you
this. After all, one of araras greatest features is the freedom it offers.
But as you know, freedom always comes at a cost. Please, dont send us
angry letters or e-mails, perhaps if something bad happen.

Feedback
Feedback is surely welcome for me to improve this humble tool, just
write an e-mail to me or any other member of the team and we will
reply as soon as possible. The source code (application, installer and
user manual) is fully available at http://www.ctan.org/pkg/arara or at
http://github.com/cereda/arara, feel free to contribute to the project

Feedback

vii

by forking it, submitting bugs, sending pull requests or even translating

it to your language. If you want to support the LATEX development by
a donation, the best way to do this is donating to the TEX Users Group.
Please also consider joining our TEX community at StackExchange.

Paulo Roberto Massa Cereda

on behalf of the arara team

Release information
Are there programming
languages other than TEX?
Enrico Gregorio

Version 3.0
Text about version.
1
2
3
4
5
6
7
8
9

paulo@alexandria ~$ arara
__ _ _ __ __ _ _ __ __ _
/ _` | '__/ _` | '__/ _` |
| (_| | | | (_| | | | (_| |
\__,_|_| \__,_|_| \__,_|
arara 3.0 - The cool TeX automation tool
Copyright (c) 2012, Paulo Roberto Massa Cereda
All rights reserved.

new

fixed

new

Localized messages in English,

Brazilian Portuguese, German,
Italian, Spanish, French, Turkish
and Russian.

sages instead of generic ones.

new

An optional configuration file is

now available in order to customize and enhance the application behaviour.

fixed

Improved rule syntax, new keys

added.

Improved error analysis for

rules and directives.
Friendly and very detailed mes-

ix

x
new

Now rules are unified in a plain

format. No more compiled rules.

new

Rules can allow an arbitrary

number of commands instead of
just one.

new

Built-in functions in the rule

context to ease the writing process.

fixed

Improved
nism.

expansion

mecha-

Version 2.0
Text about version 2.0.
new

fixed

new

Added the --timeout n flag to

allow setting a timeout for every
task. If the timeout is reached
before the task ends, arara will
kill it and interrupt the processing. The n value is expressed in
milliseconds.

fixed

Fixed the --verbose flag to behave as a realtime output.

new

requires user interaction, the

task execution is interrupted.

Theres no need of noninteractive commands anymore. arara

can now handle user input
through the --verbose tag. If the
flag is not set and the command

Fixed the execution of some

script-based system commands
to ensure cross-platform compatibility.
Added the @{SystemUtils} orb
tag to provide specific operating system checks. The orb tag
maps the SystemUtils class from
the amazing Apache Commons
Lang library and all of its methods and properties.

Version 1.0.1
Text about 1.0.1.
new

new

Added support for .tex, .dtx

and .ltx files. When no extension is provided, arara will automatically look for these extensions in this specific order.
Added the --verbose flag to allow printing the complete log in
the terminal. A short -v tag is

also available. Both stdout and

stderr are printed.
fixed

Fixed exit status when an exception is thrown. Now arara

also returns a non-zero exit status when something wrong happened. Note that this behaviour
happens only when arara is
processing a file.

Feedback

Version 1.0
Text about 1.0.
new

First public release.

xi

License
Anything that prevents you
from being friendly, a good
neighbour, is a terror tactic.
Richard Stallman

arara is licensed under the New BSD License. It is important to observe

that the New BSD License has been verified as a GPL-compatible free
software license by the Free Software Foundation, and has been vetted as
an open source license by the Open Source Initiative.

The cool TEX automation tool

Copyright 2012, Paulo Roberto Massa Cereda
All rights reserved.
Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:
Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
Redistributions in binary form must reproduce the above copyright
notice, this list of conditions and the following disclaimer in the
documentation and/or other materials provided with the distribution.
xiii

xiv
This software is provided by the copyright holders and contributors as
is and any express or implied warranties, including, but not limited
to, the implied warranties of merchantability and fitness for a particular
purpose are disclaimed. In no event shall the copyright holder or contributors be liable for any direct, indirect, incidental, special, exemplary,
or consequential damages (including, but not limited to, procurement
of substitute goods or services; loss of use, data, or profits; or business
interruption) however caused and on any theory of liability, whether in
contract, strict liability, or tort (including negligence or otherwise) arising in any way out of the use of this software, even if advised of the
possibility of such damage.

Contents
A little story . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . . . .
Feedback . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

xv

v
vi
vi

List of Figures

xvii

List of Tables

xix

List of Codes
1
2
3
4
5

A simple rule named foo which works in version 3.0 of arara.

Error raised by arara 4.0 when a rule written in the old format is invoked. . . . . . . . . . . . . . . . . . . . . . . . . . . .
Migration for rules with a single command. . . . . . . . . . .
The foo rule ported to version 4.0 of arara. . . . . . . . . . .
Migration for rules with several commands. . . . . . . . . . .

xxi

i
ii
iii
iv
iv