summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/doc/support
diff options
context:
space:
mode:
authorKarl Berry <karl@freefriends.org>2020-04-10 22:00:34 +0000
committerKarl Berry <karl@freefriends.org>2020-04-10 22:00:34 +0000
commit993a56dc5ce732dfd560a3d411d970709e732080 (patch)
tree0be74e078fbfb126531e9983b39e07be3100635c /Master/texmf-dist/doc/support
parent9ebef863fbd274ccc04480e1f12b7ce385c739c8 (diff)
arara
git-svn-id: svn://tug.org/texlive/trunk@54640 c570f23f-e606-0410-a88d-b1316a301751
Diffstat (limited to 'Master/texmf-dist/doc/support')
-rw-r--r--Master/texmf-dist/doc/support/arara/README.md14
-rw-r--r--Master/texmf-dist/doc/support/arara/arara-manual.pdfbin1827955 -> 1862533 bytes
-rw-r--r--Master/texmf-dist/doc/support/arara/arara-manual.tex4
-rw-r--r--Master/texmf-dist/doc/support/arara/arara.sty10
-rw-r--r--Master/texmf-dist/doc/support/arara/chapters/cli.tex26
-rw-r--r--Master/texmf-dist/doc/support/arara/chapters/concepts.tex4
-rw-r--r--Master/texmf-dist/doc/support/arara/chapters/deploying.tex6
-rw-r--r--Master/texmf-dist/doc/support/arara/chapters/introduction.tex8
-rw-r--r--Master/texmf-dist/doc/support/arara/chapters/logging.tex2
-rw-r--r--Master/texmf-dist/doc/support/arara/chapters/methods.tex10
-rw-r--r--Master/texmf-dist/doc/support/arara/chapters/mvel.tex10
-rw-r--r--Master/texmf-dist/doc/support/arara/chapters/rules.tex214
-rw-r--r--Master/texmf-dist/doc/support/arara/chapters/yaml.tex4
13 files changed, 256 insertions, 56 deletions
diff --git a/Master/texmf-dist/doc/support/arara/README.md b/Master/texmf-dist/doc/support/arara/README.md
index 89ddfe91652..d5417174ca3 100644
--- a/Master/texmf-dist/doc/support/arara/README.md
+++ b/Master/texmf-dist/doc/support/arara/README.md
@@ -1,6 +1,6 @@
![arara](https://i.stack.imgur.com/hjUsN.png)
-# arara
+# arara v5.1.0
![Language: Kotlin](https://img.shields.io/badge/Language-Kotlin-blue.svg?style=flat-square)
![Minimum JRE: 8.0](https://img.shields.io/badge/Minimum_JRE-8-blue.svg?style=flat-square)
@@ -10,8 +10,6 @@ way to enhance your TeX experience. The tool is an effort to provide a concise
way to automate the daily TeX workflow for users and also package writers. Users
might write their own rules when the provided ones do not suffice.
-Current stable release: 5.0.2
-
> Please note that `arara` recently moved. We are proud to announce that
> `arara` is now part of the [Island of TeX](https://gitlab.com/islandoftex).
> The new address is https://gitlab.com/islandoftex/arara. The old GitHub
@@ -46,18 +44,18 @@ use your own rules.
ensured that a green tick means `arara` passes the test suite and is ready to
be tested. However, that is *not* meant you can use the executable artifacts of
the builds *for productive use*.
-
+
Development of `arara` takes place in the development branch. Feel free to be
one of our testers and enjoy the latest features and bug fixes by building from
- there.
-
+ there.
+
## Support
We use a [Gitter](https://gitter.im/cereda/arara) chatroom for discussing things
related to `arara`. You are more than welcome to come join the fun and say *hi!*
to us. We also have the [issues](https://gitlab.com/islandoftex/arara/issues)
section in our repository as a valid channel to report problems, bugs and
-suggest improvements.
+suggest improvements.
## Localization
@@ -86,7 +84,7 @@ manually deploy our tool.
## License
-This application is licensed under the
+This application is licensed under the
[New BSD License](https://opensource.org/licenses/BSD-3-Clause). Please
note that the New BSD License has been verified as a GPL-compatible free
software license by the [Free Software Foundation](http://www.fsf.org/), and
diff --git a/Master/texmf-dist/doc/support/arara/arara-manual.pdf b/Master/texmf-dist/doc/support/arara/arara-manual.pdf
index f1ab066d436..3a45d4a5196 100644
--- a/Master/texmf-dist/doc/support/arara/arara-manual.pdf
+++ b/Master/texmf-dist/doc/support/arara/arara-manual.pdf
Binary files differ
diff --git a/Master/texmf-dist/doc/support/arara/arara-manual.tex b/Master/texmf-dist/doc/support/arara/arara-manual.tex
index d9926240c3b..3f245802fc7 100644
--- a/Master/texmf-dist/doc/support/arara/arara-manual.tex
+++ b/Master/texmf-dist/doc/support/arara/arara-manual.tex
@@ -42,8 +42,8 @@
\usepackage[margin=2.5cm]{geometry}
\usepackage{arara}
-\newcommand{\araraversion}{5.0}
-
+\newcommand{\araraversion}{5.1}
+
\begin{document}
\begin{titlingpage}
diff --git a/Master/texmf-dist/doc/support/arara/arara.sty b/Master/texmf-dist/doc/support/arara/arara.sty
index 5cc02225e5c..56eaf7608d7 100644
--- a/Master/texmf-dist/doc/support/arara/arara.sty
+++ b/Master/texmf-dist/doc/support/arara/arara.sty
@@ -125,7 +125,7 @@
shift={([xshift=0.35em, yshift=0.31em]frame.north west)},
scale=.11
]
-
+
\path[fill=#1!5] (104.4280,104.4280) circle (2.9472cm);
\path[shift={(-46.913,-45.374)},fill=#1] (88.7990,180.6000) --
(119.5860,149.8020) -- (88.7990,119.0130) -- (120.5410,87.2560) --
@@ -146,7 +146,7 @@
shift={([xshift=0.35em, yshift=0.31em]frame.north west)},
scale=.11
]
-
+
\path[fill=#1!5] (209.4880,104.7460) .. controls (209.4880,162.5980) and
(162.5940,209.4910) .. (104.7430,209.4910) .. controls (46.8930,209.4910) and
(0.0000,162.5970) .. (0.0000,104.7460) .. controls (0.0000,46.8950) and
@@ -193,7 +193,7 @@
shift={([xshift=0.35em, yshift=0.31em]frame.north west)},
scale=.11
]
-
+
\path[fill=#1!5] (104.4310,104.4310) circle (2.9473cm);
\begin{scope}[shift={(-46.694,-45.371)}]
\path[fill=#1] (139.1560,93.9220) .. controls (142.1760,91.1310) and
@@ -236,7 +236,7 @@
shift={([xshift=0.35em, yshift=0.31em]frame.north west)},
scale=.11
]
-
+
\path[fill=#1!5] (104.4280,104.4280) circle (2.9472cm);
\begin{scope}[shift={(-46.08801,-45.37)}]
\path[fill=#1] (113.9190,187.9100) -- (127.1980,200.4160) --
@@ -259,7 +259,7 @@
shift={([xshift=0.35em, yshift=0.31em]frame.north west)},
scale=.11
]
-
+
\path[fill=#1!5] (209.4910,104.7440) .. controls (209.4910,162.5960) and
(162.5940,209.4880) .. (104.7470,209.4880) .. controls (46.8950,209.4880) and
(0.0000,162.5950) .. (0.0000,104.7440) .. controls (0.0000,46.8930) and
diff --git a/Master/texmf-dist/doc/support/arara/chapters/cli.tex b/Master/texmf-dist/doc/support/arara/chapters/cli.tex
index 60678e88d5a..e4e34b76088 100644
--- a/Master/texmf-dist/doc/support/arara/chapters/cli.tex
+++ b/Master/texmf-dist/doc/support/arara/chapters/cli.tex
@@ -210,8 +210,8 @@ This option can also be specified in the configuration file (see Section~\ref{se
The \opbox{{-}max-loops} option is used to redefine the maximum number of loops our tool will allow for potentially infinite iterations. Any positive integer can be used as the \prbox{number} value for this option. An execution of the previous directive with a lower maximum number of loops is shown as follows:
\begin{codebox}{Terminal}{teal}{\icnote}{white}
-$ arara -m 2 doc8.tex
- __ _ _ __ __ _ _ __ __ _
+$ arara -m 2 doc8.tex
+ __ _ _ __ __ _ _ __ __ _
/ _` | '__/ _` | '__/ _` |
| (_| | | | (_| | | | (_| |
\__,_|_| \__,_|_| \__,_|
@@ -230,7 +230,7 @@ This option can also be specified in the configuration file (see Section~\ref{se
\item[\describeop{n}{dry-run}] 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 underlying system commands to be performed on a file. For instance, consider the following execution:
\begin{codebox}{Terminal}{teal}{\icnote}{white}
-$ arara -n doc5.tex
+$ arara -n doc5.tex
__ _ _ __ __ _ _ __ __ _
/ _` | '__/ _` | '__/ _` |
| (_| | | | (_| | | | (_| |
@@ -242,22 +242,22 @@ Processing 'doc5.tex' (size: 285 B, last modified: 03/01/2020
[DR] (PDFLaTeX) PDFLaTeX engine
-----------------------------------------------------------------
Author: Island of TeX
-About to run: [ pdflatex, /home/paulo/Downloads/doc5.tex ] @
+About to run: [ pdflatex, /home/paulo/Downloads/doc5.tex ] @
[DR] (BibTeX) The BibTeX reference management software
-----------------------------------------------------------------
Author: Island of TeX
-About to run: [ bibtex, doc5 ] @
+About to run: [ bibtex, doc5 ] @
[DR] (PDFLaTeX) PDFLaTeX engine
-----------------------------------------------------------------
Author: Island of TeX
-About to run: [ pdflatex, /home/paulo/Downloads/doc5.tex ] @
+About to run: [ pdflatex, /home/paulo/Downloads/doc5.tex ] @
[DR] (PDFLaTeX) PDFLaTeX engine
-----------------------------------------------------------------
Author: Island of TeX
-About to run: [ pdflatex, /home/paulo/Downloads/doc5.tex ] @
+About to run: [ pdflatex, /home/paulo/Downloads/doc5.tex ] @
Total: 0.23 seconds
\end{codebox}
@@ -285,7 +285,7 @@ In this example, we have a preamble named \abox{twopdftex} and a \TeX\ file name
\begin{codebox}{Terminal}{teal}{\icnote}{white}
$ arara -p twopdftex doc9.tex
- __ _ _ __ __ _ _ __ __ _
+ __ _ _ __ __ _ _ __ __ _
/ _` | '__/ _` | '__/ _` |
| (_| | | | (_| | | | (_| |
\__,_|_| \__,_|_| \__,_|
@@ -299,7 +299,7 @@ Processing 'doc9.tex' (size: 18 B, last modified: 05/29/2018
Total: 0.96 seconds
\end{codebox}
-It is important to note that this is just a directive-based preamble and nothing else, so a line other than a directive is discarded. Line breaks and conditionals are supported. Trying to exploit this area for other purposes will not work. The preamble specification in the configuration file is detailed in Section~\ref{sec:basicstructure}, on page~\pageref{sec:basicstructure}.
+It is important to note that this is just a directive-based preamble and nothing else, so a line other than a directive is discarded. Line breaks and conditionals are supported. Trying to exploit this area for other purposes will not work. The preamble specification in the configuration file is detailed in Section~\ref{sec:basicstructure}, on page~\pageref{sec:basicstructure}.
\item[\describeopp{t}{timeout}{number}] This option sets an execution timeout for every task, in milliseconds. If the timeout is reached before the task ends, \arara\ will kill it and halt the execution. Any positive integer can be used as the \prbox{number} value for this option. Of course, use a sensible value to allow proper time for a task to be executed. For instance, consider the following recursive call:
@@ -312,7 +312,7 @@ This will go \foo forever.
\begin{codebox}{Terminal}{teal}{\icnote}{white}
$ arara --timeout 3000 doc9.tex
- __ _ _ __ __ _ _ __ __ _
+ __ _ _ __ __ _ _ __ __ _
/ _` | '__/ _` | '__/ _` |
| (_| | | | (_| | | | (_| |
\__,_|_| \__,_|_| \__,_|
@@ -379,7 +379,7 @@ Note that other extensions can be added through a proper mapping in the configur
\begin{codebox}{Terminal}{teal}{\icnote}{white}
$ arara doc11.tex
- __ _ _ __ __ _ _ __ __ _
+ __ _ _ __ __ _ _ __ __ _
/ _` | '__/ _` | '__/ _` |
| (_| | | | (_| | | | (_| |
\__,_|_| \__,_|_| \__,_|
@@ -396,7 +396,7 @@ Total: 0.69 seconds
\begin{codebox}{Terminal}{teal}{\icnote}{white}
$ arara doc11
- __ _ _ __ __ _ _ __ __ _
+ __ _ _ __ __ _ _ __ __ _
/ _` | '__/ _` | '__/ _` |
| (_| | | | (_| | | | (_| |
\__,_|_| \__,_|_| \__,_|
@@ -414,7 +414,7 @@ resolve against them as well!
\begin{codebox}{Terminal}{teal}{\icnote}{white}
$ arara doc11.
- __ _ _ __ __ _ _ __ __ _
+ __ _ _ __ __ _ _ __ __ _
/ _` | '__/ _` | '__/ _` |
| (_| | | | (_| | | | (_| |
\__,_|_| \__,_|_| \__,_|
diff --git a/Master/texmf-dist/doc/support/arara/chapters/concepts.tex b/Master/texmf-dist/doc/support/arara/chapters/concepts.tex
index 06122792291..ef71eb10ab9 100644
--- a/Master/texmf-dist/doc/support/arara/chapters/concepts.tex
+++ b/Master/texmf-dist/doc/support/arara/chapters/concepts.tex
@@ -10,7 +10,7 @@ Time for our first proper contact with \arara! I must stress that is very import
A \emph{rule} is a formal description of how \arara\ handles a certain task. For instance, if we want to use \rbox{pdflatex} with our tool, we should have a rule for that. Directives are mapped to rules, so a call to a non-existent rule \rbox{foo}, for instance, will indeed raise an error:
\begin{codebox}{Terminal}{teal}{\icnote}{white}
- __ _ _ __ __ _ _ __ __ _
+ __ _ _ __ __ _ _ __ __ _
/ _` | '__/ _` | '__/ _` |
| (_| | | | (_| | | | (_| |
\__,_|_| \__,_|_| \__,_|
@@ -263,7 +263,7 @@ Note that virtually any type of data can be used as parameter value, so lists, i
When handling parametrized directives, \arara\ always checks if directive parameters and rule arguments match. If we try to inject a non-existent parameter in a parametrized directive, the tool will raise an error about it:
\begin{codebox}{Terminal}{teal}{\icnote}{white}
- __ _ _ __ __ _ _ __ __ _
+ __ _ _ __ __ _ _ __ __ _
/ _` | '__/ _` | '__/ _` |
| (_| | | | (_| | | | (_| |
\__,_|_| \__,_|_| \__,_|
diff --git a/Master/texmf-dist/doc/support/arara/chapters/deploying.tex b/Master/texmf-dist/doc/support/arara/chapters/deploying.tex
index 2dfc68141c8..25932f9f9d2 100644
--- a/Master/texmf-dist/doc/support/arara/chapters/deploying.tex
+++ b/Master/texmf-dist/doc/support/arara/chapters/deploying.tex
@@ -9,7 +9,7 @@ As previously mentioned, \arara\ runs on top of a Java virtual machine, availabl
From the early development stages, our tool employs a very straightforward directory structure. In short, we provide the \abox[araracolour]{ARARA\_HOME} alias to the directory path in which the \rbox[araracolour]{arara.jar} Java archive file is located. This particular file is the heart and soul of our tool and dictates the default rule search path, which is a special directory named \abox[araracolour]{rules/} available from the same level. This directory contains all rules specified in the YAML format, as seen in Section~\ref{sec:rule}, on page~\pageref{sec:rule}. The structure overview is presented as follows.
-\vspace{1em}
+\vspace{1em}
{\centering\begin{forest}
for tree={
@@ -51,7 +51,7 @@ $ mv arara /opt/paulo/
The tool has found a comfortable home inside my system! Observe that the full path of the \abox[araracolour]{ARARA\_HOME} reference points out to \abox[araracolour]{/opt/paulo/arara} since this is my deployment location of choice. The resulting structure overview, from the root directory, is presented as follows:
-\vspace{1em}
+\vspace{1em}
{\centering\begin{forest}
for tree={
@@ -216,4 +216,4 @@ $ which arara
/usr/local/bin/arara
\end{codebox}
-The \rbox{which} command shows the full path of the executable name provided as parameter. This particular utility does this by searching for an executable or script in the directories listed in the \abox[araracolour]{PATH} environment variable. Be mindful that aliases and shell functions are listed as well. \ No newline at end of file
+The \rbox{which} command shows the full path of the executable name provided as parameter. This particular utility does this by searching for an executable or script in the directories listed in the \abox[araracolour]{PATH} environment variable. Be mindful that aliases and shell functions are listed as well.
diff --git a/Master/texmf-dist/doc/support/arara/chapters/introduction.tex b/Master/texmf-dist/doc/support/arara/chapters/introduction.tex
index 11410ff6d3e..77e43685a8c 100644
--- a/Master/texmf-dist/doc/support/arara/chapters/introduction.tex
+++ b/Master/texmf-dist/doc/support/arara/chapters/introduction.tex
@@ -28,7 +28,7 @@ The mentioned tools perform an analysis on the file and decide what has to be do
\begin{codebox}{Terminal}{teal}{\icnote}{white}
$ arara hello.tex
- __ _ _ __ __ _ _ __ __ _
+ __ _ _ __ __ _ _ __ __ _
/ _` | '__/ _` | '__/ _` |
| (_| | | | (_| | | | (_| |
\__,_|_| \__,_|_| \__,_|
@@ -62,8 +62,8 @@ Hello world!
For now, do not worry too much about the terms, we will come back to them later on, in Chapter~\ref{chap:importantconcepts}, on page~\pageref{chap:importantconcepts}. It suffices to say that \arara\ expects \emph{you} to provide a list of tasks, and this is done by inserting special comments in the source file. Let us see how \arara\ behaves with this updated code:
\begin{codebox}{Terminal}{teal}{\icnote}{white}
-$ arara hello.tex
- __ _ _ __ __ _ _ __ __ _
+$ arara hello.tex
+ __ _ _ __ __ _ _ __ __ _
/ _` | '__/ _` | '__/ _` |
| (_| | | | (_| | | | (_| |
\__,_|_| \__,_|_| \__,_|
@@ -81,7 +81,7 @@ Hurrah, we finally got our document properly compiled with a \TeX\ engine by the
\section{Core concepts}
\label{sec:coreconcepts}
-When adding a directive in our source code, we are explicitly telling the tool what we want it to do, but I am afraid that is not sufficient at all. So far, \arara\ knows \emph{what} to do, but now it needs to know \emph{how} the task should be done. If we want \arara\ to run \rbox{pdflatex} on \rbox{hello.tex}, we need to have instructions telling our tool how to run that specific application. This particular sequence of instructions is referred as a \emph{rule} in our context.
+When adding a directive in our source code, we are explicitly telling the tool what we want it to do, but I am afraid that is not sufficient at all. So far, \arara\ knows \emph{what} to do, but now it needs to know \emph{how} the task should be done. If we want \arara\ to run \rbox{pdflatex} on \rbox{hello.tex}, we need to have instructions telling our tool how to run that specific application. This particular sequence of instructions is referred as a \emph{rule} in our context.
\begin{messagebox}{Note on rules}{attentioncolour}{\icattention}{black}
Although the core team provides a lot of rules shipped with \arara\ out of the box, with the possibility of extending the set by adding more rules, some users might find this decision rather annoying, since other tools have most of their rules hard-coded, making the automation process even more transparent. However, since \arara\ does not rely on a specific automation or compilation scheme, it becomes more extensible. The use of directives in the source code make the automation steps more fluent, which allows the specification of complex workflows much easier.
diff --git a/Master/texmf-dist/doc/support/arara/chapters/logging.tex b/Master/texmf-dist/doc/support/arara/chapters/logging.tex
index de8979e02c6..80a4c45a4fd 100644
--- a/Master/texmf-dist/doc/support/arara/chapters/logging.tex
+++ b/Master/texmf-dist/doc/support/arara/chapters/logging.tex
@@ -16,7 +16,7 @@ When running our tool on the previous example with the \opbox{{-}log} command li
\section{System information}
\label{sec:systeminformation}
-The very first entry to appear in the log file is the current version of \arara.
+The very first entry to appear in the log file is the current version of \arara.
\begin{codebox}{Log file}{teal}{\icnote}{white}
Welcome to arara 5.0.0!
diff --git a/Master/texmf-dist/doc/support/arara/chapters/methods.tex b/Master/texmf-dist/doc/support/arara/chapters/methods.tex
index dd6da67902d..7775d5e06bd 100644
--- a/Master/texmf-dist/doc/support/arara/chapters/methods.tex
+++ b/Master/texmf-dist/doc/support/arara/chapters/methods.tex
@@ -597,7 +597,7 @@ According to the \href{https://en.wikipedia.org/wiki/Ordered_pair}{Wikipedia ent
\item[\mtbox{second()}\hfill\rrbox{B}] This method, as the name implies, returns the second entry of the ordered pair, as a \rbox{B} object. It is important to observe that, from the MVEL context, as the method constitutes a property accessor (namely, a getter), the parentheses can be safely omitted.
\end{description}
-Keep in mind that the entries in the \rbox{Pair} class, once defined, cannot be modified to other values. The initial values are set during instantiation and, therefore, only entry getters are available to the user during the object life cycle.
+Keep in mind that the entries in the \rbox{Pair} class, once defined, cannot be modified to other values. The initial values are set during instantiation and, therefore, only entry getters are available to the user during the object life cycle.
\end{messagebox}
\begin{messagebox}{Status for class loading and instantiation}{araracolour}{\icok}{white}
@@ -618,7 +618,7 @@ The class loading and instantiation methods provided by \arara\ typically return
\vspace{1.4em}
-Please make sure to \emph{always} check the returned integer status when using class loading and instantiation methods in directive and rule contexts. This feature is quite powerful yet tricky and subtle!
+Please make sure to \emph{always} check the returned integer status when using class loading and instantiation methods in directive and rule contexts. This feature is quite powerful yet tricky and subtle!
\end{messagebox}
\begin{description}
@@ -807,7 +807,7 @@ From the user perspective, a \rbox{Command} object is simply a good old list of
\vspace{0.4em}
-From the previous example, it is important to observe that a potential file name quoting is not necessary. The underlying system command execution library handles the provided arguments accordingly.
+From the previous example, it is important to observe that a potential file name quoting is not necessary. The underlying system command execution library handles the provided arguments accordingly.
Behind the scenes, however, \arara\ employs a different workflow when constructing a \rbox{Command} object. The tool sets the working directory path for the current command to \abox[araracolour]{USER\_DIR} which is based on the current execution. The working directory path can be explicitly set through specific method calls, described later on in this section.
@@ -870,7 +870,7 @@ return getCommandWithWorkingDirectory('/home/paulo',
\end{codebox}
\end{description}
-The methods presented in this section constitute the foundations of underlying system command execution. In particular, whenever possible, it is highly advisable to use \rbox{Command} objects through proper \mtbox{getCommand} method calls, as the plain string approach used in previous versions of our tool is marked as deprecated and will be removed in future versions.
+The methods presented in this section constitute the foundations of underlying system command execution. In particular, whenever possible, it is highly advisable to use \rbox{Command} objects through proper \mtbox{getCommand} method calls, as the plain string approach used in previous versions of our tool is marked as deprecated and will be removed in future versions.
\section{Others}
\label{sec:others}
@@ -955,7 +955,7 @@ Within a session there are two ``reserved'' namespaces: \verb|arara| and \verb|e
path = getSession().get('environment:PATH');
\end{codebox}
-The \verb|arara| namespace is a bit different. It provides flags that control \arara s behaviour. Flags are used in rules and may be manipulated by the user. Be aware, that every change in this namespace will result in \arara\ acting like you know what you did. Use this power with care. Currently, there is only one relevant flag: \verb|arara:FILENAME:halt|. This will stop the currently run command execution on the file with the specified file name. The value of this map entry is the exit status you want \arara\ to have.
+The \verb|arara| namespace is a bit different. It provides flags that control \arara s behaviour. Flags are used in rules and may be manipulated by the user. Be aware, that every change in this namespace will result in \arara\ acting like you know what you did. Use this power with care. Currently, there is only one relevant flag: \verb|arara:FILENAME:halt|. This will stop the currently run command execution on the file with the specified file name. The value of this map entry is the exit status you want \arara\ to have.
\begin{codebox}{Example}{teal}{\icnote}{white}
path = getSession().put('arara:myfile.tex:halt', 42);
diff --git a/Master/texmf-dist/doc/support/arara/chapters/mvel.tex b/Master/texmf-dist/doc/support/arara/chapters/mvel.tex
index 4ccca9b814d..385e5225106 100644
--- a/Master/texmf-dist/doc/support/arara/chapters/mvel.tex
+++ b/Master/texmf-dist/doc/support/arara/chapters/mvel.tex
@@ -74,7 +74,7 @@ According to the documentation, MVEL allows you to express lists, maps and array
[ "Jim", "Bob", "Smith" ]
\end{codebox}
-Note that lists are denoted by comma-separated values delimited by square brackets. Similarly, maps (sets of key/value attributes) are expressed in the following format:
+Note that lists are denoted by comma-separated values delimited by square brackets. Similarly, maps (sets of key/value attributes) are expressed in the following format:
\begin{codebox}{Creating a map}{teal}{\icnote}{white}
[ "Foo" : "Bar", "Bar" : "Foo" ]
@@ -129,10 +129,10 @@ The expression language goes beyond simple evaluations. In fact, MVEL supports a
if (var > 0) {
r = "greater than zero";
}
-else if (var == 0) {
+else if (var == 0) {
r = "exactly zero";
}
-else {
+else {
r = "less than zero";
}
\end{codebox}
@@ -151,10 +151,10 @@ foreach (name : people) {
}
\end{codebox}
-As expected, MVEL also implements the standard C \rbox{for} loop. Observe that newer versions of MVEL allow an abbreviation of \rbox{foreach} to the usual \rbox{for} statement, as syntactic sugar. In order to explicitly indicate a collection iteration, we usually use \rbox{foreach} in the default rules for \arara, but both statements behave exactly the same from a semantic point of view.
+As expected, MVEL also implements the standard C \rbox{for} loop. Observe that newer versions of MVEL allow an abbreviation of \rbox{foreach} to the usual \rbox{for} statement, as syntactic sugar. In order to explicitly indicate a collection iteration, we usually use \rbox{foreach} in the default rules for \arara, but both statements behave exactly the same from a semantic point of view.
\begin{codebox}{Iteration statement}{teal}{\icnote}{white}
-for (int i = 0; i < 100; i++) {
+for (int i = 0; i < 100; i++) {
System.out.println(i);
}
\end{codebox}
diff --git a/Master/texmf-dist/doc/support/arara/chapters/rules.tex b/Master/texmf-dist/doc/support/arara/chapters/rules.tex
index 759d62e1338..a3f10dc2af8 100644
--- a/Master/texmf-dist/doc/support/arara/chapters/rules.tex
+++ b/Master/texmf-dist/doc/support/arara/chapters/rules.tex
@@ -44,7 +44,7 @@ This rule executes the \rbox{asy} command line, referring to Asymptote, a powerf
\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{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.
@@ -71,7 +71,7 @@ This rule executes the \rbox{asy} command line, referring to Asymptote, a powerf
\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}
+\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.
@@ -134,7 +134,7 @@ This rule executes the \rbox{bib2gls} command line application which extracts gl
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[\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}
@@ -192,6 +192,77 @@ When in doubt, always remember that the \opbox{{-}dry-run} command line option i
% arara: clean: { extensions: [ aux, log ] }
\end{codebox}
+\item[\rulebox{context}]
+This rule runs the \rbox{context} \TeX\ engine on the provided \mtbox{currentFile} reference, generating a corresponding file in the Portable Document File format. Please refer to the user manual for further details.
+
+\begin{description}
+\item[\rpsbox{make}] This option, as the name indicates, sets whether the engine should create context formats. Please refer to the user manual for further details on this option.
+
+\item[\abox{ctx}] This option, as the name indicates, sets the \rbox{ctx} file for process management specification. Please refer to the user manual for further details on this option.
+
+\item[\abox{interface}] This option, as the name indicates, sets the specified user interface. Please refer to the user manual for further details on this option.
+
+\item[\rpsbox{autopdf}] This option, as the name indicates, closes the corresponding \rbox{pdf} file in viewer and then reopens it afterwards.
+
+\item[\abox{purge}] This option, as the name indicates, purges files according to the provided rule. Possible values are:
+
+\begin{description}
+\item[\povalue{partial}] This value, as the name suggests, purges files either or not after a proper run, defined through a pattern. Please refer to the user manual for further details.
+
+\item[\povalue{all}] This value, as the name suggests, purges all files either or not after a proper run, defined through a pattern. Please refer to the user manual for further details.
+
+\item[\povalue{result}] This value, as the name suggests, purges the resulting file before the actual run. Please refer to the user manual for further details.
+\end{description}
+
+\item[\abox{modules}] This option, as the name indicates, sets a list of modules and styles to be loaded, normally part of the distribution.
+
+\item[\abox{environments}] This option, as the name indicates, sets a list of environment files (document styles) to load first.
+
+\item[\abox{mode}] This option, as the name indicates, enables modes according to the provided list (conditional processing in styles).
+
+\item[\abox{path}] This option, as the name indicates, consults the given paths in the provided list during a file lookup.
+
+\item[\abox{arguments}] This option, as the name indicates, sets variables that can be consulted during a run. Such variables are defined as key/value pairs.
+
+\item[\abox{trackers}] This option, as the name indicates, sets the list of tracker variables. Please refer to the user manual for further details.
+
+\item[\abox{directives}] This option, as the name indicates, sets the list of directive variables. Please refer to the user manual for further details.
+
+\item[\abox{silent}] This option, as the name indicates, disables the log categories based on the provided list. Please refer to the user manual for further details.
+
+\item[\abox{errors}] This option, as the name indicates, shows errors at the end of a run and quits when it the provided list. Please refer to the user manual for further details.
+
+\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{interaction}] This option alters the underlying engine behaviour. If this option is omitted, the engine 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.
+\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: context
+\end{codebox}
+
+\item[\rulebox{convert}]
+This rule runs the \rbox{convert} program, a member of the ImageMagick suite of tools. This program is used to convert between image formats as well as resize an image, blur, crop, despeckle, dither, draw on, flip, join, resample, and more.
+
+\begin{description}
+\item[\rpbox{program}{convert}] This option specifies the command utility path as a means to avoid potential clashes with underlying operating system commands.
+
+\item[\abox{options}~\rqbox] 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: convert: { options: [ 'photo1.jpg', '--resize',
+% arara: --> '50%', 'photo2.jpg' ] }
+\end{codebox}
+
\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.
@@ -299,6 +370,37 @@ spreadsheet import functions also use this setting.
% arara: --> csv: booklist.csv }
\end{codebox}
+\item[\rulebox{detex}]
+This rule runs \rbox{detex}, a command line application that, as the name indicates, reads the provided \mtbox{currentFile} reference, removes all comments and \TeX\ control sequences and writes the remainder to the standard output or file.
+
+\begin{description}
+\item[\rpsbox{references}] This option defines whether the tool should echo values from page counters, references and citations.
+
+\item[\rpsbox{follow}] This option defines whether the tool should follow files referenced through typical input mechanisms.
+
+\item[\rpsbox{math}] This option defines whether the tool should replace math with nouns and verbs in order to preserve grammar.
+
+\item[\rpsbox{spaces}] This option, as the name indicates, define whether the tool should replace control sequences with spaces.
+
+\item[\rpsbox{words}] This option, as the name indicates, define whether the tool should output only a list of words.
+
+\item[\abox{environments}] This option takes a list of environments to be ignored by the tool during the text transformation.
+
+\item[\abox{mode}] This option, as the name indicates, defines the operation mode for the tool. Possible values are:
+
+\begin{description}
+\item[\povalue{latex}] This value, as the name suggests, enables and forces the \LaTeX\ mode for the tool.
+
+\item[\povalue{tex}] This value, as the name suggests, enables and forces the plain \TeX\ mode for the tool.
+\end{description}
+
+\item[\abox{output}] This value, as the name indicates, sets the output file in which the contents will be redirected.
+\end{description}
+
+\begin{codebox}{Example}{teal}{\icnote}{white}
+% arara: detex: { output: thesis.txt }
+\end{codebox}
+
\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.
@@ -386,7 +488,52 @@ This rule runs the \rbox{etex} extended (plain) \TeX\ engine on the provided \mt
\end{description}
\begin{codebox}{Example}{teal}{\icnote}{white}
-% arara: etex: { shell: yes }
+% arara: etex: {
+% arara: --> shell: yes,
+% arara: --> interaction: batchmode
+% arara: --> }
+\end{codebox}
+
+\item[\rulebox{fig2dev}]
+This rule runs \rbox{fig2dev}, a command line application that translates \rbox{fig} code in the corresponding base name of the \mtbox{currentFile} reference (i.e, the name without the associated extension) as a string concatenated with the \rbox{fig} suffix into the specified graphics language and puts them in the specified output file.
+
+\begin{description}
+\item[\abox{language}~\rqbox] This option, as the name indicates, sets the output graphics language for proper transformation. Possible values are listed in the following table (you can infer their types as well, based on the values):
+
+\bigskip
+
+{\centering
+\def\arraystretch{1.5}
+\begin{tabularx}{0.8\textwidth}{YYYYYY}
+\povalue{box} & \povalue{cgm} & \povalue{epic} &
+\povalue{eepic} & \povalue{eepicemu} & \povalue{emf}\\
+\povalue{eps} & \povalue{gif} & \povalue{ibmgl} &
+\povalue{jpeg} & \povalue{latex} & \povalue{map}\\
+\povalue{mf} & \povalue{mp} & \povalue{mmp} &
+\povalue{pcx} & \povalue{pdf} & \povalue{pdftex}\\
+\povalue{pdftex\_t} & \povalue{pic} & \povalue{pictex} &
+\povalue{png} & \povalue{ppm} & \povalue{ps}\\
+\povalue{pstex} & \povalue{pstex\_t} & \povalue{ptk} &
+\povalue{shape} & \povalue{sld} & \povalue{svg}\\
+\povalue{textyl} & \povalue{tiff} & \povalue{tk} &
+\povalue{tpic} & \povalue{xbm} & \povalue{xpm}
+\end{tabularx}\par}
+
+\bigskip
+
+\item[\abox{output}~\rqbox] This option, as the name indicates, sets the output file which will contain the translated code based on the provided file and language.
+
+\item[\abox{magnification}] This option, as the name suggests, sets the magnification level at which the figure is rendered.
+
+\item[\abox{font}] This option sets the default font used for text objects to the provided value. Keep in mind that the format of this option depends on the graphics language in use.
+
+\item[\abox{size}] This option, as the name suggests, set the default font size (in points) for text objects to the provided 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: fig2dev: { language: mp, output: drawing.mp }
\end{codebox}
\item[\rulebox{frontespizio}]
@@ -440,7 +587,7 @@ This rule runs \rbox{latexindent}, a Perl script that indents \TeX\ files accord
\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[\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:
@@ -720,7 +867,7 @@ This rule runs \rbox{makeindex}, a general purpose hierarchical index generator,
\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{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}
@@ -951,6 +1098,18 @@ This rule runs \rbox{ps2pdf}, a tool that converts PostScript to Portable Docume
% arara: ps2pdf: { output: article }
\end{codebox}
+\item[\rulebox{qpdf}]
+This rule runs \rbox{qpdf}, a command line application that does structural, content-preserving transformations of Portable Document Files, as well as providing capabilities to developers.
+
+\begin{description}
+\item[\abox{options}~\rqbox] 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: qpdf: { options: [ '--linearize', 'input.pdf',
+% arara: --> 'output.pdf' ] }
+\end{codebox}
+
\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}.
@@ -1002,6 +1161,49 @@ This rule runs the \rbox{tex} \TeX\ engine on the provided \mtbox{currentFile} r
% arara: tex: { shell: yes }
\end{codebox}
+\item[\rulebox{texcount}]
+This rule runs \rbox{texcount}, a Perl script designed to count words in \TeX\ and \LaTeX\ files, ignoring macros, tables, formulae and more on the provided \mtbox{currentFile} reference. The script is highly configurable, so make sure to check the manual for further information.
+
+\begin{description}
+\item[\abox{rules}] This option, as the name suggests, sets the rules which dictate how the script should work regarding word counting and option handling. Possible values are:
+
+\begin{description}
+\item[\povalue{relaxed}] This value, as the name indicates, sets a relaxed set of rules, allowing more general cases to be counted as either words and macros.
+
+\item[\povalue{restricted}] This value, as the name indicates, sets a more restricted set of rules for word counting and option handling.
+\end{description}
+
+\item[\abox{verbosity}] This option, as the name suggests, sets the verbosity level of the script according to the provided integer value. Possible values are:
+
+\begin{description}
+\item[\povalue{\hphantom{x}0\hphantom{x}}] This value sets the lowest verbosity level of all, such that the script does not present parsing details.
+
+\item[\povalue{\hphantom{x}1\hphantom{x}}] This value raises the details a bit and sets the verbosity level to include parsed words and marked formulae.
+
+\item[\povalue{\hphantom{x}2\hphantom{x}}] This value adds more details from the previous verbosity level by including ignored text as well.
+
+\item[\povalue{\hphantom{x}3\hphantom{x}}] This value adds more details from the previous verbosity level by including comments and options.
+
+\item[\povalue{\hphantom{x}4\hphantom{x}}] This value sets the highest verbosity level of all, such that the script includes parsed worded, marked formulae, ignored text, comments, options and internal states.
+\end{description}
+
+\item[\rpsbox{strict}] This option sets whether the tool should enable strict mode, so certain groups for which rules are not defined raise warnings.
+
+\item[\rpsbox{html}] This option, as the name suggests, defines whether the tool should output the report in the HTML format.
+
+\item[\rpsbox{total}] This option, as the name suggests, defines whether the tool should provide a total sum instead of partial sums (per file).
+
+\item[\rpsbox{unicode}] This option, as the name indicates, defines whether the tool should select Unicode as encoding for both input and output.
+
+\item[\abox{output}] This option, as the name suggests, sets the output file name in which the report will be written.
+
+\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: texcount: { output: report.txt }
+\end{codebox}
+
\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.
diff --git a/Master/texmf-dist/doc/support/arara/chapters/yaml.tex b/Master/texmf-dist/doc/support/arara/chapters/yaml.tex
index c65c9898d72..bc6d63893c7 100644
--- a/Master/texmf-dist/doc/support/arara/chapters/yaml.tex
+++ b/Master/texmf-dist/doc/support/arara/chapters/yaml.tex
@@ -68,8 +68,8 @@ Scalar content can be written in block notation, using a literal style, indicate
\begin{codebox}{Scalar content in literal and folded styles}{teal}{\icnote}{white}
logo: |
This is the arara logo
- in its ASCII glory!
- __ _ _ __ __ _ _ __ __ _
+ in its ASCII glory!
+ __ _ _ __ __ _ _ __ __ _
/ _` | '__/ _` | '__/ _` |
| (_| | | | (_| | | | (_| |
\__,_|_| \__,_|_| \__,_|