arara root file (compile the main file)

Question

The arara manual on page 21 bottom

The directive context also features another special parameter named files which expects a non-empty list of file names as plain string values. For each element of this list, arara will replicate the current directive and point the ele- ment being iterated as current reference value (resolved to a proper absolute, canonical path of the file name).

( Important changes in the 5.x series ) at page 22 says:

arara previously had the file name string reference as the file variable in the rule context. As of version 5.0, support for this variable has been dropped. Users should favour the reference variable instead, since it holds the absolute, canonical representation of the file name as a proper File object.

on page 14

Our tool has two names reserved for internal use: files , and reference . Do not use them as argument identifiers!

and on page 16

reference This variable holds the canonical, absolute path representation of the file name as a File object. This is useful if it’s necessary to know the hierarchical structure of a project. Since the reference is a Java object, we can use all methods available in the File class.

I have a file called file1.tex which is part of main.tex. In file1.tex I have % arara: lualatex: { files: [ main.tex ] } so if I compile file1.tex is actualy starting compile the main file.

What I'm asking you: Since English is not my natural language I'm a little bit confused of the information and I need a clarification if my % arara: ... is actually getting the main file to be compiled and sees file1.tex as not being the main one, or I'm just lucky with {file: [main.tex] } because changing the command to:

% arara: lualatex: { reference: [ main.tex ] } I get the error:

I read a directive (3) and found out that the key 'reference' was used. This key is reserved, so you cannot use it. But do not worry, this should be an easy fix. Just replace it by another name.

Answer 1

You are mixing two things here: file (removed in v5, note the singular) and reference are parameters arara passes into the rule and directive context. You can't change them. files on the other hand is a parameter you can set in the way you did; being reserved here just means you cannot call a parameter in an own rule files.

So to answer your question: You are absolutely correct to use files to specify your main file.

Nitpick: arara does not know the concept of a main file, it only does what you instruct it to do. Hence, you are actually just overwriting arara's default to act on reference by being more explicit and using files.