Add custom extensions and directives to arara

Question

This is a more general version of Adam Liter's question about setting up an arara rule for knitr.

The basic question is this:

How can I enable support for customised extensions and directives in araraconfig.yaml?

The answer would be straightforward if it were not that the documentation is apparently rather buggy. The problem is that using the syntax modelled in the manual results in the following error when arara is run:

I didn't find any directives in 'myfile.XXX', and so didn't do anything. Is that what you really wanted?

where XXX is the extension you tried to enable. Adam's question includes a fully documented example of the error for the case of knitr.

Answer 1

The solution included in Adam Liter's question worked for the case I was concerned with, as far as I can establish so far.

I am posting what I used to enable support for the mp extension in the hope that this will work more generally and/or help isolate the issue which Adam is still experiencing. Following discussion with Adam, we decided it was best to post a new generic question rather than including a more general answer in response to a knitr-specific question. (I cannot test the knitr bit.) Really, the solution here is all the result of Adam's efforts. I was just lucky enough to find that it worked perfectly with my configuration and for metapost.

Possibly relevant background information: I am using GNU/Linux with TeX Live 2013. (We don't know if it works for me because I use Linux or because I was concerned with metapost.)

Here is my araraconfig.yaml:

!config
paths:
- <arara> @{userhome}/.arara/rules
filetypes:
- extension: tex
- extension: mp
  pattern: ^(\s)*%\s+
- extension: dat
  pattern: ^(\s)*%\s+
- extension: dtx
- extension: ltx
- extension: sk
  pattern: ^(\s)*[%#]\s+
# vim: set nospell:

Crucial note: as Adam documents, you need \s where the documentation specifies \\s. (I am assuming \s means something like 'space' although the manual doesn't really explain this. Since regular expressions vary in syntax, this is a bit frustrating.)

This is the rule I am using for metapost. The rule is in .arara/rules/mpost.yaml:

!config
# metapost rule for arara
identifier: mpost
name: metapost
command: <arara> mpost @{action} @{options} "@{file}"
arguments:
- identifier: action
  flag: <arara> -interaction=@{parameters.action}
- identifier: options
  flag: <arara> @{parameters.options}
# vim: set nospell:

I then add the following directive line in my mp source file:

% arara: mpost

This enables me to run either

arara figs.mp

or

arara figs

and have arara do the right thing. Either way, I get a 'success' and figs.1 is produced. (That's the expected result in this case and converting to PDF shows that the result contains what I'd expect as well.)

Answer 2

(Apologies if this would be better as a comment. I do not have sufficient reputation to post comments.)

The following rule seems to work well when called with just the base file name. It is also possible to have arara compile the Rnw source all the way to PDF with a single rule, see below.

!config
identifier: knitr
name: knitr
command: <arara> RScript -e "library(knitr); knit('"@{source}"', output='"@{target}"')"
arguments: 
- identifier: source
  flag: <arara> "@{parameters.source}"
  default: <arara> "@{getBasename(file)}".Rnw
- identifier: target
  flag: <arara> "@{parameters.target}"
  default: <arara> "@{getBasename(file)}".tex

Unfortunately, I was not able to resolve the error in the original question when calling arara on my source Rnw file. In this case, arara complains that the file is not found. This is a problem with the rule above, because I want to call arara again to compile the .tex file to PDF. The directive

% arara: knitr

still exists as line 1 of the .tex file. Therefore, a subsequent call actually runs arara on the source Rnw file again, rather than what is intended. (I'm not sure why, since I have the Rnw extension listed last in my configuration file, reproduced below.) Of course one could edit the directive manually, but this is clumsy and inconvenient.

So we are still in need of a solution. Here is a simple workaround. This rule first calls knitr, then the xelatex engine.

!config
identifier: knitr
name: knitr
commands: 
- <arara> RScript -e "library(knitr); knit('"@{source}"', output='"@{target}"')"
- <arara> xelatex "@{target}"
arguments: 
- identifier: source
  flag: <arara> "@{parameters.source}"
  default: <arara> "@{getBasename(file)}".Rnw
- identifier: target
  flag: <arara> "@{parameters.target}"
  default: <arara> "@{getBasename(file)}".tex

Here is my configuration file that I am using with this rule.

!config
paths:
- <arara> /path/to/my/knitr/rule
filetypes:
- extension: tex
- extension: dtx
- extension: ltx
- extension: Rnw
  pattern: ^(\s)*%\s+