animate
asymptote
authorindex
bib2gls
biber
bibtex
bibtex8
bibtexu
clean
context
convert
copy
csplain
datatooltk
detex
dvipdfm
dvipdfmx
dvips
dvipspdf
dvisvgm
etex
fig2dev
frontespizio
ghostscript
gnuplot
halt
indent
knitr
latex
latexmk
llmk
ltx2any
luahbtex
lualatex
luatex
make
makeglossaries
makeglossarieslite
makeindex
metapost
mkdir
move
nomencl
pbibtex
pdfcrop
pdfcsplain
pdflatex
pdftex
pdftk
perltex
platex
ps2pdf
pythontex
qpdf
rmdir
sage
sketch
songidx
spix
tex
texcount
texindy
tikzmake
upbibtex
uplatex
uptex
xdvipdfmx
xelatex
xetex
xindex
xindy
The official rule pack

arara ships with a pack of default rules, placed inside a special subdirectory named rules/ inside another special directory named ARARA_HOME (the place where our tool is installed). This chapter introduces the official rules, including proper listings and descriptions of associated parameters whenever applied. Note that such rules work off the shelf, without any special installation, configuration or modification. An option marked by [S] before the corresponding identifier indicates a natural boolean switch. Similarly, the occurrence of an [R] mark indicates that the corresponding option is required.

Can my rule be distributed within the official pack?
As seen in Important concepts, the default rule path can be extended to include a list of directories in which our tool should search for rules. However, if you believe your rule is comprehensive enough and deserves to be in the official pack, please contact us! We will be more than happy to discuss the inclusion of your rule in forthcoming updates.

animate

This rule creates an animated gif file from the corresponding base name of the ❖ currentFile reference (i.e, the name without the associated extension) as a string concatenated with the pdf suffix, using the convert command line utility from the ImageMagick suite.

Microsoft Windows woes
According to the ImageMagick website, the Windows installation routine adds the program directory to the system path, such that one can call command line tools directly from the command prompt, without providing a path name. However, convert is also the name of Windows system tool, located in the system directory, which converts file systems from one format to another.

The best solution to avoid possible future name conflicts, according to the ImageMagick team, is to call such command line tools by their full path in any script. Therefore, the convert rule provides the program option for this specific scenario. 

% arara: animate: { delay: 15, density: 150 }

asymptote

This rule executes the asy command line program, referring to Asymptote, a powerful descriptive vector graphics language for technical drawings, inspired by Metapost but with an improved syntax. Please note that you will have to make the .asy extension known to arara in order to compile Asymptote files. Furthermore, it is advised to use this in your regular TeX document specifying the files parameter to include all graphics you want to compile for inclusion in your document.

% arara: asymptote: { files: [ mydrawing.asy ] }

authorindex

This rule calls the authorindex wrapper, a Perl script that processes auxiliary files generated by the package of the same name, producing author index files, with the ain extension.

% arara: authorindex: { draft: yes }

bib2gls

This rule executes the bib2gls command line application which extracts glossary information stored in a bib file and converts it into glossary entry definitions in resource files. This rule passes the base name of the ❖ currentFile reference (i.e, the name without the associated extension) as the mandatory argument.

% arara: bib2gls: { group: true }
% arara: --> if found('aux', 'glsxtr@resource')

biber

This rule runs biber, the backend bibliography processor for biblatex, on the corresponding base name of the ❖ currentFile reference (i.e, the name without the associated extension) as a string.

% arara: biber: { options: [ '--wraplines' ] }

bibtex

This rule runs the bibtex program, a reference management software, on the corresponding base name of the ❖ currentFile reference (i.e, the name without the associated extension) as a string.

% arara: bibtex: { options: [ '-terse' ] }
% arara: --> if exists(toFile('references.bib'))

bibtex8

This rule runs bibtex8, an enhanced, portable C version of bibtex, on the corresponding base name of the ❖ currentFile reference (i.e, the name without the associated extension) as a string. It is important to note that this tool can read a character set file containing encoding details.

% arara: bibtex8: { options: [ '--trace', '--huge' ] }

bibtexu

This rule runs the bibtexu program, an enhanced version of bibtex with Unicode support and language features, on the corresponding base name of the ❖ currentFile reference (i.e, the name without the associated extension) as a string.

% arara: bibtexu: { options: [ '--language', 'fr' ] }

clean

This rule removes the provided file reference through the underlying system command, which can be rm in a Unix environment or del in Microsoft Windows. As a security lock, this rule will always throw an error if ❖ currentFile is equal to ❖ getOriginalFile, so the main file reference cannot be removed. It is highly recommended to use the special files parameter to indicate removal candidates. Alternatively, a list of file extensions can be provided as well. Be mindful that the security lock also applies to file removals based on extensions.

Better safe than sorry!
When in doubt, always remember that the --dry-run command line option is your friend! As seen in Command line, this option makes arara go through all the motions of running tasks and subtasks, but with no actual calls. It is a very useful feature for testing the sequence of removal commands without actually losing your files! Also, as good practice, always write plain, simple, understandable clean directives and use as many as needed in your TeX documents. 
% arara: clean: { extensions: [ aux, log ] }

context

This rule runs the context TeX engine on the provided ❖ currentFile reference, generating a corresponding file in the Portable Document Format. Please refer to the user manual for further details.

% arara: context

convert

This rule runs the convert program, a member of the ImageMagick suite of tools. This program is used to convert between image formats as well as resize an image, blur, crop, despeckle, dither, draw on, flip, join, resample, and more.

% arara: convert: { options: [ 'photo1.jpg', '--resize',
% arara: --> '50%', 'photo2.jpg' ] }

copy

This rule copies the File reference to the provided target using the underlying operating system copy operation. The target is always overwritten. However, be mindful that an error will be thrown if you try to overwrite the file referenced in ❖ getOriginalReference.

% arara: copy: { target: 'backup/thesis.tex' }

csplain

This rule runs the csplain TeX engine, a conservative extension of Knuth's plain TeX with direct processing characters and hyphenation patterns for Czech and Slovak, on the provided ❖ currentFile reference.

% arara: csplain: { interaction: batchmode, shell: yes }

datatooltk

This rule runs datatooltk, an application that creates datatool databases in raw format from several structured data formats, in batch mode. This rule requires output and one of the import options.

% arara: datatooltk: {
% arara: --> output: books.dbtex,
% arara: --> csv: booklist.csv }

detex

This rule runs detex, a command line application that, as the name indicates, reads the provided ❖ currentFile reference, removes all comments and TeX control sequences and writes the remainder to the standard output or file.

% arara: detex: { output: thesis.txt }

dvipdfm

This rule runs dvipdfm, a command line utility for file format translation, on the corresponding base name of the ❖ currentFile reference (i.e, the name without the associated extension) as a string concatenated with the dvi suffix, generating a Portable Document Format pdf file.

% arara: dvipdfm: { output: thesis }

dvipdfmx

This rule runs dvipdfmx, an extended version of dvipdfm created to support multibyte character encodings and large character sets for East Asian languages, on the corresponding base name of the ❖ currentFile reference (i.e, the name without the associated extension) as a string concatenated with the dvi suffix, generating a Portable Document Format pdf file.

% arara: dvipdfmx: { options: [ '-K', '40' ] }

dvips

This rule runs dvips on the corresponding base name of the ❖ currentFile reference (i.e, the name without the associated extension) as a string concatenated with the dvi suffix, generating a PostScript ps file.

% arara: dvips: { output: thesis }

dvipspdf

This rule runs dvips in order to obtain a corresponding ps file from the initial dvi reference, and then runs ps2pdf on the previously generated ps file in order to obtain a pdf file. Note that all base names are acquired from the ❖ currentFile reference (i.e, the name without the associated extension) and used to construct the resulting files.

% arara: dvipspdf: { output: article }

dvisvgm

This rule runs dvisvgm in order to obtain a corresponding svg file, a vector graphics format based on XML, from the initial reference. It is important to observe that the base name is acquired from the ❖ currentFile reference (i.e, the name without the associated extension) and used to construct the resulting file.

% arara: dvisvgm

etex

This rule runs the etex extended (plain) TeX engine on the provided ❖ currentFile reference, generating a corresponding file in a device independent format.

% arara: etex: {
% arara: --> shell: yes,
% arara: --> interaction: batchmode
% arara: --> }

fig2dev

This rule runs fig2dev, a command line application that translates fig code in the corresponding base name of the ❖ currentFile reference (i.e, the name without the associated extension) as a string concatenated with the fig suffix into the specified graphics language and puts them in the specified output file.

% arara: fig2dev: { language: mp, output: drawing.mp }

frontespizio

This rule automates the steps required by the frontespizio package in order to help Italian users generate the frontispiece to their thesis. First and foremost, the frontispiece is generated. If latex is used as the underlying engine, there is an additional intermediate conversion step to a proper eps file. Finally, the final document is compiled.

% arara: frontespizio: { engine: xelatex,
% arara: --> shell: yes, interaction: nonstopmode }

ghostscript

This rule runs ghostscript, an interpreter for PostScript and Portable Document Format files, according to the provided parameters.

% arara: ghostscript: { options: [ '-dCompatibilityLevel=1.4',
% arara: --> '-dPDFSETTINGS=/printer', '-dNOPAUSE', '-dQUIET',
% arara: --> '-dBATCH', 'input.pdf' ],
% arara: --> output: output.pdf,
% arara: --> device: pdfwrite }

gnuplot

This rule runs gnuplot, a command-driven plotting program that can generate plots of functions, data and data fits. The program also provides scripting capabilities, looping, functions, text processing, variables, macros, arbitrary pre-processing of input data (usually across columns), as well as the ability to perform non-linear multi-dimensional multi-set weighted data fitting.

% arara: gnuplot: { input: [ myplot.gnuplot ], default: yes }

halt

This rule, as the name suggests, sets a halt flag, which stops the current interpretation workflow, such that subsequent directives are ignored. This rule contains no associated options. Please refer to Methods for more information on flags.

% arara: halt

indent

This rule runs latexindent, a Perl script that indents TeX files according to an indentation scheme, on the provided ❖ currentFile reference. Environments, including those with alignment delimiters, and commands, including those that can split braces and brackets across lines, are usually handled correctly by the script.

% arara: indent: { overwrite: yes }

knitr

This rule calls the knitr package, a transparent engine for dynamic report generation with R. It takes an .Rnw file as input, extracts the R code in it according to a list of patterns, evaluates the code and writes the output in another file. It can also tangle R source code from the input document.

% arara: knitr: { quiet: yes }

latex

This rule runs the latex TeX engine on the provided ❖ currentFile reference, generating a corresponding file in a device independent format.

% arara: latex: { interaction: scrollmode, draft: yes }

latexmk

This rule runs latexmk, a fantastic command line tool for fully automated TeX document generation, on the provided ❖ currentFile reference.

% arara: latexmk: { engine: pdflatex }

llmk

This rule runs llmk, a command line tool specific for building LaTeX documents. The tool's aim is to provide a simple way to specify a workflow of processing documents and encourage people to always explicitly show the right workflow for each document.

% arara: llmk: { mode: verbose }

ltx2any

This rule runs ltx2any, a command line tool written in Ruby that acts as a LaTeX build wrapper, on the provided ❖ currentFile reference.

% arara: ltx2any: { synctex: yes }

luahbtex

This rule runs the luahbtex TeX engine on the provided ❖ currentFile reference, generating a corresponding file in the Portable Document Format, as expected.

% arara: luahbtex: { interaction: batchmode,
% arara: --> shell: yes, draft: yes }

lualatex

This rule runs the new lualatex TeX engine on the provided ❖ currentFile reference, generating a corresponding file in the Portable Document Format, as expected.

% arara: lualatex: { interaction: errorstopmode,
% arara: --> synctex: yes }

luatex

This rule runs the luatex TeX engine on the provided ❖ currentFile reference, generating a corresponding file in the Portable Document Format, as expected.

% arara: luatex: { interaction: batchmode,
% arara: --> shell: yes, draft: yes }

make

This rule runs make, a build automation tool that automatically builds executable programs and libraries from source code, according to a special file which specifies how to derive the target program.

% arara: make: { targets: [ compile, package ] }

makeglossaries

This rule runs makeglossaries, an efficient Perl script designed for use with TeX documents that work with the glossaries package. All the information required to be passed to the relevant indexing application should also be contained in the auxiliary file. The script takes the corresponding base name of the ❖ currentFile reference (i.e, the name without the associated extension) as the mandatory argument.

% arara: makeglossaries if found('aux', '@istfilename')

makeglossarieslite

This rule runs makeglossaries-lite, a lightweight Lua script designed for use with TeX documents that work with the glossaries package. All the information required to be passed to the relevant indexing application should also be contained in the auxiliary file. The script takes the corresponding base name of the ❖ currentFile reference (i.e, the name without the associated extension) as the mandatory argument.

% arara: makeglossarieslite if found('aux', '@istfilename')

makeindex

This rule runs makeindex, a general purpose hierarchical index generator, on the corresponding base name of the ❖ currentFile reference (i.e, the name without the associated extension) as a string concatenated with the idx suffix, generating an index as a special ind file.

% arara: makeindex: { style: book.ist }

metapost

This rule runs metapost, a tool to compile the Metapost graphics programming language. Please note that you will have to make the .mp extension known to arara in order to compile Metapost files. Furthermore, it is advised to use this in your regular TeX document specifying the files parameter to include all graphics you want to compile for inclusion in your document.

% arara: metapost: { files: [ graphics.mp ] }

mkdir

This rule creates a new directory at the current location and all parents as required. It does nothing if the directory already exists.

% arara: mkdir: { target: 'dir_to_make' }

move

This rule moves the File reference to the provided target using the underlying operating system move operation. The target is always overwritten. However, be mindful that an error will be thrown if you try to move or overwrite the file referenced in ❖ getOriginalReference.

% arara: move: { files: [ 'thesis.pdf' ],
% arara: --> target: 'backup/thesis.pdf' }

nomencl

This rule runs makeindex in order to automatically generate a nomenclature list from TeX documents that work with the nomencl package. The program itself is a general purpose hierarchical index generator and takes the corresponding base name of the ❖ currentFile reference (i.e, the name without the associated extension) as a string concatenated with the nlo suffix and a special style file in order to generate the nomenclature list as a special nls file.

% arara: nomencl

pbibtex

This rule runs the pbibtex program, a reference management software, on the corresponding base name of the ❖ currentFile reference (i.e, the name without the associated extension) as a string.

% arara: pbibtex
% arara: --> if exists(toFile('references.bib'))

pdfcrop

This rule runs pdfcrop, a command line utility to calculate and remove empty margins, on corresponding base name of the ❖ currentFile reference (i.e, the name without the associated extension) as a string concatenated with the pdf suffix.

% arara: pdfcrop

pdfcsplain

This rule runs the pdfcsplain TeX engine, a conservative extension of Knuth's plain TeX with direct processing characters and hyphenation patterns for Czech and Slovak, on the provided ❖ currentFile reference.

% arara: pdfcsplain: { shell: yes, synctex: yes }

pdflatex

This rule runs the pdflatex TeX engine on the provided ❖ currentFile reference, generating a corresponding file in the Portable Document Format, as expected.

% arara: pdflatex: { interaction: batchmode }
% arara: --> if missing('pdf') || changed('tex')

pdftex

This rule runs the pdftex TeX engine on the provided ❖ currentFile reference, generating a corresponding file in the Portable Document Format, as expected.

% arara: pdftex: { draft: yes }

pdftk

This rule runs pdftk, a command line tool for manipulating Portable Document Format documents, on the corresponding base name of the ❖ currentFile reference (i.e, the name without the associated extension) as a string concatenated with the pdf suffix.

% arara: pdftk: { options: [ burst ] }

perltex

This rule runs perltex, a wrapper that enables a symbiosis between Perl, a popular general purpose programming language, and a TeX engine, on the provided ❖ currentFile reference.

% arara: perltex: { safe: no, standalone: yes }

platex

This rule runs the platex TeX engine on the provided ❖ currentFile reference, generating a corresponding file in a device independent format.

% arara: platex: { interaction: scrollmode, shell: yes }

ps2pdf

This rule runs ps2pdf, a tool that converts PostScript to Portable Document Format, on the corresponding base name of the ❖ currentFile reference (i.e, the name without the associated extension) as a string concatenated with the ps suffix.

% arara: ps2pdf: { output: article }

pythontex

This rule runs pythontex, a wrapper that provides access to Python from within typical TeX documents, on the provided ❖ currentFile reference. Make sure to take a look at the documentation for further details.

% arara: pythontex: { jobs: 2, verbose: yes }

qpdf

This rule runs qpdf, a command line application that does structural, content-preserving transformations of Portable Document Format files, as well as providing capabilities to developers.

% arara: qpdf: { options: [ '--linearize', 'input.pdf',
% arara: --> 'output.pdf' ] }

rmdir

This rule removes a directory including its contents at the current location. It does nothing if the directory does not exist.

% arara: rmdir: { target: 'dir_to_remove' }

sage

This rule runs sage, a free open source mathematics software system, on the corresponding base name of the ❖ currentFile reference (i.e, the name without the associated extension) as a string concatenated with the sage extension (which can be overridden).

% arara: sage

sketch

This rule runs sketch, a system for producing line drawings of solid objects and scenes, on the corresponding base name of the ❖ currentFile reference (i.e, the name without the associated extension) as a string concatenated with the sk suffix. Note that one needs to add support for this particular file type, as seen in Configuration.

% arara: sketch

songidx

This rule runs songidx, a song index generation script for the songs package, on the file reference provided as parameter, generating a proper index as a special sbx file. It is very important to observe that, at the time of writing, this script is not available off the shelf in TeX Live or MiKTeX distributions, so a manual deployment is required. The script execution is performed by the underlying texlua interpreter.

% arara: songidx: { input: songs }

spix

This rule runs spix, an interesting command line TeX automation tool written in Python, on the provided ❖ currentFile reference.

% arara: spix

tex

This rule runs the tex TeX engine on the provided ❖ currentFile reference, generating a corresponding file in a device independent format.

% arara: tex: { shell: yes }

texcount

This rule runs texcount, a Perl script designed to count words in TeX and LaTeX files, ignoring macros, tables, formulae and more on the provided ❖ currentFile reference. The script is highly configurable, so make sure to check the manual for further information.

% arara: texcount: { output: report.txt }

texindy

This rule runs texindy, a variant of the xindy indexing system focused on LaTeX documents, on the corresponding base name of the ❖ currentFile reference (i.e, the name without the associated extension) as a string concatenated with the idx suffix, generating an index as a special ind file.

% arara: texindy: { markup: latex }

tikzmake

This rule runs make on a very specific build file generated by the tikzmake package, as a means to simplify the externalization of TikZ pictures. This build file corresponds to the base name of the ❖ currentFile reference (i.e, the name without the associated extension) as a string concatenated with the makefile suffix.

% arara: tikzmake: { force: yes, jobs: 2 }

upbibtex

This rule runs the upbibtex program, a reference management software, on the corresponding base name of the ❖ currentFile reference (i.e, the name without the associated extension) as a string.

% arara: pbibtex
% arara: --> if exists(toFile('references.bib'))

uplatex

This rule runs the uplatex TeX engine on the provided ❖ currentFile reference, generating a corresponding file in a device independent format.

% arara: uplatex: { interaction: scrollmode, shell: yes }

uptex

This rule runs the uptex TeX engine on the provided ❖ currentFile reference, generating a corresponding file in a device independent format.

% arara: uptex

xdvipdfmx

This rule runs xdvipdfmx, the back end for the xetex TeX engine (and not intended to be invoked directly), on the corresponding base name of the ❖ currentFile reference (i.e, the name without the associated extension) as a string concatenated with a certain suffix, generating a Portable Document Format pdf file.

% arara: xdvipdfmx: { output: thesis }

xelatex

This rule runs the new xelatex TeX engine on the provided ❖ currentFile reference, generating a corresponding file in the Portable Document Format, as expected.

% arara: xelatex: { shell: yes, synctex: yes }

xetex

This rule runs the xetex TeX engine on the provided ❖ currentFile reference, generating a corresponding file in the Portable Document Format, as expected.

% arara: xetex: { interaction: scrollmode, synctex: yes }

xindex

This rule runs xindex, a flexible and powerful indexing system, on a provided idx input. This tool is completely with the makeindex program.

% arara: xindex: { input: mydoc.idx }

xindy

This rule runs xindy, a flexible and powerful indexing system, on the corresponding base name of the ❖ currentFile reference (i.e, the name without the associated extension) as a string concatenated with the idx suffix, generating an index as a special ind file.

% arara: xindy: { markup: xelatex }

It is highly advisable to browse the relevant documentation about packages and tools described in this chapter as a means to learn more about features and corresponding advanced usage. For TeX Live users, we recommend the use of texdoc, a command line program to find and view documentation. For example, this manual can be viewed through the following command:

$ texdoc arara

The primary function of the handy texdoc tool is to locate relevant documentation for a given keyword (typically, a package name) on your disk, and open it in an appropriate viewer. For MiKTeX users, the distribution provides a similar tool named mthelp to find and view documentation. Make sure to use these tools whenever needed!