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.tex104
1 files changed, 97 insertions, 7 deletions
diff --git a/support/arara/doc/chapters/rules.tex b/support/arara/doc/chapters/rules.tex
index a3f10dc2af..ace21a6fad 100644
--- a/support/arara/doc/chapters/rules.tex
+++ b/support/arara/doc/chapters/rules.tex
@@ -1039,6 +1039,70 @@ This rule runs the \rbox{pdftex} \TeX\ engine on the provided \mtbox{currentFile
% arara: pdftex: { draft: 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.
+\end{description}
+
+\begin{codebox}{Example}{teal}{\icnote}{white}
+% arara: pdftk: { options: [ burst ] }
+\end{codebox}
+
+\item[\rulebox{perltex}]
+This rule runs \rbox{perltex}, a wrapper that enables a symbiosis between Perl, a popular general purpose programming language, and a \TeX\ engine, on the provided \mtbox{currentFile} reference.
+
+\begin{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 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.
+\end{description}
+
+\item[\rpsbox{safe}] This option sets whether the wrapper should enable sandboxing. When explicitly disabled, the wrapper might execute any arbitrary Perl code, including that which can harm files.
+
+\item[\abox{permit}] This option takes a list of values in which indicate particular Perl operations to be performed, enabling finer-grained control over the wrapper sandbox.
+
+\item[\rpsbox{standalone}] This option generates a specific style file to make the document suitable for distribution to users who do not have the wrapper installed. Please refer to the manual for further details on this option.
+
+\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: perltex: { safe: no, standalone: yes }
+\end{codebox}
+
\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.
@@ -1074,28 +1138,54 @@ This rule runs the \rbox{platex} \TeX\ engine on the provided \mtbox{currentFile
% 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.
+\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.
+
\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: pdftk: { options: [ burst ] }
+% arara: ps2pdf: { output: article }
\end{codebox}
-\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.
+\item[\rulebox{pythontex}]
+This rule runs \rbox{pythontex}, a wrapper that provides access to Python from within typical \TeX\ documents, on the provided \mtbox{currentFile} reference. Make sure to take a look at the documentation for further details.
\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.
+\item[\abox{encoding}] This option sets the encoding of the underlying \TeX\ document and all related files. If an encoding is not specified, Unicode is assumed.
+
+\item[\rpsbox{errorcode}] This option determines whether an exit code of 1 is returned if there were errors. On by default, but can be turned off since it is undesirable when working with some editors.
+
+\item[\rpsbox{runall}] This option sets whether all code to be executed, regardless of modification. It is useful when code has not been modified, but a dependency such as a library or external data has changed.
+
+\item[\abox{rerun}] This option, as the name indicates, sets the underlying threshold for reexecuting code. By default, the wrapper will rerun code that has been modified or that produced errors on the last run. Possible values are:
+
+\begin{description}
+\item[\povalue{never}] When this value is used, the wrapper never executes code. In this scenario, a warning is issued if there is modified code. Please refer to the documentation for further details.
+
+\item[\povalue{modified}] When this value is used, as the name indicates, the wrapper only executes code that has been modified or that has modified dependencies.
+
+\item[\povalue{errors}] When this value is used, as the name indicates, the wrapper executes code that has been modified as well as code that produced errors on the last run.
+
+\item[\povalue{warnings}] When this value is used, as the name indicates, the wrapper executes code that has been modified as well as code that produced errors or warnings on the last run.
+
+\item[\povalue{always}] When this value is used, as the name indicates, the wrapper executes all code, regardless of modification or errors and warnings. It is useful when code has not been modified, but a dependency such as a library or external data has changed.
+\end{description}
+
+\item[\rpsbox{hashdependencies}] This option, as the name suggests, determines whether dependencies are checked for changes via their hashes or modification times.
+
+\item[\abox{jobs}] This option, as the name suggests, takes an integer value denoting the maximum number of concurrent processes. By default, the wrapper relies on the number of CPUs in the system.
+
+\item[\rpsbox{verbose}] This option sets whether the wrapper should be executed in verbose mode, providing more output information, including a list of all processes that are launched.
\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: ps2pdf: { output: article }
+% arara: pythontex: { jobs: 2, verbose: yes }
\end{codebox}
\item[\rulebox{qpdf}]