summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/doc/support/arara/chapters/configuration.tex
diff options
context:
space:
mode:
Diffstat (limited to 'Master/texmf-dist/doc/support/arara/chapters/configuration.tex')
-rw-r--r--Master/texmf-dist/doc/support/arara/chapters/configuration.tex28
1 files changed, 14 insertions, 14 deletions
diff --git a/Master/texmf-dist/doc/support/arara/chapters/configuration.tex b/Master/texmf-dist/doc/support/arara/chapters/configuration.tex
index 35553378d2d..e7aba4102b7 100644
--- a/Master/texmf-dist/doc/support/arara/chapters/configuration.tex
+++ b/Master/texmf-dist/doc/support/arara/chapters/configuration.tex
@@ -26,7 +26,7 @@ Our tool looks for the presence of at least one of four very specific files befo
\vspace{1.4em}
-From version 4.0 on, \arara\ provides two approaches regarding the location of a configuration file. They dictate how the execution should behave and happen from a user perspective, and are described as follows.
+\arara\ provides two approaches regarding the location of a configuration file. They dictate how the execution should behave and happen from a user perspective, and are described as follows.
\begin{description}
\item[global configuration file] For this approach, the configuration file should be located at \abox[araracolour]{USER\_HOME} which is the home directory of the current user. All subsequent executions of \arara\ will read this configuration file and apply the specified settings accordingly. However, it is important to note that this approach has the lowest lookup priority, which means that a local configuration, presented as follows, will always supersede a global counterpart.
@@ -43,7 +43,7 @@ If the logging feature is properly enabled, \arara\ will indicate in the corresp
\section{Basic structure}
\label{sec:basicstructure}
-The following list describes the basic structure of an \arara\ configuration file by presenting the proper elements (or keys, if we consider the proper \gls{YAML} nomenclature). Observe that elements marked as \rbox[araracolour]{M} are mandatory (i.e, the configuration file \emph{has} to have them in order to work). Similarly, elements marked as \rbox[araracolour]{O} are optional, so you can safely ignore them when writing a configuration file for our tool.
+The following list describes the basic structure of an \arara\ configuration file by presenting the proper elements (or keys, if we consider the proper YAML nomenclature). Observe that elements marked as \rbox[araracolour]{M} are mandatory (i.e, the configuration file \emph{has} to have them in order to work). Similarly, elements marked as \rbox[araracolour]{O} are optional, so you can safely ignore them when writing a configuration file for our tool.
\begin{description}
\item[\describe{M}{!config}] This keyword is mandatory and must be the first line of a configuration file. It denotes the object mapping metadata to be internally used by the tool. Actually, the tool is not too demanding on using it (in fact, you could suppress it entirely and \arara\ will not complain), but it is considered good practice to start a configuration file with a \abox{!config} keyword regardless.
@@ -56,7 +56,7 @@ paths:
- '/opt/paulo/rules'
\end{codebox}
-There are three variables available in the \abox{paths} context and are described as follows (note that \gls{MVEL} variables and \glspl{orb-tag} are discussed in Chapter~\ref{sec:mvelbasicusage}). A variable will be denoted by \varbox{variable} in this list.
+There are three variables available in the \abox{paths} context and are described as follows (note that MVEL variables and orb tags are discussed in Chapter~\ref{sec:mvelbasicusage}). A variable will be denoted by \varbox{variable} in this list.
\begin{description}
\item[\varbox{user.home}] This variable, as the name implies, holds the value of the absolute, canonical path of \abox[araracolour]{USER\_HOME} which is the home directory of the current user, as plain string. Note that the specifics of the home directory (such as name and location) are defined by the operating system involved.
@@ -66,25 +66,25 @@ paths:
- '@{user.home}/rules'
\end{codebox}
-\item[\varbox{user.dir}] This variable, as the name implies, holds the value of the absolute, canonical path of \abox[araracolour]{USER\_DIR} which is the working directory associated with the current execution, as plain string. Note that the working directory approach requires a user execution strategy to ensure the correct path value.
+\item[\varbox{user.name}] This variable, as the name implies, holds the value of the current user account name, as plain string. On certain operating systems, this value is used to build the home directory structure.
\begin{codebox}{Example}{teal}{\icnote}{white}
paths:
-- '@{user.dir}/rules'
+- '/home/@{user.name}/rules'
\end{codebox}
-\item[\varbox{user.name}] This variable, as the name implies, holds the value of the current user account name, as plain string. On certain operating systems, this value is used to build the home directory structure.
-\end{description}
+\item[\varbox{application.workingDirectory}] This variable, as the name implies, holds the value of the absolute, canonical path of the working directory associated with the current execution, as plain string.
\begin{codebox}{Example}{teal}{\icnote}{white}
paths:
-- '/home/@{user.name}/rules'
+- '@{application.workingDirectory}/rules'
\end{codebox}
+\end{description}
-Observe that the \varbox{user} variable actually holds a map containing three keys (resulting in a map within a map). However, for didactic purposes, it is easier to use the property navigation feature of \gls{MVEL}, detailed in Section~\ref{sec:propertynavigation}, on page~\pageref{sec:propertynavigation}, and consider the map references as three independent variables. You can use property navigation styles interchangeably. Note that you can also precede the path with the special keyword \rbox{<arara>} and save some quotes (see Section~\ref{sec:rule}, on page~\pageref{sec:rule}). In this specific scenario, the special keyword will be automatically removed afterwards.
+Observe that the \varbox{user} variable actually holds a map containing two keys (resulting in a map within a map). However, for didactic purposes, it is easier to use the property navigation feature of MVEL, detailed in Section~\ref{sec:propertynavigation}, on page~\pageref{sec:propertynavigation}, and consider the map references as three independent variables. You can use property navigation styles interchangeably. Note that you can also precede the path with the special keyword \rbox{<arara>} and save some quotes (see Section~\ref{sec:rule}, on page~\pageref{sec:rule}, but keep in mind that this special keyword is marked as deprecated and will be removed in future versions). In this specific scenario, the special keyword will be automatically removed afterwards.
\begin{messagebox}{Avoid folded and literal styles for scalars in a path}{attentioncolour}{\icattention}{black}
-Do not use folded or literal styles for scalars in a path! The \gls{orb-tag} resolution for a path in plain string should be kept as simple as possible, so \emph{always} use the inline style.
+Do not use folded or literal styles for scalars in a path! The orb tag resolution for a path in plain string should be kept as simple as possible, so \emph{always} use the inline style.
\end{messagebox}
\item[\describecf{O}{string}{language}{en}] This key sets the language of all subsequent executions of \arara\ according to the provided language code value, as plain string. The default language is set to English. Also, it is very important to observe that the \opbox{{-}language} command line option can override this setting.
@@ -117,19 +117,19 @@ logging: true
header: false
\end{codebox}
-\item[\describecf{O}{string}{logname}{arara}] This key modifies the default log file name, according to the associated plain string value, plus the \rbox{log} extension. The value cannot be empty or contain invalid characters. There is no \gls{orb-tag} evaluation in this specific context, only a plain string value. The log file will be written by our tool if, and only if, the \opbox{{-}log} command line option is used.
+\item[\describecf{O}{string}{logname}{arara}] This key modifies the default log file name, according to the associated plain string value, plus the \rbox{log} extension. The value cannot be empty or contain invalid characters. There is no orb tag evaluation in this specific context, only a plain string value. The log file will be written by our tool if, and only if, the \opbox{{-}log} command line option is used.
\begin{codebox}{Example}{teal}{\icnote}{white}
logname: mylog
\end{codebox}
-\item[\describecf{O}{string}{dbname}{arara}] This key modifies the default \gls{XML} database file name, according to the associated plain string value, plus the \rbox{xml} extension. The value cannot be empty or contain invalid characters. There is no \gls{orb-tag} evaluation in this specific context, only a plain string value. This database is used by file hashing operations, detailed in Section~\ref{sec:files}, on page~\pageref{sec:files}.
+\item[\describecf{O}{string}{dbname}{arara}] This key modifies the default YAML database file name, according to the associated plain string value, plus the \rbox{yaml} extension. The value cannot be empty or contain invalid characters. There is no orb tag evaluation in this specific context, only a plain string value. This database is used by file hashing operations, detailed in Section~\ref{sec:files}, on page~\pageref{sec:files}.
\begin{codebox}{Example}{teal}{\icnote}{white}
dbname: mydb
\end{codebox}
-\item[\describecf{O}{string}{laf}{none}] This key modifies the default look and feel class reference, i.e, the appearance of \gls{GUI} widgets provided by our tool, according to the associated plain string value. The value cannot be empty or contain invalid characters. There is no \gls{orb-tag} evaluation in this specific context, only a plain string value. This look and feel setting is used by UI methods, detailed in Section~\ref{sec:dialogboxes}, on page~\pageref{sec:dialogboxes}. Note that this value is used by the underlying Java runtime environment, so a full qualified class name is expected.
+\item[\describecf{O}{string}{laf}{none}] This key modifies the default look and feel class reference, i.e, the appearance of GUI widgets provided by our tool, according to the associated plain string value. The value cannot be empty or contain invalid characters. There is no orb tag evaluation in this specific context, only a plain string value. This look and feel setting is used by UI methods, detailed in Section~\ref{sec:dialogboxes}, on page~\pageref{sec:dialogboxes}. Note that this value is used by the underlying Java runtime environment, so a full qualified class name is expected.
\begin{codebox}{Example}{teal}{\icnote}{white}
laf: 'javax.swing.plaf.nimbus.NimbusLookAndFeel'
@@ -244,7 +244,7 @@ filetypes:
\begin{messagebox}{Do not escape backslashes}{attentioncolour}{\icattention}{black}
\setlength{\parskip}{1em}
-When writing a file type pattern, there is no need for escaping backslashes as one does for strings in a typical programming language (including \gls{MVEL} expressions). In this specific scenario, key values are represented as plain, literal strings.
+When writing a file type pattern, there is no need for escaping backslashes as one does for strings in a typical programming language (including MVEL expressions). In this specific scenario, key values are represented as plain, literal strings.
However, please note that character escaping might be required by the underlying regular expression in some scenarios (i.e, a literal dot in the pattern). It is highly recommended to consult a proper regular expression documentation for a comprehensive overview.
\end{messagebox}