summaryrefslogtreecommitdiff
path: root/support/arara/doc/chapters/introduction.tex
diff options
context:
space:
mode:
Diffstat (limited to 'support/arara/doc/chapters/introduction.tex')
-rw-r--r--support/arara/doc/chapters/introduction.tex25
1 files changed, 7 insertions, 18 deletions
diff --git a/support/arara/doc/chapters/introduction.tex b/support/arara/doc/chapters/introduction.tex
index f064774c9a..11410ff6d3 100644
--- a/support/arara/doc/chapters/introduction.tex
+++ b/support/arara/doc/chapters/introduction.tex
@@ -33,7 +33,7 @@ $ arara hello.tex
| (_| | | | (_| | | | (_| |
\__,_|_| \__,_|_| \__,_|
-Processing 'hello.tex' (size: 86 bytes, last modified: 05/03/2018
+Processing 'hello.tex' (size: 86 B, last modified: 05/03/2018
07:28:30), please wait.
It looks like no directives were found in the provided file. Make
@@ -68,7 +68,7 @@ $ arara hello.tex
| (_| | | | (_| | | | (_| |
\__,_|_| \__,_|_| \__,_|
-Processing 'hello.tex' (size: 86 bytes, last modified: 05/03/2018
+Processing 'hello.tex' (size: 86 B, last modified: 05/03/2018
07:28:30), please wait.
(PDFLaTeX) PDFLaTeX engine .............................. SUCCESS
@@ -84,8 +84,7 @@ Hurrah, we finally got our document properly compiled with a \TeX\ engine by the
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 very easy.
-% "very easy" -> "much easier" perhaps?
+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.
\end{messagebox}
Despite the inherited verbosity of automation steps not being suitable for small documents, \arara\ really shines when you have a document which needs full control of the automation process (for instance, a thesis or a manual). Complex workflows are easily tackled by our tool.
@@ -120,28 +119,18 @@ An \arara\ directive is usually defined in a line of its own, started with a com
Our example has one directive, referencing \rbox{pdflatex}. It is important to observe that the \rbox{pdflatex} identifier \emph{does not represent the command to be executed}, but \emph{the name of the rule associated with that directive}.
-\begin{messagebox}{New feature in version 4.0}{araracolour}{\icinfo}{white}
-\textbf{Multiline directives} -- Later on, in Section~\ref{sec:directives}, on page~\pageref{sec:directives}, we will discover that a directive can also span several lines in order to provide a better code organization. For now, let us assume a typical directive occupies only one line.
-\end{messagebox}
-
-Once \arara\ finds a directive, it will look for the associated \emph{rule}. In our example, it will look for a rule named \rbox{pdflatex} which will evidently run the \rbox{pdflatex} command line application. Rules are \gls{YAML} files named according to their identifiers followed by the \rbox{yaml} extension and follow a strict structure. This concept is covered in Section~\ref{sec:rule}, on page~\pageref{sec:rule}.
-
-\begin{messagebox}{New feature in version 4.0}{araracolour}{\icattention}{white}
-\textbf{\gls{REPL} workflow} -- \arara\ now employs a \gls{REPL} workflow for rules and directives. In previous versions, directives were extracted, their corresponding rules were analyzed, commands were built and added to a queue before any proper execution or evaluation. I decided to change this workflow, so now \arara\ evaluates each rule on demand, i.e, there is no \emph{a priori} checking. A rule will \emph{always} reflect the current state, including potential side effects from previous executed rules.
-\end{messagebox}
+Once \arara\ finds a directive, it will look for the associated \emph{rule}. In our example, it will look for a rule named \rbox{pdflatex} which will evidently run the \rbox{pdflatex} command line application. Rules are YAML files named according to their identifiers followed by the \rbox{yaml} extension and follow a strict structure. This concept is covered in Section~\ref{sec:rule}, on page~\pageref{sec:rule}.
Now, we have a queue of pairs $(\textit{directive}, \textit{rule})$ to process. For each pair, \arara\ will map the directive to its corresponding rule, evaluate it and run the proper command. The execution chain requires that command $i$ was successfully executed to then proceed to command $i+1$, and so forth. This is also by design: \arara\ will halt the execution if any of the commands in the queue had raised an error. How does one know if a command was successfully executed? \arara\ checks the corresponding \emph{exit status} available after a command execution. In general, a successful execution yields 0 as its exit status.
-\begin{messagebox}{New feature in version 4.0}{araracolour}{\icinfo}{white}
-\textbf{Custom exit status checking} -- In previous versions, there was no way of customizing the exit status checking of a command. A command was successful if, and only if, its resulting exit status was 0 and no other value. From now on, we can define any value, or even forget about it and make it always return a valid status regardless of execution (for instance, in a rule that always is successful -- see, for instance, the \rbox{clean} rule).
-\end{messagebox}
+In order to decide whether a command execution is successful, \arara\ relies on exit status checking. Typically, a command is successful if, and only if, its resulting exit status is 0 and no other value. However, we can define any value, or even forget about it and make it always return a valid status regardless of execution (for instance, in a rule that always is successful -- see, for instance, the \rbox{clean} rule).
That is pretty much how \arara\ works: directives in the source code are mapped to rules. These pairs are added to a queue. The queue is then executed and the status is reported. More details about the expansion process are presented in Chapter~\ref{chap:importantconcepts}, on page~\pageref{chap:importantconcepts}. In short, we teach \arara\ to do a task by providing a rule, and tell it to execute it through directives in the source code.
\section{Operating system remarks}
\label{sec:operatingsystemremarks}
-The application is written using the Java language, so \arara\ runs on top of a Java virtual machine, available on all the major operating systems~--~in some cases, you might need to install the proper virtual machine. We tried very hard to keep both code and libraries compatible with older virtual machines or from other vendors. Currently, \arara\ is known to run on Oracle's Java 5 to 10, and OpenJDK 5 to 10. We also have reports of users successfully using the tool with virtual machines provided by Azul Systems, so your mileage might vary greatly.
+The application is written using the Kotlin language (and some pieces of Java), so \arara\ runs on top of a Java virtual machine, available on all the major operating systems~--~in some cases, you might need to install the proper virtual machine. We tried very hard to keep both code and libraries compatible with older virtual machines or from other vendors. Currently, \arara\ is known to run on Oracle's Java 8 to 13, OpenJDK 8 to 13 and ZuluFX 8 and 11.
\begin{messagebox}{Outdated Java virtual machines}{attentioncolour}{\icerror}{black}
Dear reader, beware of outdated software, mainly Java virtual machines! Although \arara\ offers support for older virtual machines, try your best to keep your software updated as frequently as possible. The legacy support exists only for historical reasons, and also due to the sheer fact that we know some people that still runs \arara\ on very old hardware. If you are not in this particular scenario, get the latest virtual machine.
@@ -152,6 +141,6 @@ In Chapter~\ref{chap:buildingfromsource}, on page~\pageref{chap:buildingfromsour
\section{Support}
\label{sec:support}
-If you run into any issue with \arara, please let us know. We all have very active profiles in the \href{https://tex.stackexchange.com/}{\TeX\ community at StackExchange}, so just use the \rbox[araracolour]{arara} tag in your question and we will help you the best we can (also, take a look at their \href{https://tex.meta.stackexchange.com/q/1436}{starter guide}). We also have a \href{https://gitter.im/cereda/arara}{Gitter chat room}, in which we occasionally hang out. Also, if you think the report is worthy of an issue, open one in our \href{https://github.com/cereda/arara/issues}{GitHub repository}. And last, but not least, feel free to poke us by good old electronic mail (please try the other approaches first).
+If you run into any issue with \arara, please let us know. We all have very active profiles in the \href{https://tex.stackexchange.com/}{\TeX\ community at StackExchange}, so just use the \rbox[araracolour]{arara} tag in your question and we will help you the best we can (also, take a look at their \href{https://tex.meta.stackexchange.com/q/1436}{starter guide}). We also have a \href{https://gitter.im/cereda/arara}{Gitter chat room}, in which we occasionally hang out. Also, if you think the report is worthy of an issue, open one in our \href{https://gitlab.com/islandoftex/arara/issues}{GitLab repository}.
We really hope you like our humble contribution to the \TeX\ community. Let \arara\ enhance your \TeX\ experience, it will help you when you will need it the most. Enjoy the manual.