% !TeX root = ../arara-manual.tex
\chapter{The official rule pack}
\label{chap:theofficialrulepack}

\arara\ ships with a pack of default rules, placed inside a special subdirectory named \abox[araracolour]{rules/} inside another special directory named \abox[araracolour]{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 \rbox[araracolour]{S} after the corresponding identifier indicates a natural boolean switch. Similarly, the occurrence of an \rqbox\ mark indicates that the corresponding option is required.

\begin{messagebox}{Can my rule be distributed within the official pack?}{araracolour}{\icok}{white}
As seen in Section~\ref{sec:basicstructure}, on page~\pageref{sec:basicstructure}, 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.
\end{messagebox}

\begin{description}
\item[\rulebox{animate}{Chris Hughes, Paulo Cereda}]
This rule creates an animated \rbox{gif} file from the corresponding base name of the \mtbox{currentFile} reference (i.e, the name without the associated extension) as a string concatenated with the \rbox{pdf} suffix, using the \rbox{convert} command line utility from the ImageMagick suite.

\begin{description}
\item[\rpbox{delay}{10}] This option regulates the number of ticks before the display of the next image sequence, acting as a pause between still frames.

\item[\rpbox{loop}{0}] This option regulates the number of repetitions for the animation. When set to zero, the animation repeats itself an infinite number of times.

\item[\rpbox{density}{300}] This option specifies the horizontal and vertical canvas resolution while rendering vector formats into a proper raster image.

\item[\rpbox{program}{convert}] This option specifies the command utility path as a means to avoid potential clashes with underlying operating system commands.

\begin{messagebox}{Microsoft Windows woes}{attentioncolour}{\icattention}{black}
\setlength{\parskip}{1em}
According to the \href{http://www.imagemagick.org/Usage/windows/}{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, \rbox{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 \rbox{convert} rule provides the \abox{program} option for this specific scenario.
\end{messagebox}

\item[\abox{options}] This option, as the name indicates, takes a list of raw command line options and appends it to the actual system call. An error is thrown if any data structure other than a proper list is provided as the value.
\end{description}

\begin{codebox}{Example}{teal}{\icnote}{white}
% arara: animate: { delay: 15, density: 150 }
\end{codebox}

\item[\rulebox{bib2gls}{Nicola Talbot, Paulo Cereda}] This rule executes the \rbox{bib2gls} command line application which extracts glossary information stored in a \rbox{bib} file and converts it into glossary entry definitions in resource files. This rule passes the base name of the \mtbox{currentFile} reference (i.e, the name without the associated extension) as the mandatory argument.

\begin{description}
\item[\abox{dir}] This option sets the directory used for writing auxiliary files. Note that this option does not change the current working directory.

\item[\abox{trans}] This option sets the extension of the transcript file created by \rbox{bib2gls}. The value should be just the file extension without the leading dot. The default is \rbox{glg}.

\item[\abox{locale}] This option specifies the preferred language resource file. Please keep in mind that the provided value must be a valid \gls{IETF} language tag. If omitted, the default is obtained by \rbox{bib2gls} from the \gls{JVM}.

\item[\rpsbox{group}] This option sets whether \rbox{bib2gls} will try to determine the letter group for each entry and add it to a new field called \rbox{group} when sorting. Be mindful that some \rbox{sort} options ignore this setting. The default value is off.

\item[\rpsbox{interpret}] This option sets whether the interpreter mode of \rbox{bib2gls} is enabled. If the interpreter is on, \rbox{bib2gls} will attempt to convert any \LaTeX\ markup in the sort value to the closest matching Unicode characters. If the interpreter is off, the \rbox{log} file will not be parsed for recognised packages. The default value is on.

\item[\rpsbox{breakspace}] This option sets whether the interpreter will treat a tilde character as a non-breaking space (as with \TeX) or a normal space. The default behaviour treats it as non-breakable.

\item[\rpsbox{trimfields}] This option sets whether \rbox{bib2gls} will trim leading and trailing spaces from field values. The default behaviour does not trim spaces.

\item[\rpsbox{recordcount}] This option sets whether the record counting will be enabled. If activated, \rbox{bib2gls} will add record count fields to entries. The default behaviour is off.

\item[\rpsbox{recordcountunit}] This option sets whether \rbox{bib2gls} will add unit record count fields to entries. These fields can then be used with special commands. The default behaviour is off.

\item[\rpsbox{cite}] This option sets whether \rbox{bib2gls} will treat citation instances found in the \rbox{aux} file as though it was actually an ignored record. The default behaviour is off.

\item[\rpsbox{verbose}] This option sets whether \rbox{bib2gls} will be executed in verbose mode. When enabled, the application will write extra information to the terminal and transcript file. This option is unrelated to \arara's verbose mode. The default behaviour is off.

\item[\rpsbox{merge}] This option sets whether the program will merge \rbox{wrglossary} counter records. If disabled, one may end up with duplicate page numbers in the list of entry locations, but linking to different parts of the page. The default is on.

\item[\rpsbox{uniscript}] This option sets whether text superscript and subscript will use the corresponding Unicode characters if available. The default is on.

\item[\abox{packages}] This option instructs the interpreter to assume the packages from the provided list have been used by the document.

\item[\abox{ignore}] This option instructs \rbox{bib2gls} to skip the check for any package from the provided list when parsing the corresponding log file.

\item[\abox{custom}] This option instructs the interpreter to parse the package files from the provided list. The package files need to be quite simple.

\item[\abox{mapformats}] This option takes a list and sets up the rule of precedence for partial location matches. Each element from the provided list must be another list of exactly two entries representing a conflict resolution.

\item[\abox{options}] This option, as the name indicates, takes a list of raw command line options and appends it to the actual system call. An error is thrown if any data structure other than a proper list is provided as the value.
\end{description}

\begin{codebox}{Example}{teal}{\icnote}{white}
% arara: bib2gls: { group: true }
% arara: --> if found('aux', 'glsxtr@resource')
\end{codebox}

\item[\rulebox{biber}{Marco Daniel, Paulo Cereda}] This rule runs \rbox{biber}, the backend bibliography processor for \rbox{biblatex}, on the corresponding base name of the \mtbox{currentFile} reference (i.e, the name without the associated extension) as a string.

\begin{description}
\item[\abox{options}] This option, as the name indicates, takes a list of raw command line options and appends it to the actual system call. An error is thrown if any data structure other than a proper list is provided as the value.
\end{description}

\begin{codebox}{Example}{teal}{\icnote}{white}
% arara: biber: { options: [ '--wraplines' ] }
\end{codebox}

\item[\rulebox{bibtex}{Marco Daniel, Paulo Cereda}] This rule runs the \rbox{bibtex} program, a reference management software, on the corresponding base name of the \mtbox{currentFile} reference (i.e, the name without the associated extension) as a string.

\begin{description}
\item[\abox{options}] This option, as the name indicates, takes a list of raw command line options and appends it to the actual system call. An error is thrown if any data structure other than a proper list is provided as the value.
\end{description}

\begin{codebox}{Example}{teal}{\icnote}{white}
% arara: bibtex: { options: [ '-terse' ] }
% arara: --> if exists(toFile('references.bib'))
\end{codebox}

\item[\rulebox{bibtex8}{Marco Daniel, Paulo Cereda}] This rule runs \rbox{bibtex8}, an enhanced, portable C version of \rbox{bibtex}, on the corresponding base name of the \mtbox{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.

\begin{description}
\item[\abox{options}] This option, as the name indicates, takes a list of raw command line options and appends it to the actual system call. An error is thrown if any data structure other than a proper list is provided as the value.
\end{description}

\begin{codebox}{Example}{teal}{\icnote}{white}
% arara: bibtex8: { options: [ '--trace', '--huge' ] }
\end{codebox}

\item[\rulebox{bibtexu}{Marco Daniel, Paulo Cereda}] This rule runs the \rbox{bibtexu} program, an enhanced version of \rbox{bibtex} with Unicode support and language features, on the corresponding base name of the \mtbox{currentFile} reference (i.e, the name without the associated extension) as a string.

\begin{description}
\item[\abox{options}] This option, as the name indicates, takes a list of raw command line options and appends it to the actual system call. An error is thrown if any data structure other than a proper list is provided as the value.
\end{description}

\begin{codebox}{Example}{teal}{\icnote}{white}
% arara: bibtexu: { options: [ '--language', 'fr' ] }
\end{codebox}

\item[\rulebox{clean}{Marco Daniel, Paulo Cereda}] This rule removes the provided file reference through the underlying system command, which can be \rbox{rm} in a Unix environment or \rbox{del} in Microsoft Windows. As a security lock, this rule will always throw an error if \mtbox{currentFile} is equal to \mtbox{getOriginalFile}, so the main file reference cannot be removed. It is highly recommended to use the special \abox{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.

\begin{description}
\item[\abox{extensions}] This option, as the name indicates, takes a list of extensions and constructs a new list of removals commands according to the base name of the \mtbox{currentFile} reference (i.e, the name without the associated extension) as a string concatenated with each extension from the original list as suffixes. Keep in mind that, if the special \abox{files} parameter is used with this option, the resulting list will contain the cartesian product of file base names and extensions. An error is thrown if any data structure other than a proper list is provided as the value.

\begin{messagebox}{Better safe than sorry!}{attentioncolour}{\icattention}{black}
When in doubt, always remember that the \opbox{{-}dry-run} command line option is your friend! As seen in Section~\ref{sec:options}, on page~\pageref{sec:options}, 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 \rbox{clean} directives and use as many as needed in your \TeX\ documents.
\end{messagebox}
\end{description}

\begin{codebox}{Example}{teal}{\icnote}{white}
% arara: clean: { extensions: [ aux, log ] }
\end{codebox}

\item[\rulebox{csplain}{Paulo Cereda}] This rule runs the \rbox{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 \mtbox{currentFile} reference.

\begin{description}
\item[\abox{interaction}] This option alters the underlying engine behaviour. When such option is omitted, \TeX\ will prompt the user for interaction in the event of an error. Possible values are, in order of increasing user interaction (courtesy of our master Enrico Gregorio):

\begin{description}
\item[\povalue{batchmode}] In this mode, nothing is printed on the terminal, and errors are scrolled as if the \rbox{return} key is hit at every error. Missing files that \TeX\ tries to input or request from keyboard input cause the job to abort.

\item[\povalue{nonstopmode}] In this mode, the diagnostic message will appear on the terminal, but there is no possibility of user interaction just like in batch mode, previously described.

\item[\povalue{scrollmode}] In this mode, as the name indicates, \TeX\ will stop only for missing files to input or if proper keyboard input is necessary. \TeX\ fixes errors itself.

\item[\povalue{errorstopmode}] In this mode, \TeX\ will stop at each error, asking for proper user intervention. This is the most user interactive mode available.
\end{description}

\item[\rpsbox{shell}] This option sets whether the possibility of running underlying system commands from within \TeX\ is activated.

\item[\rpsbox{synctex}] This option sets whether \rbox{synctex}, an input and output synchronization feature that allows navigation from source to typeset material and vice versa, available in most \TeX\ engines, is activated.

\item[\rpsbox{draft}] This option sets whether the draft mode, i.e, a mode that produces no output, so the engine can check the syntax, is activated.

\item[\abox{options}] This option, as the name indicates, takes a list of raw command line options and appends it to the actual system call. An error is thrown if any data structure other than a proper list is provided as the value.
\end{description}

\begin{codebox}{Example}{teal}{\icnote}{white}
% arara: csplain: { interaction: batchmode, shell: yes }
\end{codebox}

\item[\rulebox{datatooltk}{Nicola Talbot, Paulo Cereda}] This rule runs \rbox{datatooltk}, an application that creates \rbox{datatool} databases in raw format from several structured data formats, in batch mode. This rule requires \abox{output} and one of the import options.

\begin{description}
\item[\abox{output}~\rqbox] This option provides the database name to be saved as output. To guard against accidentally overwriting a document file, \rbox{datatooltk} now forbids the \rbox{tex} extension for output files. This option is required.

\item[\abox{csv}] This option, as the name indicates, imports data from the \rbox{csv} file reference provided as a plain string value.

\item[\abox{sep}] This option specifies the character used to separate values in the \rbox{csv} file. Defaults to a comma.

\item[\abox{delim}] This option specifies the character used to delimit values in the \rbox{csv} file. Defaults to a double quote.

\item[\abox{name}] This option, as the name indicates, sets the label reference of the newly created database according to the provided value.

\item[\abox{sql}] This option imports data from an \gls{SQL} database where the provided value refers to a proper \rbox{select} \gls{SQL} statement.

\item[\abox{sqldb}] This option, as the name indicates, sets the name of the \gls{SQL} database according to the provided value.

\item[\abox{sqluser}] This option, as the name indicates, sets the name of the \gls{SQL} user according to the provided value.

\item[\rpbox{noconsole}{gui}] This action dictates the password request action if such information was not provided earlier. If there is no console available, the action is determined by the following values:

\begin{description}
\item[\povalue{error}] As the name indicates, this action issues an error when no password was previously provided through the proper option.

\item[\povalue{stdin}] This action requests the password via the standard input stream, which is less secure than using a console.

\item[\povalue{gui}] This action displays a dialog box in which the user can enter the password for the \gls{SQL} database.
\end{description}

\item[\abox{probsoln}] This option, as the name indicates, imports data in the \rbox{probsoln} format from the file name provided as the value.

\item[\abox{input}] This option, as the name indicates, imports data in the \rbox{datatool} format from the file name provided as the value.

\item[\abox{sort}] This option, as the name indicates, sorts the database according to the column whose label is provided as the value. The value may be preceded by \rbox{+} or \rbox{-} to indicate ascending or descending order, respectively. If the sign is omitted, ascending is assumed.

\item[\abox{sortlocale}] This option, as the name indicates, sorts the database according to alphabetical order rules of the locale provided as the value. If the value is set to \rbox{none} strings are sorted according to non-locale letter order.

\item[\rpsbox{sortcase}] This option sets whether strings will be sorted using case-sensitive comparison for non-locale letter ordering. The default behaviour is case-insensitive.

\item[\abox{seed}] This option, as the name indicates, sets the random generator seed to the provided value. The seed is cleared if an empty value is provided.

\item[\rpsbox{shuffle}] This option sets whether the database will be properly shuffled. Shuffle is always performed after sort, regardless of the option order.

\item[\rpsbox{csvheader}] This option sets whether the \rbox{csv} file has a header row. The
spreadsheet import functions also use this setting.

\item[\rpsbox{debug}] This option, as the name indicates, sets whether the debug mode of \rbox{datatooltk} is activated. The debug mode is disabled by default.

\item[\rpsbox{owneronly}] This option sets whether read and write permissions when saving \rbox{dbtex} files should be defined for the owner only. This option has no effect on some operating systems.

\item[\rpsbox{maptex}] This option sets whether \TeX\ special characters will be properly mapped when importing data from \rbox{csv} files or \gls{SQL} databases.

\item[\abox{xls}] This option, as the name indicates, imports data from a Microsoft Excel \rbox{xls} file reference provided as a plain string value.

\item[\abox{ods}] This option, as the name indicates, imports data from an Open Document Spreadsheet \rbox{ods} file reference provided as a plain string value.

\item[\abox{sheet}] This option specifies the sheet to select from the Excel workbook or Open Document Spreadsheet. This may either be an index or the name of the sheet.

\item[\abox{filterop}] This option specifies the logical operator to be associated with a given filter. Filtering is always performed after sorting and shuffling. Possible values are:

\begin{description}
\item[\povalue{or}\hfill\hphantom{w}] This value, as the name indicates, uses the logical \rbox{or} operator when filtering. This is the default behaviour. Note that this value has no effect if only one filter is supplied.

\item[\povalue{and}] This value, as the name indicates, uses the logical \rbox{and} operator when filtering. Note that this value has no effect if only one filter is supplied.
\end{description}

\item[\abox{filters}] This option takes a list and sets up a sequence of filters. Each element from the provided list must be another list of exactly three entries representing a key, an operator and a value, respectively.

\item[\abox{truncate}] This option truncates the database to the number of rows provided as the value. Truncation is always performed after any sorting, shuffling and filtering, but before column removal.
\end{description}

\begin{codebox}{Example}{teal}{\icnote}{white}
% arara: datatooltk: {
% arara: --> output: books.dbtex,
% arara: --> csv: booklist.csv }
\end{codebox}

\item[\rulebox{dvipdfm}{Marco Daniel, Paulo Cereda}] This rule runs \rbox{dvipdfm}, a command line utility for file format translation, on the corresponding base name of the \mtbox{currentFile} reference (i.e, the name without the associated extension) as a string concatenated with the \rbox{dvi} suffix, generating a Portable Document Format \rbox{pdf} file.

\begin{description}
\item[\abox{output}] This option, as the name indicates, sets the output name for the generated \rbox{pdf} file. There is no need to provide an extension, as the value is always normalized with \mtbox{getBasename} such that only the name without the associated extension is used. The base name of the current file reference is used as the default value.

\item[\abox{options}] This option, as the name indicates, takes a list of raw command line options and appends it to the actual system call. An error is thrown if any data structure other than a proper list is provided as the value.
\end{description}

\begin{codebox}{Example}{teal}{\icnote}{white}
% arara: dvipdfm: { output: thesis }
\end{codebox}

\item[\rulebox{dvipdfmx}{Marco Daniel, Paulo Cereda}] This rule runs \rbox{dvipdfmx}, an extended version of \rbox{dvipdfm} created to support multibyte character encodings and large character sets for East Asian languages, on the corresponding base name of the \mtbox{currentFile} reference (i.e, the name without the associated extension) as a string concatenated with the \rbox{dvi} suffix, generating a Portable Document Format \rbox{pdf} file.

\begin{description}
\item[\abox{output}] This option, as the name indicates, sets the output name for the generated \rbox{pdf} file. There is no need to provide an extension, as the value is always normalized with \mtbox{getBasename} such that only the name without the associated extension is used. The base name of the current file reference is used as the default value.

\item[\abox{options}] This option, as the name indicates, takes a list of raw command line options and appends it to the actual system call. An error is thrown if any data structure other than a proper list is provided as the value.
\end{description}

\begin{codebox}{Example}{teal}{\icnote}{white}
% arara: dvipdfmx: { options: [ '-K', '40' ] }
\end{codebox}

\item[\rulebox{dvips}{Marco Daniel, Paulo Cereda}] This rule runs \rbox{dvips} on the corresponding base name of the \mtbox{currentFile} reference (i.e, the name without the associated extension) as a string concatenated with the \rbox{dvi} suffix, generating a PostScript \rbox{ps} file.

\begin{description}
\item[\abox{output}] This option, as the name indicates, sets the output name for the generated \rbox{ps} file. There is no need to provide an extension, as the value is always normalized with \mtbox{getBasename} such that only the name without the associated extension is used. The base name of the current file reference is used as the default value.

\item[\abox{options}] This option, as the name indicates, takes a list of raw command line options and appends it to the actual system call. An error is thrown if any data structure other than a proper list is provided as the value.
\end{description}

\begin{codebox}{Example}{teal}{\icnote}{white}
% arara: dvips: { output: thesis }
\end{codebox}

\item[\rulebox{dvipspdf}{Marco Daniel, Paulo Cereda}] This rule runs \rbox{dvips} in order to obtain a corresponding \rbox{ps} file from the initial \rbox{dvi} reference, and then runs \rbox{ps2pdf} on the previously generated \rbox{ps} file in order to obtain a \rbox{pdf} file. Note that all base names are acquired from the \mtbox{currentFile} reference (i.e, the name without the associated extension) and used to construct the resulting files.

\begin{description}
\item[\abox{output}] This option, as the name indicates, sets the output name for the generated \rbox{pdf} file. There is no need to provide an extension, as the value is always normalized with \mtbox{getBasename} such that only the name without the associated extension is used. The base name of the current file reference is used as the default value.

\item[\abox{options1}] This option, as the name indicates, takes a list of raw command line options and appends it to the \rbox{dvips} program call. An error is thrown if any data structure other than a proper list is provided as the value.

\item[\abox{options2}] This option, as the name indicates, takes a list of raw command line options and appends it to the \rbox{ps2pdf} program call. An error is thrown if any data structure other than a proper list is provided as the value.
\end{description}

\begin{codebox}{Example}{teal}{\icnote}{white}
% arara: dvipspdf: { output: article }
\end{codebox}

\item[\rulebox{dvisvgm}{samcarter}] This rule runs \rbox{dvisvgm} in order to obtain a corresponding \rbox{svg} file, a vector graphics format based on XML, from the initial \rbox{dvi} reference. It is important to observe that the base name is acquired from the \mtbox{currentFile} reference (i.e, the name without the associated extension) and used to construct the resulting file.

\begin{description}
\item[\abox{options}] This option, as the name indicates, takes a list of raw command line options and appends it to the actual system call. An error is thrown if any data structure other than a proper list is provided as the value.
\end{description}

\begin{codebox}{Example}{teal}{\icnote}{white}
% arara: dvisvgm
\end{codebox}

\item[\rulebox{etex}{Marco Daniel, Paulo Cereda, Nicola Talbot}] This rule runs the \rbox{etex} extended (plain) \TeX\ engine on the provided \mtbox{currentFile} reference, generating a corresponding file in a device independent format.

\begin{description}
\item[\abox{interaction}] This option alters the underlying engine behaviour. If this option is omitted, \TeX\ will prompt the user for interaction in the event of an error. Possible values are, in order of increasing user interaction (courtesy of our master Enrico Gregorio):

\begin{description}
\item[\povalue{batchmode}] In this mode, nothing is printed on the terminal, and errors are scrolled as if the \rbox{return} key is hit at every error. Missing files that \TeX\ tries to input or request from keyboard input cause the job to abort.

\item[\povalue{nonstopmode}] In this mode, the diagnostic message will appear on the terminal, but there is no possibility of user interaction just like in batch mode, previously described.

\item[\povalue{scrollmode}] In this mode, as the name indicates, \TeX\ will stop only for missing files to input or if proper keyboard input is necessary. \TeX\ fixes errors itself.

\item[\povalue{errorstopmode}] In this mode, \TeX\ will stop at each error, asking for proper user intervention. This is the most user interactive mode available.
\end{description}

\item[\rpsbox{shell}] This option sets whether the possibility of running underlying system commands from within \TeX\ is activated.

\item[\abox{options}] This option, as the name indicates, takes a list of raw command line options and appends it to the actual system call. An error is thrown if any data structure other than a proper list is provided as the value.
\end{description}

\begin{codebox}{Example}{teal}{\icnote}{white}
% arara: etex: { shell: yes }
\end{codebox}

\item[\rulebox{frontespizio}{Francesco Endrici, Enrico Gregorio, Paulo Cereda}] This rule automates the steps required by the \rbox{frontespizio} package in order to help Italian users generate the frontispiece to their thesis. First and foremost, the frontispiece is generated. If \rbox{latex} is used as the underlying engine, there is an additional intermediate conversion step to a proper \rbox{eps} file. Finally, the final document is compiled.

\begin{description}
\item[\rpbox{engine}{pdflatex}] This option, as the name indicates, sets the underlying \TeX\ engine to be used for both compilations (the frontispiece and the document itself). Possible values are:

\begin{description}
\item[\povalue{latex}] This value, as the name indicates, sets the underlying \TeX\ engine to \rbox{latex} for both compilations (frontispiece and document).

\item[\povalue{pdflatex}] This value, as the name indicates, sets the underlying \TeX\ engine to \rbox{pdflatex} for both compilations (frontispiece and document).

\item[\povalue{xelatex}] This value, as the name indicates, sets the underlying \TeX\ engine to \rbox{xelatex} for both compilations (frontispiece and document).

\item[\povalue{lualatex}] This value, as the name indicates, sets the underlying \TeX\ engine to \rbox{lualatex} for both compilations (frontispiece and document).
\end{description}

\item[\rpsbox{shell}] This option sets whether the possibility of running underlying system commands from within the selected \TeX\ engine is activated.

\item[\abox{interaction}] This option alters the underlying engine behaviour. If this option is omitted, \TeX\ will prompt the user for interaction in the event of an error. Possible values are, in order of increasing user interaction (courtesy of our master Enrico Gregorio):

\begin{description}
\item[\povalue{batchmode}] In this mode, nothing is printed on the terminal, and errors are scrolled as if the \rbox{return} key is hit at every error. Missing files that \TeX\ tries to input or request from keyboard input cause the job to abort.

\item[\povalue{nonstopmode}] In this mode, the diagnostic message will appear on the terminal, but there is no possibility of user interaction just like in batch mode, previously described.

\item[\povalue{scrollmode}] In this mode, as the name indicates, \TeX\ will stop only for missing files to input or if proper keyboard input is necessary. \TeX\ fixes errors itself.

\item[\povalue{errorstopmode}] In this mode, \TeX\ will stop at each error, asking for proper user intervention. This is the most user interactive mode available.
\end{description}

\item[\abox{options}] This option, as the name indicates, takes a list of raw command line options and appends it to the actual \TeX\ engine call. An error is thrown if any data structure other than a proper list is provided as the value.
\end{description}

\begin{codebox}{Example}{teal}{\icnote}{white}
% arara: frontespizio: { engine: xelatex,
% arara: --> shell: yes, interaction: nonstopmode }
\end{codebox}

\item[\rulebox{halt}{Heiko Oberdiek, Paulo Cereda}] This rule, as the name suggests, calls the \rbox{halt} trigger, which stops the current interpretation workflow, such that subsequent directives are ignored. This rule contains no associated options. Please refer to Section~\ref{sec:commandsandtriggers}, on page~\pageref{sec:commandsandtriggers}, for more information on triggers.

\begin{codebox}{Example}{teal}{\icnote}{white}
% arara: halt
\end{codebox}

\item[\rulebox{indent}{Chris Hughes, Paulo Cereda}] This rule runs \rbox{latexindent}, a Perl script that indents \TeX\ files according to an indentation scheme, on the provided \mtbox{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.

\begin{description}
\item[\rpsbox{silent}] This option, as the name indicates, sets whether the script will operate in silent mode, in which no output is given to the terminal.

\item[\rpsbox{overwrite}] This option, as the name indicates, sets whether the \mtbox{currentFile} reference will be overwritten. If activated, a copy will be made before the actual indentation process. 

\item[\abox{trace}] This option, as the name indicates, enables the script tracing mode, such that a verbose output will be given to the \rbox{indent.log} log file. Possible values are:

\begin{description}
\item[\povalue{default}] This value, as the name indicates, refers to the default tracing level. Note that, especially for large files, this value does affect performance of the script.

\item[\povalue{complete}] This value, as the name indicates, refers to the detailed, complete tracing level. Note that, especially for large files, performance of the script will be significantly affected when this value is used.
\end{description}

\item[\rpsbox{screenlog}] This option, as the name indicates, sets whether \rbox{latexindent} will output the log file to the screen, as well as to the specified log file.

\item[\rpsbox{modifylinebreaks}] This option, as the name indicates, sets whether the script will modify line breaks, according to specifications written in a configuration file.

\item[\abox{cruft}] This option sets the provided value as a cruft location in which the script will write backup and log files. The default behaviour sets the working directory as cruft location.

\item[\abox{logfile}] This option, as the name indicates, sets the name of the log file generated by \rbox{latexindent} according to the provided value.

\item[\abox{output}] This option, as the name indicates, sets the name of the output file. Please note that this option has higher priority over some switches, so options like \abox{overwrite} will be ignored by the underlying script.

\item[\abox{options}] This option, as the name indicates, takes a list of raw command line options and appends it to the actual script call. An error is thrown if any data structure other than a proper list is provided as the value.

\item[\abox{settings}] This option, as the name indicates, dictates the indentation settings to be applied in the current script execution. Two possible values are available:

\begin{description}
\item[\povalue{local}] This value, as the name implies, acts a switch to indicate a local configuration. In this scenario, the script will look for a proper settings file in the same directory as the \mtbox{currentFile} reference and add the corresponding content to the indentation scheme. Optionally, a file location can be specified as well. Please refer to the \abox{where} option for more details on such feature.

\item[\povalue{onlydefault}] This value, as the name indicates, ignores any local configuration, so the script will resort to the default indentation behaviour.
\end{description}

\item[\abox{where}] This option, as the name indicates, sets the file location containing the indentation settings according to the provided value. This option can only be used if, and only if, \rbox[cyan]{local} is set as the value for the \abox{settings} option, otherwise the rule will throw an error.

\item[\abox{replacement}] This option, as the name indicates, implements the replacement mode switches. Three possible values are available:

\begin{description}
\item[\povalue{full}] This value, as the name indicates, performs indentation and replacements, not respecting verbatim code blocks.

\item[\povalue{noverb}] This value, as the name indicates, performs indentation and replacements, and will respect verbatim code blocks.

\item[\povalue{noindent}] This value, as the name implies, will not perform indentation, and will perform replacements not respecting verbatim code blocks.
\end{description}
\end{description}

\begin{codebox}{Example}{teal}{\icnote}{white}
% arara: indent: { overwrite: yes }
\end{codebox}

\item[\rulebox{latex}{Marco Daniel, Paulo Cereda}] This rule runs the \rbox{latex} \TeX\ engine on the provided \mtbox{currentFile} reference, generating a corresponding file in a device independent format.

\begin{description}
\item[\abox{interaction}] This option alters the underlying engine behaviour. If this option is omitted, \TeX\ will prompt the user for interaction in the event of an error. Possible values are, in order of increasing user interaction (courtesy of our master Enrico Gregorio):

\begin{description}
\item[\povalue{batchmode}] In this mode, nothing is printed on the terminal, and errors are scrolled as if the \rbox{return} key is hit at every error. Missing files that \TeX\ tries to input or request from keyboard input cause the job to abort.

\item[\povalue{nonstopmode}] In this mode, the diagnostic message will appear on the terminal, but there is no possibility of user interaction just like in batch mode, previously described.

\item[\povalue{scrollmode}] In this mode, as the name indicates, \TeX\ will stop only for missing files to input or if proper keyboard input is necessary. \TeX\ fixes errors itself.

\item[\povalue{errorstopmode}] In this mode, \TeX\ will stop at each error, asking for proper user intervention. This is the most user interactive mode available.
\end{description}

\item[\rpsbox{shell}] This option sets whether the possibility of running underlying system commands from within \TeX\ is activated.

\item[\rpsbox{synctex}] This option sets whether \rbox{synctex}, an input and output synchronization feature that allows navigation from source to typeset material and vice versa, available in most \TeX\ engines, is activated.

\item[\rpsbox{draft}] This option sets whether the draft mode, i.e, a mode that produces no output, so the engine can check the syntax, is activated.

\item[\abox{options}] This option, as the name indicates, takes a list of raw command line options and appends it to the actual system call. An error is thrown if any data structure other than a proper list is provided as the value.
\end{description}

\begin{codebox}{Example}{teal}{\icnote}{white}
% arara: latex: { interaction: scrollmode, draft: yes }
\end{codebox}

\item[\rulebox{latexmk}{Marco Daniel, Brent Longborough, Paulo Cereda}] This rule runs \rbox{latexmk}, a fantastic command line tool for fully automated \TeX\ document generation, on the provided \mtbox{currentFile} reference.

\begin{description}
\item[\abox{clean}] This option, as the name indicates, removes all temporary files generated after a sequence of intermediate calls for document generation. Two possible values are available:

\begin{description}
\item[\povalue{all}] This value, as the name indicates, removes all temporary, intermediate files, as well as resulting, final formats such as PostScript and Portable Document File. Only relevant source files are kept.

\item[\povalue{partial}] This value, as the name indicates, removes all temporary, intermediate files and keeps the resulting, final formats such as PostScript and Portable Document File.
\end{description}

\item[\abox{engine}] This option, as the name indicates, sets the underlying \TeX\ engine of \rbox{latexmk} to be used for the compilation sequence. Possible values are:

\begin{description}
\item[\povalue{latex}] This value, as the name indicates, sets the underlying \TeX\ engine of the script to \rbox{latex} for the compilation sequence.

\item[\povalue{pdflatex}] This value, as the name indicates, sets the underlying \TeX\ engine of the script to \rbox{pdflatex} for the compilation sequence.

\item[\povalue{xelatex}] This value, as the name indicates, sets the underlying \TeX\ engine of the script to \rbox{xelatex} for the compilation sequence.

\item[\povalue{lualatex}] This value, as the name indicates, sets the underlying \TeX\ engine of the script to \rbox{lualatex} for the compilation sequence.
\end{description}

\item[\abox{program}] This option, as the name suggests, sets the \TeX\ engine according to the provided value. It is important to note that this option has higher priority over \abox{engine} values, so the latter will be discarded.

\item[\abox{options}] This option, as the name indicates, takes a list of raw command line options and appends it to the actual script call. An error is thrown if any data structure other than a proper list is provided as the value.
\end{description}

\begin{codebox}{Example}{teal}{\icnote}{white}
% arara: latexmk: { engine: pdflatex }
\end{codebox}

\item[\rulebox{lualatex}{Marco Daniel, Paulo Cereda}] This rule runs the new \rbox{lualatex} \TeX\ engine on the provided \mtbox{currentFile} reference, generating a corresponding file in the Portable Document File format, as expected.

\begin{description}
\item[\abox{interaction}] This option alters the underlying engine behaviour. If this option is omitted, \TeX\ will prompt the user for interaction in the event of an error. Possible values are, in order of increasing user interaction (courtesy of our master Enrico Gregorio):

\begin{description}
\item[\povalue{batchmode}] In this mode, nothing is printed on the terminal, and errors are scrolled as if the \rbox{return} key is hit at every error. Missing files that \TeX\ tries to input or request from keyboard input cause the job to abort.

\item[\povalue{nonstopmode}] In this mode, the diagnostic message will appear on the terminal, but there is no possibility of user interaction just like in batch mode, previously described.

\item[\povalue{scrollmode}] In this mode, as the name indicates, \TeX\ will stop only for missing files to input or if proper keyboard input is necessary. \TeX\ fixes errors itself.

\item[\povalue{errorstopmode}] In this mode, \TeX\ will stop at each error, asking for proper user intervention. This is the most user interactive mode available.
\end{description}

\item[\rpsbox{shell}] This option sets whether the possibility of running underlying system commands from within \TeX\ is activated.

\item[\rpsbox{synctex}] This option sets whether \rbox{synctex}, an input and output synchronization feature that allows navigation from source to typeset material and vice versa, available in most \TeX\ engines, is activated.

\item[\rpsbox{draft}] This option sets whether the draft mode, i.e, a mode that produces no output, so the engine can check the syntax, is activated.

\item[\abox{options}] This option, as the name indicates, takes a list of raw command line options and appends it to the actual system call. An error is thrown if any data structure other than a proper list is provided as the value.
\end{description}

\begin{codebox}{Example}{teal}{\icnote}{white}
% arara: lualatex: { interaction: errorstopmode,
% arara: --> synctex: yes }
\end{codebox}

\item[\rulebox{luatex}{Marco Daniel, Paulo Cereda}] This rule runs the \rbox{luatex} \TeX\ engine on the provided \mtbox{currentFile} reference, generating a corresponding file in the Portable Document File format, as expected.

\begin{description}
\item[\abox{interaction}] This option alters the underlying engine behaviour. If this option is omitted, \TeX\ will prompt the user for interaction in the event of an error. Possible values are, in order of increasing user interaction (courtesy of our master Enrico Gregorio):

\begin{description}
\item[\povalue{batchmode}] In this mode, nothing is printed on the terminal, and errors are scrolled as if the \rbox{return} key is hit at every error. Missing files that \TeX\ tries to input or request from keyboard input cause the job to abort.

\item[\povalue{nonstopmode}] In this mode, the diagnostic message will appear on the terminal, but there is no possibility of user interaction just like in batch mode, previously described.

\item[\povalue{scrollmode}] In this mode, as the name indicates, \TeX\ will stop only for missing files to input or if proper keyboard input is necessary. \TeX\ fixes errors itself.

\item[\povalue{errorstopmode}] In this mode, \TeX\ will stop at each error, asking for proper user intervention. This is the most user interactive mode available.
\end{description}

\item[\rpsbox{shell}] This option sets whether the possibility of running underlying system commands from within \TeX\ is activated.

\item[\rpsbox{synctex}] This option sets whether \rbox{synctex}, an input and output synchronization feature that allows navigation from source to typeset material and vice versa, available in most \TeX\ engines, is activated.

\item[\rpsbox{draft}] This option sets whether the draft mode, i.e, a mode that produces no output, so the engine can check the syntax, is activated.

\item[\abox{options}] This option, as the name indicates, takes a list of raw command line options and appends it to the actual system call. An error is thrown if any data structure other than a proper list is provided as the value.
\end{description}

\begin{codebox}{Example}{teal}{\icnote}{white}
% arara: luatex: { interaction: batchmode,
% arara: --> shell: yes, draft: yes }
\end{codebox}

\item[\rulebox{make}{Marco Daniel, Paulo Cereda}] This rule runs \rbox{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.

\begin{description}
\item[\abox{targets}] This option takes a list of targets. Note that \rbox{make} updates a target if it depends on files that have been modified since the target was last modified, or if the target does not exist.

\item[\abox{options}] This option, as the name indicates, takes a list of raw command line options and appends it to the actual system call. An error is thrown if any data structure other than a proper list is provided as the value.
\end{description}

\begin{codebox}{Example}{teal}{\icnote}{white}
% arara: make: { targets: [ compile, package ] }
\end{codebox}

\item[\rulebox{makeglossaries}{Marco Daniel, Nicola Talbot, Paulo Cereda}] This rule runs \rbox{makeglossaries}, an efficient Perl script designed for use with \TeX\ documents that work with the \rbox{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 \mtbox{currentFile} reference (i.e, the name without the associated extension) as the mandatory argument.

\begin{description}
\item[\abox{options}] This option, as the name indicates, takes a list of raw command line options and appends it to the actual script call. An error is thrown if any data structure other than a proper list is provided as the value.
\end{description}

\begin{codebox}{Example}{teal}{\icnote}{white}
% arara: makeglossaries if found('aux', '@istfilename')
\end{codebox}

\item[\rulebox{makeglossarieslite}{Marco Daniel, Nicola Talbot, Paulo Cereda}] This rule runs \rbox{makeglossaries-lite}, a lightweight Lua script designed for use with \TeX\ documents that work with the \rbox{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 \mtbox{currentFile} reference (i.e, the name without the associated extension) as the mandatory argument.

\begin{description}
\item[\abox{options}] This option, as the name indicates, takes a list of raw command line options and appends it to the actual script call. An error is thrown if any data structure other than a proper list is provided as the value.
\end{description}

\begin{codebox}{Example}{teal}{\icnote}{white}
% arara: makeglossarieslite if found('aux', '@istfilename')
\end{codebox}

\item[\rulebox{makeindex}{Marco Daniel, Paulo Cereda}] This rule runs \rbox{makeindex}, a general purpose hierarchical index generator, on the corresponding base name of the \mtbox{currentFile} reference (i.e, the name without the associated extension) as a string concatenated with the \rbox{idx} suffix, generating an index as a special \rbox{ind} file.

\begin{description}
\item[\abox{style}] This option, as the name indicates, sets the underlying index style file. Make sure to provide a valid \rbox{ist} file when using this option.

\item[\rpsbox{german}] This option, as the name indicates, sets whether German word ordering should be used when generating the index, according to the rules set forth in DIN 5007.

\item[\abox{order}] This option, as the name indicates, sets the default ordering scheme for the \rbox{makeindex} program. Two possible values are available:

\begin{description}
\item[\povalue{letter}] This value, as the name indicates, activates the letter ordering scheme. In such scheme, a blank space does not precede any letter in the alphabet. 

\item[\povalue{word}] This value, as the name indicates, activates the word ordering scheme. In such scheme, a blank space precedes any letter in the alphabet.
\end{description}

\item[\rpbox{input}{idx}] This option, as the name indicates, sets the default extension for the input file, according to the provided value. Later, this value will be concatenated as a suffix for the base name of the \mtbox{currentFile} reference (i.e, the name without the associated extension).

\item[\rpbox{output}{ind}] This option, as the name indicates, sets the default extension for the output file, according to the provided value. Later, this value will be concatenated as a suffix for the base name of the \mtbox{currentFile} reference (i.e, the name without the associated extension).

\item[\rpbox{log}{ilg}] This option, as the name indicates, sets the default extension for the log file, according to the provided value. Later, this value will be concatenated as a suffix for the base name of the \mtbox{currentFile} reference (i.e, the name without the associated extension).

\item[\abox{options}] This option, as the name indicates, takes a list of raw command line options and appends it to the actual system call. An error is thrown if any data structure other than a proper list is provided as the value.
\end{description}

\begin{codebox}{Example}{teal}{\icnote}{white}
% arara: makeindex: { style: book.ist }
\end{codebox}

\item[\rulebox{nomencl}{Marco Daniel, Nicola Talbot, Paulo Cereda}] This rule runs \rbox{makeindex} in order to automatically generate a nomenclature list from \TeX\ documents that work with the \rbox{nomencl} package. The program itself is a general purpose hierarchical index generator and takes the corresponding base name of the \mtbox{currentFile} reference (i.e, the name without the associated extension) as a string concatenated with the \rbox{nlo} suffix and a special style file in order to generate the nomenclature list as a special \rbox{nls} file.

\begin{description}
\item[\rpbox{style}{nomencl.ist}] This option, as the name indicates, sets the underlying index style file. The default value is set to the one automatically provided by the \rbox{nomencl} package, so it is highly recommended to not override it.

\item[\abox{options}] This option, as the name indicates, takes a list of raw command line options and appends it to the actual system call. An error is thrown if any data structure other than a proper list is provided as the value.
\end{description}

\begin{codebox}{Example}{teal}{\icnote}{white}
% arara: nomencl
\end{codebox}

\item[\rulebox{pdfcsplain}{Paulo Cereda}] This rule runs the \rbox{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 \mtbox{currentFile} reference.

\begin{description}
\item[\abox{interaction}] This option alters the underlying engine behaviour. If this option is omitted, \TeX\ will prompt the user for interaction in the event of an error. Possible values are, in order of increasing user interaction (courtesy of our master Enrico Gregorio):

\begin{description}
\item[\povalue{batchmode}] In this mode, nothing is printed on the terminal, and errors are scrolled as if the \rbox{return} key is hit at every error. Missing files that \TeX\ tries to input or request from keyboard input cause the job to abort.

\item[\povalue{nonstopmode}] In this mode, the diagnostic message will appear on the terminal, but there is no possibility of user interaction just like in batch mode, previously described.

\item[\povalue{scrollmode}] In this mode, as the name indicates, \TeX\ will stop only for missing files to input or if proper keyboard input is necessary. \TeX\ fixes errors itself.

\item[\povalue{errorstopmode}] In this mode, \TeX\ will stop at each error, asking for proper user intervention. This is the most user interactive mode available.
\end{description}

\item[\rpsbox{shell}] This option sets whether the possibility of running underlying system commands from within \TeX\ is activated.

\item[\rpsbox{synctex}] This option sets whether \rbox{synctex}, an input and output synchronization feature that allows navigation from source to typeset material and vice versa, available in most \TeX\ engines, is activated.

\item[\rpsbox{draft}] This option sets whether the draft mode, i.e, a mode that produces no output, so the engine can check the syntax, is activated.

\item[\abox{options}] This option, as the name indicates, takes a list of raw command line options and appends it to the actual system call. An error is thrown if any data structure other than a proper list is provided as the value.
\end{description}

\begin{codebox}{Example}{teal}{\icnote}{white}
% arara: pdfcsplain: { shell: yes, synctex: yes }
\end{codebox}

\item[\rulebox{pdflatex}{Marco Daniel, Paulo Cereda}] This rule runs the \rbox{pdflatex} \TeX\ engine on the provided \mtbox{currentFile} reference, generating a corresponding file in the Portable Document File format, as expected.

\begin{description}
\item[\abox{interaction}] This option alters the underlying engine behaviour. If this option is omitted, \TeX\ will prompt the user for interaction in the event of an error. Possible values are, in order of increasing user interaction (courtesy of our master Enrico Gregorio):

\begin{description}
\item[\povalue{batchmode}] In this mode, nothing is printed on the terminal, and errors are scrolled as if the \rbox{return} key is hit at every error. Missing files that \TeX\ tries to input or request from keyboard input cause the job to abort.

\item[\povalue{nonstopmode}] In this mode, the diagnostic message will appear on the terminal, but there is no possibility of user interaction just like in batch mode, previously described.

\item[\povalue{scrollmode}] In this mode, as the name indicates, \TeX\ will stop only for missing files to input or if proper keyboard input is necessary. \TeX\ fixes errors itself.

\item[\povalue{errorstopmode}] In this mode, \TeX\ will stop at each error, asking for proper user intervention. This is the most user interactive mode available.
\end{description}

\item[\rpsbox{shell}] This option sets whether the possibility of running underlying system commands from within \TeX\ is activated.

\item[\rpsbox{synctex}] This option sets whether \rbox{synctex}, an input and output synchronization feature that allows navigation from source to typeset material and vice versa, available in most \TeX\ engines, is activated.

\item[\rpsbox{draft}] This option sets whether the draft mode, i.e, a mode that produces no output, so the engine can check the syntax, is activated.

\item[\abox{options}] This option, as the name indicates, takes a list of raw command line options and appends it to the actual system call. An error is thrown if any data structure other than a proper list is provided as the value.
\end{description}

\begin{codebox}{Example}{teal}{\icnote}{white}
% arara: pdflatex: { interaction: batchmode }
% arara: --> if missing('pdf') || changed('tex')
\end{codebox}

\item[\rulebox{pdftex}{Marco Daniel, Paulo Cereda}] This rule runs the \rbox{pdftex} \TeX\ engine on the provided \mtbox{currentFile} reference, generating a corresponding file in the Portable Document File format, as expected.

\begin{description}
\item[\abox{interaction}] This option alters the underlying engine behaviour. If this option is omitted, \TeX\ will prompt the user for interaction in the event of an error. Possible values are, in order of increasing user interaction (courtesy of our master Enrico Gregorio):

\begin{description}
\item[\povalue{batchmode}] In this mode, nothing is printed on the terminal, and errors are scrolled as if the \rbox{return} key is hit at every error. Missing files that \TeX\ tries to input or request from keyboard input cause the job to abort.

\item[\povalue{nonstopmode}] In this mode, the diagnostic message will appear on the terminal, but there is no possibility of user interaction just like in batch mode, previously described.

\item[\povalue{scrollmode}] In this mode, as the name indicates, \TeX\ will stop only for missing files to input or if proper keyboard input is necessary. \TeX\ fixes errors itself.

\item[\povalue{errorstopmode}] In this mode, \TeX\ will stop at each error, asking for proper user intervention. This is the most user interactive mode available.
\end{description}

\item[\rpsbox{shell}] This option sets whether the possibility of running underlying system commands from within \TeX\ is activated.

\item[\rpsbox{synctex}] This option sets whether \rbox{synctex}, an input and output synchronization feature that allows navigation from source to typeset material and vice versa, available in most \TeX\ engines, is activated.

\item[\rpsbox{draft}] This option sets whether the draft mode, i.e, a mode that produces no output, so the engine can check the syntax, is activated.

\item[\abox{options}] This option, as the name indicates, takes a list of raw command line options and appends it to the actual system call. An error is thrown if any data structure other than a proper list is provided as the value.
\end{description}

\begin{codebox}{Example}{teal}{\icnote}{white}
% arara: pdftex: { draft: yes }
\end{codebox}

\item[\rulebox{pdftk}{Nicola Talbot, Paulo Cereda}] This rule runs \rbox{pdftk}, a command line tool for manipulating Portable Document Format documents, on the corresponding base name of the \mtbox{currentFile} reference (i.e, the name without the associated extension) as a string concatenated with the \rbox{pdf} suffix.

\begin{description}
\item[\abox{options}] This option, as the name indicates, takes a list of raw command line options and appends it to the actual system call. An error is thrown if any data structure other than a proper list is provided as the value.
\end{description}

\begin{codebox}{Example}{teal}{\icnote}{white}
% arara: pdftk: { options: [ burst ] }
\end{codebox}

\item[\rulebox{ps2pdf}{Marco Daniel, Paulo Cereda}] This rule runs \rbox{ps2pdf}, a tool that converts PostScript to Portable Document File, on the corresponding base name of the \mtbox{currentFile} reference (i.e, the name without the associated extension) as a string concatenated with the \rbox{ps} suffix.

\begin{description}
\item[\abox{output}] This option, as the name indicates, sets the output name for the generated \rbox{pdf} file. There is no need to provide an extension, as the value is always normalized with \mtbox{getBasename} such that only the name without the associated extension is used. The base name of the current file reference is used as the default value.

\item[\abox{options}] This option, as the name indicates, takes a list of raw command line options and appends it to the actual system call. An error is thrown if any data structure other than a proper list is provided as the value.
\end{description}

\begin{codebox}{Example}{teal}{\icnote}{white}
% arara: ps2pdf: { output: article }
\end{codebox}

\item[\rulebox{sketch}{Sergey Ulyanov, Paulo Cereda}] This rule runs \rbox{sketch}, a system for producing line drawings of solid objects and scenes, on the corresponding base name of the \mtbox{currentFile} reference (i.e, the name without the associated extension) as a string concatenated with the \rbox{sk} suffix. Note that one needs to add support for this particular file type, as seen in Section~\ref{sec:basicstructure}, on page~\pageref{sec:basicstructure}.

\begin{description}
\item[\abox{options}] This option, as the name indicates, takes a list of raw command line options and appends it to the actual system call. An error is thrown if any data structure other than a proper list is provided as the value.
\end{description}

\begin{codebox}{Example}{teal}{\icnote}{white}
% arara: sketch
\end{codebox}

\item[\rulebox{songidx}{Francesco Endrici, Paulo Cereda}] This rule runs \rbox{songidx}, a song index generation script for the \rbox{songs} package, on the file reference provided as parameter, generating a proper index as a special \rbox{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 MiK\TeX\ distributions, so a manual deployment is required. The script execution is performed by the underlying \rbox{texlua} interpreter.

\begin{description}
\item[\abox{input}~\rqbox] This required option, as the name indicates, sets the input name for the song index file specified within the \TeX\ document. There is no need to provide an extension, as the value is always normalized with \mtbox{getBasename} such that only the name without the associated extension is used.

\item[\rpbox{script}{songidx.lua}] This option, as the name indicates, sets the script path. The default value is set to the script name, so either make sure \rbox{songidx.lua} is located in the same directory of your \TeX\ document or provide the correct location (preferably a full path).

\item[\abox{options}] This option, as the name indicates, takes a list of raw command line options and appends it to the actual script call. An error is thrown if any data structure other than a proper list is provided as the value.
\end{description}

\begin{codebox}{Example}{teal}{\icnote}{white}
% arara: songidx: { input: songs }
\end{codebox}

\item[\rulebox{tex}{Marco Daniel, Paulo Cereda}] This rule runs the \rbox{tex} \TeX\ engine on the provided \mtbox{currentFile} reference, generating a corresponding file in a device independent format.

\begin{description}
\item[\abox{interaction}] This option alters the underlying engine behaviour. If this option is omitted, \TeX\ will prompt the user for interaction in the event of an error. Possible values are, in order of increasing user interaction (courtesy of our master Enrico Gregorio):

\begin{description}
\item[\povalue{batchmode}] In this mode, nothing is printed on the terminal, and errors are scrolled as if the \rbox{return} key is hit at every error. Missing files that \TeX\ tries to input or request from keyboard input cause the job to abort.

\item[\povalue{nonstopmode}] In this mode, the diagnostic message will appear on the terminal, but there is no possibility of user interaction just like in batch mode, previously described.

\item[\povalue{scrollmode}] In this mode, as the name indicates, \TeX\ will stop only for missing files to input or if proper keyboard input is necessary. \TeX\ fixes errors itself.

\item[\povalue{errorstopmode}] In this mode, \TeX\ will stop at each error, asking for proper user intervention. This is the most user interactive mode available.
\end{description}

\item[\rpsbox{shell}] This option sets whether the possibility of running underlying system commands from within \TeX\ is activated.

\item[\abox{options}] This option, as the name indicates, takes a list of raw command line options and appends it to the actual system call. An error is thrown if any data structure other than a proper list is provided as the value.
\end{description}

\begin{codebox}{Example}{teal}{\icnote}{white}
% arara: tex: { shell: yes }
\end{codebox}

\item[\rulebox{texindy}{Nicola Talbot, Paulo Cereda}] This rule runs \rbox{texindy}, a variant of the \rbox{xindy} indexing system focused on \LaTeX\ documents, on the corresponding base name of the \mtbox{currentFile} reference (i.e, the name without the associated extension) as a string concatenated with the \rbox{idx} suffix, generating an index as a special \rbox{ind} file.

\begin{description}
\item[\rpsbox{quiet}] This option, as the name indicates, sets whether the tool will output progress messages. It is important to observe that \rbox{texindy} always outputs error messages, regardless of this option.

\item[\abox{codepage}] This option, as the name indicates, specifies the encoding to be used for letter group headings. Additionally, it specifies the encoding used internally for sorting, but that does not matter for the final result.

\item[\abox{language}] This option, as the name indicates, specifies the language that dictates the rules for index sorting. These rules are encoded in a module.

\item[\abox{markup}] This option, as the name indicates, specifies the input markup for the raw index. The following values are available:

\begin{description}
\item[\povalue{latex}] This value, as the name implies, is emitted by default from the \LaTeX\ kernel, and the raw input is encoded in the \LaTeX\ Internal Character Representation format.

\item[\povalue{xelatex}] This value, as the name implies, acts like the previous \rbox[cyan]{latex} markup option, but without \rbox{inputenc} usage. Raw input is encoded in the UTF-8 format.

\item[\povalue{omega}] This value, as the name implies, acts like the previous \rbox[cyan]{latex} markup option, but with Omega's special notation as encoding for characters not in the ASCII set.
\end{description}

\item[\abox{modules}] This option, as the name indicates, takes a list of module names. Modules are searched in the usual application path. An error is thrown if any data structure other than a proper list is provided as the value.

\item[\rpbox{input}{idx}] This option, as the name indicates, sets the default extension for the input file, according to the provided value. Later, this value will be concatenated as a suffix for the base name of the \mtbox{currentFile} reference (i.e, the name without the associated extension).

\item[\rpbox{output}{ind}] This option, as the name indicates, sets the default extension for the output file, according to the provided value. Later, this value will be concatenated as a suffix for the base name of the \mtbox{currentFile} reference (i.e, the name without the associated extension).

\item[\rpbox{log}{ilg}] This option, as the name indicates, sets the default extension for the log file, according to the provided value. Later, this value will be concatenated as a suffix for the base name of the \mtbox{currentFile} reference (i.e, the name without the associated extension).

\item[\abox{options}] This option, as the name indicates, takes a list of raw command line options and appends it to the actual system call. An error is thrown if any data structure other than a proper list is provided as the value.
\end{description}

\begin{codebox}{Example}{teal}{\icnote}{white}
% arara: texindy: { markup: latex }
\end{codebox}

\item[\rulebox{tikzmake}{Robbie Smith, Paulo Cereda}] This rule runs \rbox{make} on a very specific build file generated by the \rbox{tikzmake} package, as a means to simplify the externalization of Ti{\itshape k}Z pictures. This build file corresponds to the base name of the \mtbox{currentFile} reference (i.e, the name without the associated extension) as a string concatenated with the \rbox{makefile} suffix.

\begin{description}
\item[\rpsbox{force}] This option, as the name indicates, sets whether all targets specified in the corresponding build file should be unconditionally made.

\item[\abox{jobs}] This option, as the name indicates, specifies the number of jobs (commands) to run simultaneously. Note that the provided value must be a positive integer. The default number of job slots is one, which means serial execution.

\item[\abox{options}] This option, as the name indicates, takes a list of raw command line options and appends it to the actual system call. An error is thrown if any data structure other than a proper list is provided as the value.
\end{description}

\begin{codebox}{Example}{teal}{\icnote}{white}
% arara: tikzmake: { force: yes, jobs: 2 }
\end{codebox}

\item[\rulebox{velocity}{Paulo Cereda}] This rule, as the name suggests, calls the \mtbox{mergeVelocityTemplate} method, merging an input template file written according to the Velocity Template Language 1.7 specification with the provided \rbox{Map} data object in order to produce a corresponding \rbox{File} output. Be mindful that this particular rule returns \rbox{true} if, and only if, the aforementioned method is successfully executed. Otherwise, an exception is raised.

\begin{description}
\item[\abox{input}] This option, as the name indicates, sets the input template file, written according to the Velocity Template Language 1.7 specification, as a proper \rbox{File} reference. Please note that the \mtbox{currentFile} reference is used as default input when this option is not set.

\item[\abox{output}~\rqbox] This required option, as the name indicates, sets the output \rbox{File} reference. Be mindful that, if the reference exists, it will be overwritten without any warning.

\item[\abox{context}~\rqbox] This required option, as the name indicates, sets the \rbox{Map} data object to be used as context to the method call, according to the provided value. An error is thrown if any data structure other than a proper map is specified.
\end{description}

\begin{codebox}{Example}{teal}{\icnote}{white}
% arara: velocity: { input: input.txt, output: output.txt,
% arara: --> context: { name: Paulo, country: Brazil } }
\end{codebox}

\item[\rulebox{xdvipdfmx}{Marco Daniel, Paulo Cereda}] This rule runs \rbox{xdvipdfmx}, the back end for the \rbox{xetex} \TeX\ engine (and not intended to be invoked directly), on the corresponding base name of the \mtbox{currentFile} reference (i.e, the name without the associated extension) as a string concatenated with the \rbox{dvi} suffix, generating a Portable Document Format \rbox{pdf} file.

\begin{description}
\item[\abox{output}] This option, as the name indicates, sets the output name for the generated \rbox{pdf} file. There is no need to provide an extension, as the value is always normalized with \mtbox{getBasename} such that only the name without the associated extension is used. The base name of the current file reference is used as the default value.

\item[\abox{options}] This option, as the name indicates, takes a list of raw command line options and appends it to the actual system call. An error is thrown if any data structure other than a proper list is provided as the value.
\end{description}

\begin{codebox}{Example}{teal}{\icnote}{white}
% arara: xdvipdfmx: { output: thesis }
\end{codebox}

\item[\rulebox{xelatex}{Marco Daniel, Paulo Cereda}] This rule runs the new \rbox{xelatex} \TeX\ engine on the provided \mtbox{currentFile} reference, generating a corresponding file in the Portable Document File format, as expected.

\begin{description}
\item[\abox{interaction}] This option alters the underlying engine behaviour. If this option is omitted, \TeX\ will prompt the user for interaction in the event of an error. Possible values are, in order of increasing user interaction (courtesy of our master Enrico Gregorio):

\begin{description}
\item[\povalue{batchmode}] In this mode, nothing is printed on the terminal, and errors are scrolled as if the \rbox{return} key is hit at every error. Missing files that \TeX\ tries to input or request from keyboard input cause the job to abort.

\item[\povalue{nonstopmode}] In this mode, the diagnostic message will appear on the terminal, but there is no possibility of user interaction just like in batch mode, previously described.

\item[\povalue{scrollmode}] In this mode, as the name indicates, \TeX\ will stop only for missing files to input or if proper keyboard input is necessary. \TeX\ fixes errors itself.

\item[\povalue{errorstopmode}] In this mode, \TeX\ will stop at each error, asking for proper user intervention. This is the most user interactive mode available.
\end{description}

\item[\rpsbox{shell}] This option sets whether the possibility of running underlying system commands from within \TeX\ is activated.

\item[\rpsbox{synctex}] This option sets whether \rbox{synctex}, an input and output synchronization feature that allows navigation from source to typeset material and vice versa, available in most \TeX\ engines, is activated.

\item[\abox{options}] This option, as the name indicates, takes a list of raw command line options and appends it to the actual system call. An error is thrown if any data structure other than a proper list is provided as the value.
\end{description}

\begin{codebox}{Example}{teal}{\icnote}{white}
% arara: xelatex: { shell: yes, synctex: yes }
\end{codebox}

\item[\rulebox{xetex}{Marco Daniel, Paulo Cereda}] This rule runs the \rbox{xetex} \TeX\ engine on the provided \mtbox{currentFile} reference, generating a corresponding file in the Portable Document File format, as expected.

\begin{description}
\item[\abox{interaction}] This option alters the underlying engine behaviour. If this option is omitted, \TeX\ will prompt the user for interaction in the event of an error. Possible values are, in order of increasing user interaction (courtesy of our master Enrico Gregorio):

\begin{description}
\item[\povalue{batchmode}] In this mode, nothing is printed on the terminal, and errors are scrolled as if the \rbox{return} key is hit at every error. Missing files that \TeX\ tries to input or request from keyboard input cause the job to abort.

\item[\povalue{nonstopmode}] In this mode, the diagnostic message will appear on the terminal, but there is no possibility of user interaction just like in batch mode, previously described.

\item[\povalue{scrollmode}] In this mode, as the name indicates, \TeX\ will stop only for missing files to input or if proper keyboard input is necessary. \TeX\ fixes errors itself.

\item[\povalue{errorstopmode}] In this mode, \TeX\ will stop at each error, asking for proper user intervention. This is the most user interactive mode available.
\end{description}

\item[\rpsbox{shell}] This option sets whether the possibility of running underlying system commands from within \TeX\ is activated.

\item[\rpsbox{synctex}] This option sets whether \rbox{synctex}, an input and output synchronization feature that allows navigation from source to typeset material and vice versa, available in most \TeX\ engines, is activated.

\item[\abox{options}] This option, as the name indicates, takes a list of raw command line options and appends it to the actual system call. An error is thrown if any data structure other than a proper list is provided as the value.
\end{description}

\begin{codebox}{Example}{teal}{\icnote}{white}
% arara: xetex: { interaction: scrollmode, synctex: yes }
\end{codebox}

\item[\rulebox{xindy}{Nicola Talbot, Paulo Cereda}] This rule runs \rbox{xindy}, a flexible and powerful indexing system, on the corresponding base name of the \mtbox{currentFile} reference (i.e, the name without the associated extension) as a string concatenated with the \rbox{idx} suffix, generating an index as a special \rbox{ind} file.

\begin{description}
\item[\rpsbox{quiet}] This option, as the name indicates, sets whether the tool will output progress messages. It is important to observe that \rbox{xindy} always outputs error messages, regardless of this option.

\item[\abox{codepage}] This option, as the name indicates, specifies the encoding to be used for letter group headings. Additionally, it specifies the encoding used internally for sorting, but that does not matter for the final result.

\item[\abox{language}] This option, as the name indicates, specifies the language that dictates the rules for index sorting. These rules are encoded in a module.

\item[\abox{markup}] This option, as the name indicates, specifies the input markup for the raw index. The following values are available:

\begin{description}
\item[\povalue{latex}] This value, as the name implies, is emitted by default from the \LaTeX\ kernel, and the raw input is encoded in the \LaTeX\ Internal Character Representation format.

\item[\povalue{xelatex}] This value, as the name implies, acts like the previous \rbox[cyan]{latex} markup option, but without \rbox{inputenc} usage. Raw input is encoded in the UTF-8 format.

\item[\povalue{omega}] This value, as the name implies, acts like the previous \rbox[cyan]{latex} markup option, but with Omega's special notation as encoding for characters not in the ASCII set.

\item[\povalue{xindy}] This value, as the name implies, uses the \rbox{xindy} input markup as specified in the \rbox{xindy} manual.
\end{description}

\item[\abox{modules}] This option, as the name indicates, takes a list of module names. Modules are searched in the usual application path. An error is thrown if any data structure other than a proper list is provided as the value.

\item[\rpbox{input}{idx}] This option, as the name indicates, sets the default extension for the input file, according to the provided value. Later, this value will be concatenated as a suffix for the base name of the \mtbox{currentFile} reference (i.e, the name without the associated extension).

\item[\rpbox{output}{ind}] This option, as the name indicates, sets the default extension for the output file, according to the provided value. Later, this value will be concatenated as a suffix for the base name of the \mtbox{currentFile} reference (i.e, the name without the associated extension).

\item[\rpbox{log}{ilg}] This option, as the name indicates, sets the default extension for the log file, according to the provided value. Later, this value will be concatenated as a suffix for the base name of the \mtbox{currentFile} reference (i.e, the name without the associated extension).

\item[\abox{options}] This option, as the name indicates, takes a list of raw command line options and appends it to the actual system call. An error is thrown if any data structure other than a proper list is provided as the value.
\end{description}

\begin{codebox}{Example}{teal}{\icnote}{white}
% arara: xindy: { markup: xelatex }
\end{codebox}
\end{description}

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 \rbox{texdoc}, a command line program to find and view documentation. For example, this manual can be viewed through the following command:

\begin{codebox}{Terminal}{teal}{\icnote}{white}
$ texdoc arara
\end{codebox}

The primary function of the handy \rbox{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 MiK\TeX\ users, the distribution provides a similar tool named \rbox{mthelp} to find and view documentation. Make sure to use these tools whenever needed!