What is a valid arara configuration file?

Question

The arara program itself is running from the command line, and from TeXWorks, but I'm stuck at config file errors.

It's supposed to be optional - so I've tried without one. That gives an error Apparently, there's an invalid directive at line 3.

There are rules at https://github.com/cereda/arara/tree/master/rules but at least the lualatex one throws errors.

Rules that seem according to the manual https://ctan.crest.fr/tex-archive/support/arara/doc/arara-usermanual.pdf to be valid e.g.

!config
paths:
- C:/Program Files/arara

throw errors like

Problem: mapping values are not allowed here
Error found in line 1, column 5.
    paths:

There are various online versions, but they all throw similar errors.

Answer 1

_{I am marking this answer as community-wiki.}

Version 3.0a is know to be shipped with TeX Live and MiKTeX, so if you have either of those TeX distributions, it is almost certain that you already have arara in your system path. :) A quick glance in the terminal:

[paulo@cambridge ~] $ arara -v
  __ _ _ __ __ _ _ __ __ _ 
 / _` | '__/ _` | '__/ _` |
| (_| | | | (_| | | | (_| |
 \__,_|_|  \__,_|_|  \__,_|

arara 3.0a - The cool TeX automation tool
Copyright (c) 2012, Paulo Roberto Massa Cereda
All rights reserved.
...

So far, so good. :)

arara is also shipped with several predefined rules. They are listed in the current user manual (accessible through CTAN or by issuing texdoc arara in the terminal). Here they are in a TeX Live installation:

[paulo@cambridge rules] $ pwd
/usr/local/texlive/2017/texmf-dist/scripts/arara/rules
[paulo@cambridge rules] $ ls
biber.yaml         lmkclean.yaml        make.yaml        sketch.yaml
bibtex.yaml        lualatexmk.yaml      nomencl.yaml     songidx.yaml
clean.yaml         lualatex.yaml        pdflatexmk.yaml  tex.yaml
dvips.yaml         luatex.yaml          pdflatex.yaml    xelatexmk.yaml
frontespizio.yaml  makeglossaries.yaml  pdftex.yaml      xelatex.yaml
latex.yaml         makeindex.yaml       ps2pdf.yaml      xetex.yaml

So, unless you want to define a custom rule for arara, there is absolutely no need to have a configuration file. :) Everything will already work out of the box. For example, consider mydoc.tex:

% arara: pdflatex
\documentclass{article}

\begin{document}
Hello world.
\end{document}

If you run arara mydoc.tex, the compilation will happen as expected:

[paulo@cambridge ~] $ arara mydoc.tex 
  __ _ _ __ __ _ _ __ __ _ 
 / _` | '__/ _` | '__/ _` |
| (_| | | | (_| | | | (_| |
 \__,_|_|  \__,_|_|  \__,_|

Running PDFLaTeX... SUCCESS

To run arara through TeXworks, we need to configure the editor first. :) Here we go!

_{The following steps are described in the current user manual, so I took the liberty of reproducing it here as well, for completeness sake.}

1. First, click in Edit → Preferences... to open the preferences screen:

2. The next screen is the TeXworks preferences. There are several tabs available. Navigate to the Typesetting tab, which contains two lists: the paths for TeX and related programs, and the processing tools. In the second list - the processing tools - click the Plus (+) button to add another tool.

3. TeXworks provides a very straightforward interface for adding new tools; we just need to provide the tool name, the executable path, and the parameters.

Important note: When I wrote the manual, arara was not yet distributed with TeX Live or MiKTeX, hence the figure displays a different path. It is advisable for you to select the arara executable from the bin folder in your TeX Live installation. Sadly, I don't have a Windows machine to point you to the exact location, so I kindly ask our friends here to help me on this regard. :)

Here we have the parameters:

Now it is just a matter of confirming the inclusion of arara in the list of tools in your TeXworks session. :) Then arara will be listed as a compilation profile:

Now, let me go back and talk about configuration files for version 3.0a. Since I am a Linux user, it took me a while to understand why the tool had raised that specific error. The reason is, surprisingly, the existence of :, which in the YAML format, represents a map separator (hence the error). The solution would be quoting the entry either with single or double quotes:

!config
paths:
- 'C:/Program Files/arara'

And I believe this particular issue regarding configuration files is solved. Now, back to the rules residing in the project's official repository at GitHub. :)

For a while, I've been working on a brand new version of arara to be released in this year, hopefully. New enhancements, bug fixes and much more were added to this new release, and the rule format had to be updated. Given that this was my first project with a lot of visibility, I had not much experience in organising things, so there was no warning sign telling users of version 3.0a of arara to not rely on those rules by the sheer fact that they were for the upcoming version and no backwards-compatible. So I kindly apologize for the confusion.

There is no need to rely on those rules because the current distribution of arara already covers most of them. Hopefully, the new version will be released in the next months and all confusion regarding versioning will be over. And other issues will arise, eventually. :)

So that's it, I hope my humble notes can help you. :) Please, let me know if you need any clarification, I'd be more than glad to help you!