summaryrefslogtreecommitdiff
path: root/support/arara/doc/chapters/cli.tex
diff options
context:
space:
mode:
Diffstat (limited to 'support/arara/doc/chapters/cli.tex')
-rw-r--r--support/arara/doc/chapters/cli.tex154
1 files changed, 98 insertions, 56 deletions
diff --git a/support/arara/doc/chapters/cli.tex b/support/arara/doc/chapters/cli.tex
index ddf318bc67..60678e88d5 100644
--- a/support/arara/doc/chapters/cli.tex
+++ b/support/arara/doc/chapters/cli.tex
@@ -7,30 +7,30 @@
\section{User interface design}
\label{sec:userinterfacedesign}
-The goal of a user interface design is to make the interaction as simple and efficient as possible. Good user interface design facilitates finishing the task at hand without drawing unnecessary attention to itself. For \arara\ 4.0, we redesigned the interface in order to look more pleasant to the eye, after all, we work with \TeX\ and friends:
+The goal of a user interface design is to make the interaction as simple and efficient as possible. Good user interface design facilitates finishing the task at hand without drawing unnecessary attention to itself. We redesigned the interface in order to look more pleasant to the eye, after all, we work with \TeX\ and friends:
\begin{codebox}{Terminal}{teal}{\icnote}{white}
- __ _ _ __ __ _ _ __ __ _
+ __ _ _ __ __ _ _ __ __ _
/ _` | '__/ _` | '__/ _` |
| (_| | | | (_| | | | (_| |
\__,_|_| \__,_|_| \__,_|
-Processing 'doc5.tex' (size: 307 bytes, last modified: 05/29/2018
-08:57:30), please wait.
+Processing 'doc5.tex' (size: 285 B, last modified: 03/01/2020
+19:25:40), please wait.
(PDFLaTeX) PDFLaTeX engine .............................. SUCCESS
(BibTeX) The BibTeX reference management software ....... SUCCESS
(PDFLaTeX) PDFLaTeX engine .............................. SUCCESS
(PDFLaTeX) PDFLaTeX engine .............................. SUCCESS
-Total: 1.45 seconds
+Total: 1.14 seconds
\end{codebox}
First of all, we have the nice application logo, displayed using ASCII art. The entire layout is based on monospaced font spacing, usually used in terminal prompts. Hopefully you follow the conventional use of a monospaced font in your terminal, otherwise the visual effect will not be so pleasant. First and foremost, \arara\ displays details about the file being processed, including size and modification status:
\begin{codebox}{Terminal}{teal}{\icnote}{white}
-Processing 'doc5.tex' (size: 307 bytes, last modified: 05/29/2018
-08:57:30), please wait.
+Processing 'doc5.tex' (size: 285 B, last modified: 03/01/2020
+19:25:40), please wait.
\end{codebox}
The list of tasks was also redesigned to be fully justified, and each entry displays both task and subtask names (the former being displayed enclosed in parentheses), besides of course the usual execution result:
@@ -51,7 +51,7 @@ As previously mentioned in Section~\ref{sec:rule}, on page~\pageref{sec:rule}, i
Also, observe that our tool displays the execution time before terminating, in seconds. The execution time has a very simple precision, as it is meant to be easily readable, and should not be considered for command profiling.
\begin{codebox}{Terminal}{teal}{\icnote}{white}
-Total: 1.45 seconds
+Total: 1.14 seconds
\end{codebox}
The tool has two execution modes: \emph{silent}, which is the default, and \emph{verbose}, which prints as much information about tasks as possible. When in silent mode, \arara\ will simply display the task and subtask names, as well as the execution result. Nothing more is added to the output. For instance:
@@ -66,7 +66,7 @@ When executed in verbose mode, \arara\ will display the underlying system comman
-----------------------------------------------------------------
(BibTeX) The BibTeX reference management software
-----------------------------------------------------------------
-This is BibTeX, Version 0.99d (TeX Live 2017)
+This is BibTeX, Version 0.99d (TeX Live 2019)
The top-level auxiliary file: doc5.aux
The style file: plain.bst
Database file #1: mybib.bib
@@ -85,35 +85,57 @@ In order to run \arara\ on your \TeX\ file, the simplest possible way is to prov
$ arara doc6.tex
\end{codebox}
+From version 5.0 on, \arara\ may receive more than one file as parameter. It will compile them sequentially (starting with the leftmost). The process fails on the first failure of these executions. For the files to be flawlessly compiled by \TeX, they should be in the same working directory. If you process your files with other tools, this requirement could be lifted.
+
+\begin{codebox}{Terminal}{teal}{\icnote}{white}
+$ arara doc20.tex doc21.tex
+ __ _ _ __ __ _ _ __ __ _
+ / _` | '__/ _` | '__/ _` |
+| (_| | | | (_| | | | (_| |
+ \__,_|_| \__,_|_| \__,_|
+
+Processing 'doc20.tex' (size: 28 B, last modified: 02/28/2020
+07:15:02), please wait.
+
+(PDFTeX) PDFTeX engine .................................. SUCCESS
+
+Processing 'doc21.tex' (size: 28 B, last modified: 02/28/2020
+07:15:10), please wait.
+
+(PDFTeX) PDFTeX engine .................................. SUCCESS
+
+Total: 1.20 seconds
+\end{codebox}
+
The tool has a set of command line options (also known as flags or switches) that modify the underlying execution behaviour or enhance the execution workflow. If you do not provide any parameters, \arara\ will display the tool usage and the available options:
\begin{codebox}{Terminal}{teal}{\icnote}{white}
$ arara
- __ _ _ __ __ _ _ __ __ _
+ __ _ _ __ __ _ _ __ __ _
/ _` | '__/ _` | '__/ _` |
| (_| | | | (_| | | | (_| |
\__,_|_| \__,_|_| \__,_|
-arara 4.0 (revision 1)
-Copyright (c) 2012-2017, Paulo Roberto Massa Cereda
-All rights reserved
-
-usage: arara [file [--dry-run] [--log] [--verbose | --silent]
- [--timeout N] [--max-loops N] [--language L]
- [ --preamble P ] [--header] | --help | --version]
- -h,--help print the help message
- -H,--header extract directives only in the file header
- -l,--log generate a log output
- -L,--language <code> set the application language
- -m,--max-loops <number> set the maximum number of loops
- -n,--dry-run go through all the motions of running a
- command, but with no actual calls
- -p,--preamble <name> set the file preamble based on the
- configuration file
- -s,--silent hide the command output
- -t,--timeout <number> set the execution timeout (in milliseconds)
- -V,--version print the application version
- -v,--verbose print the command output
+Usage: arara [OPTIONS] [file]...
+
+Options:
+ -l, --log Generate a log output
+ -v, --verbose / -s, --silent Print the command output
+ -n, --dry-run Go through all the motions of running a
+ command, but with no actual calls
+ -H, --header Extract directives only in the file header
+ -t, --timeout INT Set the execution timeout (in milliseconds)
+ -L, --language TEXT Set the application language
+ -m, --max-loops INT Set the maximum number of loops (> 0)
+ -p, --preamble TEXT Set the file preamble based on the
+ configuration file
+ -d, --working-directory DIRECTORY
+ Set the working directory for all tools
+ -V, --version Show the version and exit
+ -h, --help Show this message and exit
+
+Arguments:
+ file The file(s) to evaluate and process
\end{codebox}
The available options for our tool are detailed as follows. Each option contains short and long variations, which are denoted by \opbox{o} and \opbox{{-}option} in the command line, respectively. Additionally, when a parameter is required by the current option, it will be denoted by \prbox{parameter} in the description.
@@ -139,20 +161,20 @@ When running \arara\ without this option, two directives will be extracted (the
\begin{codebox}{Terminal}{teal}{\icnote}{white}
$ arara -L nl doc5.tex
- __ _ _ __ __ _ _ __ __ _
+ __ _ _ __ __ _ _ __ __ _
/ _` | '__/ _` | '__/ _` |
| (_| | | | (_| | | | (_| |
\__,_|_| \__,_|_| \__,_|
-Verwerken van 'doc5.tex' (grootte: 307 bytes, laatst gewijzigd:
-05/29/2018 11:50:32), een ogenblik geduld.
+Verwerken van 'doc5.tex' (grootte: 285 B, laatst gewijzigd:
+03/01/2020 19:25:40), een ogenblik geduld.
-(PDFLaTeX) PDFLaTeX engine ............................ SUCCESVOL
-(BibTeX) The BibTeX reference management software ..... SUCCESVOL
-(PDFLaTeX) PDFLaTeX engine ............................ SUCCESVOL
-(PDFLaTeX) PDFLaTeX engine ............................ SUCCESVOL
+(PDFLaTeX) PDFLaTeX engine .............................. SUCCESVOL
+(BibTeX) The BibTeX reference management software ....... SUCCESVOL
+(PDFLaTeX) PDFLaTeX engine .............................. SUCCESVOL
+(PDFLaTeX) PDFLaTeX engine .............................. SUCCESVOL
-Totaal: 1,59 seconden
+Totaal: 1,07 seconden
\end{codebox}
\begin{messagebox}{Navis volitans mihi anguillis plena est}{araracolour}{\icok}{white}
@@ -174,7 +196,7 @@ At time of writing, \arara\ is able to speak English, German, Dutch, Italian and
\vspace{1.4em}
-Would you like to make \arara\ speak your own language? Splendid! We would love to have you in the team! Just send us an electronic mail, join our \href{https://gitter.im/cereda/arara}{dedicated chatroom} or \href{https://github.com/cereda/arara/issues}{open an issue} about it. The localization process is quite straightforward, we can help you. Any language is welcome!
+Would you like to make \arara\ speak your own language? Splendid! We would love to have you in the team! Just send us an electronic mail, join our \href{https://gitter.im/cereda/arara}{dedicated chatroom} or \href{https://gitlab.com/islandoftex/arara/issues}{open an issue} about it. The localization process is quite straightforward, we can help you. Any language is welcome!
\end{messagebox}
This option can also be specified in the configuration file (see Section~\ref{sec:basicstructure}, on page~\pageref{sec:basicstructure}). However, one can always override this setting by running the tool with an explicit \opbox{L} option.
@@ -194,7 +216,7 @@ $ arara -m 2 doc8.tex
| (_| | | | (_| | | | (_| |
\__,_|_| \__,_|_| \__,_|
-Processing 'doc8.tex' (size: 45 bytes, last modified: 05/29/2018
+Processing 'doc8.tex' (size: 45 B, last modified: 05/29/2018
12:32:14), please wait.
(PDFTeX) PDFTeX engine .................................. SUCCESS
@@ -209,35 +231,35 @@ This option can also be specified in the configuration file (see Section~\ref{se
\begin{codebox}{Terminal}{teal}{\icnote}{white}
$ arara -n doc5.tex
- __ _ _ __ __ _ _ __ __ _
+ __ _ _ __ __ _ _ __ __ _
/ _` | '__/ _` | '__/ _` |
| (_| | | | (_| | | | (_| |
\__,_|_| \__,_|_| \__,_|
-Processing 'doc5.tex' (size: 307 bytes, last modified: 05/29/2018
-11:50:32), please wait.
+Processing 'doc5.tex' (size: 285 B, last modified: 03/01/2020
+19:25:40), please wait.
[DR] (PDFLaTeX) PDFLaTeX engine
-----------------------------------------------------------------
-Authors: Marco Daniel, Paulo Cereda
-About to run: [ pdflatex, doc5.tex ]
+Author: Island of TeX
+About to run: [ pdflatex, /home/paulo/Downloads/doc5.tex ] @
[DR] (BibTeX) The BibTeX reference management software
-----------------------------------------------------------------
-Authors: Marco Daniel, Paulo Cereda
-About to run: [ bibtex, doc5 ]
+Author: Island of TeX
+About to run: [ bibtex, doc5 ] @
[DR] (PDFLaTeX) PDFLaTeX engine
-----------------------------------------------------------------
-Authors: Marco Daniel, Paulo Cereda
-About to run: [ pdflatex, doc5.tex ]
+Author: Island of TeX
+About to run: [ pdflatex, /home/paulo/Downloads/doc5.tex ] @
[DR] (PDFLaTeX) PDFLaTeX engine
-----------------------------------------------------------------
-Authors: Marco Daniel, Paulo Cereda
-About to run: [ pdflatex, doc5.tex ]
+Author: Island of TeX
+About to run: [ pdflatex, /home/paulo/Downloads/doc5.tex ] @
-Total: 0.27 seconds
+Total: 0.23 seconds
\end{codebox}
Note that the rule authors are displayed (so they can be blamed in case anything goes wrong), as well as the system command to be executed. It is an interesting approach to see everything that will happen to your document and in which order.
@@ -268,7 +290,7 @@ $ arara -p twopdftex doc9.tex
| (_| | | | (_| | | | (_| |
\__,_|_| \__,_|_| \__,_|
-Processing 'doc9.tex' (size: 18 bytes, last modified: 05/29/2018
+Processing 'doc9.tex' (size: 18 B, last modified: 05/29/2018
14:39:21), please wait.
(PDFTeX) PDFTeX engine .................................. SUCCESS
@@ -295,7 +317,7 @@ $ arara --timeout 3000 doc9.tex
| (_| | | | (_| | | | (_| |
\__,_|_| \__,_|_| \__,_|
-Processing 'doc10.tex' (size: 63 bytes, last modified: 05/29/2018
+Processing 'doc10.tex' (size: 63 B, last modified: 05/29/2018
15:24:06), please wait.
(PDFTeX) PDFTeX engine ................................. ERROR
@@ -314,6 +336,8 @@ Total: 3.37 seconds
If left unattended, this particular execution would never finish (and probably crash the engine at a certain point), as expected by the recursive calls without a proper fixed point. The \opbox{{-}timeout} option was set at 3000 milliseconds and the task was aborted when the time limit was reached. Note that the tool raised an error about it.
+\item[\describeop{d}{working-directory}] This option allows you to change the working directory. That is, the commands will run from a different directory than the directory you launched \arara\ in. This is especially useful when calling a \TeX\ engine as they resolve files against the working direcotry. For that reason, \arara\ will also resolve each file you pass to it that has no absolute path against the working directory. The working directory is fixed for the whole call; passing multiple files to \arara\ will resolve all of them against and execute all actions within that one working directory.
+
\item[\describeop{V}{version}] This option, as the name indicates, prints the current version. It also prints the current revision and a list of libraries with their corresponding licenses. Finally, it simply exits the application. Note that this option has the second highest priority over the others.
\item[\describeop{v}{verbose}] This option enables the verbose mode of \arara, as seen in Section~\ref{sec:userinterfacedesign}, on page~\pageref{sec:userinterfacedesign}. It also enables all streams to be flushed directly to the terminal, including potential user input interactions (the exact opposite of silent mode). This option can also be activated by default in the configuration file (see Section~\ref{sec:basicstructure}, on page~\pageref{sec:basicstructure}).
@@ -360,7 +384,7 @@ $ arara doc11.tex
| (_| | | | (_| | | | (_| |
\__,_|_| \__,_|_| \__,_|
-Processing 'doc11.tex' (size: 34 bytes, last modified: 05/29/2018
+Processing 'doc11.tex' (size: 34 B, last modified: 05/29/2018
19:40:35), please wait.
(PDFTeX) PDFTeX engine .................................. SUCCESS
@@ -377,7 +401,25 @@ $ arara doc11
| (_| | | | (_| | | | (_| |
\__,_|_| \__,_|_| \__,_|
-Processing 'doc11.tex' (size: 34 bytes, last modified: 05/29/2018
+Processing 'doc11.tex' (size: 34 B, last modified: 05/29/2018
+19:40:35), please wait.
+
+(PDFTeX) PDFTeX engine .................................. SUCCESS
+
+Total: 0.69 seconds
+\end{codebox}
+
+\item Many shells complete file names that have multiple extensions in the same directory, so that they end with a period. We try to
+resolve against them as well!
+
+\begin{codebox}{Terminal}{teal}{\icnote}{white}
+$ arara doc11.
+ __ _ _ __ __ _ _ __ __ _
+ / _` | '__/ _` | '__/ _` |
+| (_| | | | (_| | | | (_| |
+ \__,_|_| \__,_|_| \__,_|
+
+Processing 'doc11.tex' (size: 34 B, last modified: 05/29/2018
19:40:35), please wait.
(PDFTeX) PDFTeX engine .................................. SUCCESS