summaryrefslogtreecommitdiff
path: root/support/arara/doc/chapters/rules.tex
diff options
context:
space:
mode:
Diffstat (limited to 'support/arara/doc/chapters/rules.tex')
-rw-r--r--support/arara/doc/chapters/rules.tex434
1 files changed, 381 insertions, 53 deletions
diff --git a/support/arara/doc/chapters/rules.tex b/support/arara/doc/chapters/rules.tex
index f2e7bfd0bc..759d62e133 100644
--- a/support/arara/doc/chapters/rules.tex
+++ b/support/arara/doc/chapters/rules.tex
@@ -9,7 +9,7 @@ As seen in Section~\ref{sec:basicstructure}, on page~\pageref{sec:basicstructure
\end{messagebox}
\begin{description}
-\item[\rulebox{animate}{Chris Hughes, Paulo Cereda}]
+\item[\rulebox{animate}]
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}
@@ -35,14 +35,64 @@ The best solution to avoid possible future name conflicts, according to the Imag
% 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.
+\item[\rulebox{asymptote}]
+This rule executes the \rbox{asy} command line, referring to Asymptote, a powerful descriptive vector graphics language for technical drawings, inspired by Metapost but with an improved syntax. Please note that you will have to make the \rbox{.asy} extension known to \arara\ in order to compile Asymptote files. Furthermore, it is advised to use this in your regular \TeX\ document specifying the \abox{files} parameter to include all graphics you want to compile for inclusion in your document.
+
+\begin{description}
+\item[\abox{color}] This option, as the name suggests, provides the underlying color model to be used in the current execution. Possible values are:
+
+\begin{description}
+\item[\povalue{\hphantom{x}bw\hphantom{x}}] This option value, as the name suggests, converts all colors to a black and white model.
+
+\item[\povalue{cmyk}] This option value converts the RGB (red, green an blue) color model to the CMYK (cyan, magenta, yellow and black) counterpart.
+
+\item[\povalue{rgb}] This option value converts the CMYK (cyan, magenta, yellow and black) color model to the RGB (red, green an blue) counterpart.
+
+\item[\povalue{gray}] This option value, as the name suggests, converts all colors to a grayscale model.
+\end{description}
+
+\item[\rpbox{engine}{latex}] This option, as the name indicates, sets the underlying \TeX\ engine to be used for the current compilation. Make sure to take a look at the Asymptote manual for further details on this option. Possible values are:
+
+\begin{description}
+\item[\povalue{latex}] This value, as the name suggests, sets the underlying \TeX\ engine to \rbox{latex} for the current compilation. Note that the engine might play a major role in the generated code.
+
+\item[\povalue{pdflatex}] This value, as the name indicates, sets the underlying \TeX\ engine to \rbox{pdflatex} for the current compilation. Note that the engine might play a major role in the generated code.
+
+\item[\povalue{xelatex}] This value, as the name suggests, sets the underlying \TeX\ engine to \rbox{xelatex} for the current compilation. Note that the engine might play a major role in the generated code.
+
+\item[\povalue{lualatex}] This value, as the name indicates, sets the underlying \TeX\ engine to \rbox{lualatex} for the current compilation. Note that the engine might play a major role in the generated code.
+
+\item[\povalue{tex}] This value, as the name suggests, sets the underlying \TeX\ engine to \rbox{tex} for the current compilation. Note that the engine might play a major role in the generated code.
+
+\item[\povalue{pdftex}] This value, as the name indicates, sets the underlying \TeX\ engine to \rbox{pdftex} for the current compilation. Note that the engine might play a major role in the generated code.
+
+\item[\povalue{luatex}] This value, as the name suggests, sets the underlying \TeX\ engine to \rbox{luatex} for the current compilation. Note that the engine might play a major role in the generated code.
+
+\item[\povalue{context}] This value, as the name indicates, sets the underlying \TeX\ engine to \rbox{context} for the current compilation. Note that the engine might play a major role in the generated code.
+
+\item[\povalue{none}] This value, as the name suggests, sets the underlying \TeX\ engine to \rbox{none} for the current compilation. In this case, there will be no associated engine.
+\end{description}
+
+\item[\abox{format}] This option, as the name suggests, converts each output file to a specified format. Make sure to take a look at the Asymptote manual for further details.
+
+\item[\abox{output}] This option, as the name suggests, sets an alternative output directory or file name. Make sure to take a look at the Asymptote manual for further details.
+
+\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.
+
+\begin{codebox}{Example}{teal}{\icnote}{white}
+% arara: asymptote: { files: [ mydrawing.asy ] }
+\end{codebox}
+\end{description}
+
+\item[\rulebox{bib2gls}]
+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[\abox{locale}] This option specifies the preferred language resource file. Please keep in mind that the provided value must be a valid IETF language tag. If omitted, the default is obtained by \rbox{bib2gls} from the 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.
@@ -80,9 +130,12 @@ The best solution to avoid possible future name conflicts, according to the Imag
% 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.
+\item[\rulebox{biber}]
+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[\rpsbox{tool}] This option sets whether the bibliography processor should be executed in \emph{tool mode}, intended for transformations and modifications of datasources. Since this mode is oriented towards a datasource rather than a document, make sure to use it alongside the \abox{options} option.
+
\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}
@@ -90,7 +143,8 @@ The best solution to avoid possible future name conflicts, according to the Imag
% 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.
+\item[\rulebox{bibtex}]
+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.
@@ -101,7 +155,8 @@ The best solution to avoid possible future name conflicts, according to the Imag
% 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.
+\item[\rulebox{bibtex8}]
+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.
@@ -111,7 +166,8 @@ The best solution to avoid possible future name conflicts, according to the Imag
% 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.
+\item[\rulebox{bibtexu}]
+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.
@@ -121,7 +177,8 @@ The best solution to avoid possible future name conflicts, according to the Imag
% 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.
+\item[\rulebox{clean}]
+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.
@@ -135,7 +192,8 @@ When in doubt, always remember that the \opbox{{-}dry-run} command line option i
% 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.
+\item[\rulebox{csplain}]
+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):
@@ -163,7 +221,8 @@ When in doubt, always remember that the \opbox{{-}dry-run} command line option i
% 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.
+\item[\rulebox{datatooltk}]
+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.
@@ -176,11 +235,11 @@ When in doubt, always remember that the \opbox{{-}dry-run} command line option i
\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{sql}] This option imports data from an SQL database where the provided value refers to a proper \rbox{select} 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{sqldb}] This option, as the name indicates, sets the name of the 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[\abox{sqluser}] This option, as the name indicates, sets the name of the 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:
@@ -189,7 +248,7 @@ When in doubt, always remember that the \opbox{{-}dry-run} command line option i
\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.
+\item[\povalue{gui}] This action displays a dialog box in which the user can enter the password for the 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.
@@ -213,7 +272,7 @@ spreadsheet import functions also use this setting.
\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[\rpsbox{maptex}] This option sets whether \TeX\ special characters will be properly mapped when importing data from \rbox{csv} files or 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.
@@ -240,7 +299,8 @@ spreadsheet import functions also use this setting.
% 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.
+\item[\rulebox{dvipdfm}]
+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.
@@ -252,7 +312,8 @@ spreadsheet import functions also use this setting.
% 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.
+\item[\rulebox{dvipdfmx}]
+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.
@@ -264,7 +325,8 @@ spreadsheet import functions also use this setting.
% 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.
+\item[\rulebox{dvips}]
+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.
@@ -276,7 +338,8 @@ spreadsheet import functions also use this setting.
% 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.
+\item[\rulebox{dvipspdf}]
+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.
@@ -290,7 +353,8 @@ spreadsheet import functions also use this setting.
% 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.
+\item[\rulebox{dvisvgm}]
+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.
@@ -300,7 +364,8 @@ spreadsheet import functions also use this setting.
% 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.
+\item[\rulebox{etex}]
+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):
@@ -324,7 +389,8 @@ spreadsheet import functions also use this setting.
% 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.
+\item[\rulebox{frontespizio}]
+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:
@@ -361,13 +427,15 @@ spreadsheet import functions also use this setting.
% 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.
+\item[\rulebox{halt}]
+This rule, as the name suggests, sets a \rbox{halt} flag, which stops the current interpretation workflow, such that subsequent directives are ignored. This rule contains no associated options. Please refer to Section~\ref{sec:others}, on page~\pageref{sec:others}, for more information on flags.
\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.
+\item[\rulebox{indent}]
+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.
@@ -419,9 +487,37 @@ spreadsheet import functions also use this setting.
% 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.
+\item[\rulebox{knitr}]
+This rule calls the \rbox{knitr} package, a transparent engine for dynamic report generation with R. It takes an \rbox{.Rnw} file as input, extracts the R code in it according to a list of patterns, evaluates the code and writes the output in another file. It can also tangle R source code from the input document.
+
+\begin{description}
+\item[\rpbox{output}{NULL}] This option sets the output file. when absent, \rbox{knitr} will try to guess a default, which will be under the current working directory.
+
+\item[\rpsbox{tangle}] This option sets whether to tangle the R code from the input file. Note that, when used, this option requires \abox{output} to be specified as well, otherwise an error is thrown.
+
+\item[\rpsbox{quiet}] This option, as the name indicates, sets whether the tool should suppress both progress bar and messages.
+
+\item[\rpbox{envir}{parent.frame()}] This option sets the environment in which code chunks are to be evaluated. Please refer to the documentation for further details.
+
+\item[\rpbox{encoding}{getOption("encoding")}] This option, as the name indicates, sets the encoding of the input file. Please refer to the documentation for further details.
+\end{description}
+
+\begin{codebox}{Example}{teal}{\icnote}{white}
+% arara: knitr: { quiet: yes }
+\end{codebox}
+
+\item[\rulebox{latex}]
+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[\rpbox{branch}{stable}] This option allows branching formats for the current engine, mainly focused on package development. Users of current \TeX\ distributions might benefit from format branching in order to easily test documents and code against the upcoming releases. Possible values are:
+
+\begin{description}
+\item[\povalue{stable}] This value, as the name implies, enables the stable engine format branch. Note that this is the default format.
+
+\item[\povalue{developer}] For experienced users, this value enables the experimental, developer engine format branch.
+\end{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}
@@ -447,7 +543,8 @@ spreadsheet import functions also use this setting.
% 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.
+\item[\rulebox{latexmk}]
+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:
@@ -479,7 +576,8 @@ spreadsheet import functions also use this setting.
% 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.
+\item[\rulebox{luahbtex}]
+This rule runs the \rbox{luahbtex} \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):
@@ -504,11 +602,50 @@ spreadsheet import functions also use this setting.
\end{description}
\begin{codebox}{Example}{teal}{\icnote}{white}
+% arara: luahbtex: { interaction: batchmode,
+% arara: --> shell: yes, draft: yes }
+\end{codebox}
+
+\item[\rulebox{lualatex}]
+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[\rpbox{branch}{stable}] This option allows branching formats for the current engine, mainly focused on package development. Users of current \TeX\ distributions might benefit from format branching in order to easily test documents and code against the upcoming releases. Possible values are:
+
+\begin{description}
+\item[\povalue{stable}] This value, as the name implies, enables the stable engine format branch. Note that this is the default format.
+
+\item[\povalue{developer}] For experienced users, this value enables the experimental, developer engine format branch.
+\end{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.
+\item[\rulebox{luatex}]
+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):
@@ -537,7 +674,8 @@ spreadsheet import functions also use this setting.
% 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.
+\item[\rulebox{make}]
+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.
@@ -549,7 +687,8 @@ spreadsheet import functions also use this setting.
% 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.
+\item[\rulebox{makeglossaries}]
+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.
@@ -559,7 +698,8 @@ spreadsheet import functions also use this setting.
% 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.
+\item[\rulebox{makeglossarieslite}]
+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.
@@ -569,7 +709,8 @@ spreadsheet import functions also use this setting.
% 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.
+\item[\rulebox{makeindex}]
+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.
@@ -597,7 +738,41 @@ spreadsheet import functions also use this setting.
% 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.
+\item[\rulebox{metapost}]
+This rule runs \rbox{metapost}, a tool to compile the Metapost graphics programming language. Please note that you will have to make the \rbox{.mp} extension known to \arara\ in order to compile Metapost files. Furthermore, it is advised to use this in your regular \TeX\ document specifying the \abox{files} parameter to include all graphics you want to compile for inclusion in your document.
+
+\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[\abox{numbersystem}] This option sets the number system Metapost will use for calculations.
+
+\begin{description}
+\item[\povalue{scaled}] In this mode, 32-bit fixed-point arithmetics is used.
+
+\item[\povalue{double}] In this mode, IEEE floating-point arithmetics with 64 bits is used.
+\item[\povalue{binary}] This mode is similary to \povalue{double} but without a fixed-length mantissa.
+\item[\povalue{decimal}] In this mode, arbitrary precision arithmetics is used and numbers are internally represented in base 10.
+\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 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: metapost: { files: [ graphics.mp ] }
+\end{codebox}
+
+\item[\rulebox{nomencl}]
+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.
@@ -609,7 +784,20 @@ spreadsheet import functions also use this setting.
% 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.
+\item[\rulebox{pbibtex}]
+This rule runs the \rbox{pbibtex} 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: pbibtex
+% arara: --> if exists(toFile('references.bib'))
+\end{codebox}
+
+\item[\rulebox{pdfcsplain}]
+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):
@@ -637,9 +825,18 @@ spreadsheet import functions also use this setting.
% 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.
+\item[\rulebox{pdflatex}]
+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[\rpbox{branch}{stable}] This option allows branching formats for the current engine, mainly focused on package development. Users of current \TeX\ distributions might benefit from format branching in order to easily test documents and code against the upcoming releases. Possible values are:
+
+\begin{description}
+\item[\povalue{stable}] This value, as the name implies, enables the stable engine format branch. Note that this is the default format.
+
+\item[\povalue{developer}] For experienced users, this value enables the experimental, developer engine format branch.
+\end{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}
@@ -666,7 +863,8 @@ spreadsheet import functions also use this setting.
% 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.
+\item[\rulebox{pdftex}]
+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):
@@ -694,7 +892,43 @@ spreadsheet import functions also use this setting.
% 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.
+\item[\rulebox{platex}]
+This rule runs the \rbox{platex} \TeX\ engine on the provided \mtbox{currentFile} reference, generating a corresponding file in a device independent format.
+
+\begin{description}
+\item[\rpbox{branch}{stable}] This option allows branching formats for the current engine, mainly focused on package development. Users of current \TeX\ distributions might benefit from format branching in order to easily test documents and code against the upcoming releases. Possible values are:
+
+\begin{description}
+\item[\povalue{stable}] This value, as the name implies, enables the stable engine format branch. Note that this is the default format.
+
+\item[\povalue{developer}] For experienced users, this value enables the experimental, developer engine format branch.
+\end{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: platex: { interaction: scrollmode, shell: yes }
+\end{codebox}
+
+\item[\rulebox{pdftk}]
+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.
@@ -704,7 +938,8 @@ spreadsheet import functions also use this setting.
% 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.
+\item[\rulebox{ps2pdf}]
+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.
@@ -716,7 +951,8 @@ spreadsheet import functions also use this setting.
% 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}.
+\item[\rulebox{sketch}]
+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.
@@ -726,7 +962,8 @@ spreadsheet import functions also use this setting.
% 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.
+\item[\rulebox{songidx}]
+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.
@@ -740,7 +977,8 @@ spreadsheet import functions also use this setting.
% 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.
+\item[\rulebox{tex}]
+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):
@@ -764,7 +1002,8 @@ spreadsheet import functions also use this setting.
% 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.
+\item[\rulebox{texindy}]
+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.
@@ -798,7 +1037,8 @@ spreadsheet import functions also use this setting.
% 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.
+\item[\rulebox{tikzmake}]
+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.
@@ -812,22 +1052,82 @@ spreadsheet import functions also use this setting.
% 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.
+\item[\rulebox{upbibtex}]
+This rule runs the \rbox{upbibtex} 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{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{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}
-\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.
+\begin{codebox}{Example}{teal}{\icnote}{white}
+% arara: pbibtex
+% arara: --> if exists(toFile('references.bib'))
+\end{codebox}
+
+\item[\rulebox{uplatex}]
+This rule runs the \rbox{uplatex} \TeX\ engine on the provided \mtbox{currentFile} reference, generating a corresponding file in a device independent format.
+
+\begin{description}
+\item[\rpbox{branch}{stable}] This option allows branching formats for the current engine, mainly focused on package development. Users of current \TeX\ distributions might benefit from format branching in order to easily test documents and code against the upcoming releases. Possible values are:
+
+\begin{description}
+\item[\povalue{stable}] This value, as the name implies, enables the stable engine format branch. Note that this is the default format.
-\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.
+\item[\povalue{developer}] For experienced users, this value enables the experimental, developer engine format branch.
+\end{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: velocity: { input: input.txt, output: output.txt,
-% arara: --> context: { name: Paulo, country: Brazil } }
+% arara: uplatex: { interaction: scrollmode, shell: yes }
\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.
+\item[\rulebox{uptex}]
+This rule runs the \rbox{uptex} \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[\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: uptex
+\end{codebox}
+
+\item[\rulebox{xdvipdfmx}]
+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.
@@ -839,9 +1139,18 @@ spreadsheet import functions also use this setting.
% 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.
+\item[\rulebox{xelatex}]
+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[\rpbox{branch}{stable}] This option allows branching formats for the current engine, mainly focused on package development. Users of current \TeX\ distributions might benefit from format branching in order to easily test documents and code against the upcoming releases. Possible values are:
+
+\begin{description}
+\item[\povalue{stable}] This value, as the name implies, enables the stable engine format branch. Note that this is the default format.
+
+\item[\povalue{developer}] For experienced users, this value enables the experimental, developer engine format branch.
+\end{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}
@@ -865,7 +1174,8 @@ spreadsheet import functions also use this setting.
% 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.
+\item[\rulebox{xetex}]
+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):
@@ -891,7 +1201,25 @@ spreadsheet import functions also use this setting.
% 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.
+\item[\rulebox{xindex}]
+This rule runs \rbox{xindex}, a flexible and powerful indexing system, on a provided \rbox{idx} input. This tool is completely with the \rbox{makeindex} program.
+
+\begin{description}
+\item[\abox{input}~\rqbox] This option, as the name indicates, corresponds to the \rbox{idx} reference to be processed by the indexing system. Note that this option is required.
+
+\item[\rpbox{config}{cfg}] This option specifies a configuration extension. Make sure to take a look at the documentation for further details.
+
+\item[\rpbox{language}{en}] This option, as the name suggests, specifies the language. Make sure to take a look at the documentation for further details.
+
+\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: xindex: { input: mydoc.idx }
+\end{codebox}
+
+\item[\rulebox{xindy}]
+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.